@firtoz/collection-sync 1.0.0

package/src/react/constants.ts

@@ -0,0 +1,11 @@
+export const DEFAULT_PAGE_LIMIT = 50;
+export const DEFAULT_SEEK_ROW_GAP = 80;
+export const DEFAULT_SEEK_COOLDOWN_MS = 200;
+
+/** Default quiet period before coalesced predicate `rangeQuery` after viewport motion. */
+export const DEFAULT_VIEWPORT_RANGE_QUIET_MS = 72;
+/**
+ * Default max time between predicate `rangeQuery` calls while the viewport keeps changing
+ * (still issues a fetch even during continuous motion).
+ */
+export const DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS = 200;

package/src/react/index.ts

@@ -0,0 +1,50 @@
+export {
+	DEFAULT_PAGE_LIMIT,
+	DEFAULT_SEEK_COOLDOWN_MS,
+	DEFAULT_SEEK_ROW_GAP,
+	DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS,
+	DEFAULT_VIEWPORT_RANGE_QUIET_MS,
+} from "./constants";
+export type {
+	CacheDisplayMode,
+	PartialSyncCollection,
+	PartialSyncItem,
+	PartialSyncLiveCollection,
+	PartialSyncRowRef,
+	PartialSyncRowShape,
+	PartialSyncRowSlot,
+	PartialSyncRowSlotView,
+	PartialSyncRowVersion,
+	UsePartialSyncCollectionOptions,
+	UsePartialSyncCollectionResult,
+	UsePartialSyncViewportOptions,
+	UsePartialSyncViewportResult,
+	UsePartialSyncWindowOptions,
+	UsePartialSyncWindowResult,
+	UsePredicateFilteredRowsOptions,
+	ViewportInfo,
+} from "./types";
+export type {
+	CreatePartialSyncAdapterConfig,
+	NumericAxisSpec,
+	PartialSyncViewportAdapter,
+	PartialSyncViewportItem,
+	PredicateSortSpec,
+} from "./partial-sync-adapter";
+export {
+	betweenConditionsForNumericAxes,
+	createPartialSyncAdapter,
+} from "./partial-sync-adapter";
+export {
+	assertSyncUtils,
+	computeFingerprintForIndexWindow,
+	defaultPartialSyncVersionMs,
+	defaultPredicateColumnValue,
+	getPartialSyncRowByMapId,
+	matchesPredicate,
+	tryIdsForIndexWindow,
+} from "./partial-sync-utils";
+export { usePartialSyncWindow } from "./usePartialSyncWindow";
+export { usePartialSyncCollection } from "./usePartialSyncCollection";
+export { usePartialSyncViewport } from "./usePartialSyncViewport";
+export { usePredicateFilteredRows } from "./usePredicateFilteredRows";

package/src/react/partial-sync-adapter.ts

@@ -0,0 +1,73 @@
+import type { PartialSyncRowShape } from "../partial-sync-row-key";
+import type { RangeCondition, SyncRangeSort } from "../sync-protocol";
+
+/** Row shape compatible with partial-sync viewport hooks (matches {@link PartialSyncItem}). */
+export type PartialSyncViewportItem = PartialSyncRowShape;
+
+export type PredicateSortSpec<TSortColumn extends string> = {
+	column: TSortColumn;
+	direction: SyncRangeSort["direction"];
+};
+
+/**
+ * Bundles predicate ↔ viewport mapping, optional prefetch expansion, and sort accessors for
+ * {@link usePartialSyncViewport} + {@link usePredicateFilteredRows}.
+ */
+export type PartialSyncViewportAdapter<
+	TItem extends PartialSyncViewportItem,
+	TViewport,
+	TSortColumn extends keyof TItem & string,
+> = {
+	toConditions: (viewport: TViewport) => RangeCondition[];
+	expandViewport: (viewport: TViewport, pad: number) => TViewport;
+	sort: PredicateSortSpec<TSortColumn>;
+	getSortValue: (row: TItem, column: TSortColumn) => unknown;
+};
+
+export type CreatePartialSyncAdapterConfig<
+	TItem extends PartialSyncViewportItem,
+	TViewport,
+	TSortColumn extends keyof TItem & string,
+> = {
+	toConditions: (viewport: TViewport) => RangeCondition[];
+	/** Widen viewport before server `rangeQuery`. Default: identity (no prefetch). */
+	expandViewport?: (viewport: TViewport, pad: number) => TViewport;
+	sort: PredicateSortSpec<TSortColumn>;
+	getSortValue: (row: TItem, column: TSortColumn) => unknown;
+};
+
+export function createPartialSyncAdapter<
+	TItem extends PartialSyncViewportItem,
+	TViewport,
+	TSortColumn extends keyof TItem & string,
+>(
+	config: CreatePartialSyncAdapterConfig<TItem, TViewport, TSortColumn>,
+): PartialSyncViewportAdapter<TItem, TViewport, TSortColumn> {
+	return {
+		toConditions: config.toConditions,
+		expandViewport: config.expandViewport ?? ((v) => v),
+		sort: config.sort,
+		getSortValue: config.getSortValue,
+	};
+}
+
+export type NumericAxisSpec<TViewport> = {
+	readonly column: string;
+	readonly min: (viewport: TViewport) => number;
+	readonly max: (viewport: TViewport) => number;
+};
+
+/**
+ * Builds `between` {@link RangeCondition}s from numeric axis accessors (N-D box / interval per column).
+ */
+export function betweenConditionsForNumericAxes<TViewport>(
+	viewport: TViewport,
+	axes: readonly NumericAxisSpec<TViewport>[],
+): RangeCondition[] {
+	return axes.map((axis) => ({
+		column: axis.column,
+		op: "between" as const,
+		value: axis.min(viewport),
+		valueTo: axis.max(viewport),
+	}));
+}

package/src/react/partial-sync-utils.ts

@@ -0,0 +1,115 @@
+import type { CollectionUtils } from "@firtoz/db-helpers";
+import type { UtilsRecord } from "@tanstack/db";
+import type { RangeFingerprint } from "../sync-protocol";
+import type { PartialSyncCollection, PartialSyncItem } from "./types";
+
+/** Merge every row currently in the collection into the bridge cache (id set only). Idempotent. */
+export function primePartialSyncBridgeCachedIdsFromCollection<
+	TItem extends PartialSyncItem,
+>(
+	bridge: { seedHydratedLocalRows: (rows: readonly TItem[]) => void },
+	collection: Pick<PartialSyncCollection<TItem>, "entries">,
+): void {
+	bridge.seedHydratedLocalRows(Array.from(collection.entries(), ([, v]) => v));
+}
+
+/**
+ * TanStack `Collection` types `utils` as {@link UtilsRecord}. This narrows to sync helpers when
+ * present (e.g. after `memoryCollectionOptions` / Drizzle sync config).
+ */
+export function assertSyncUtils<TItem>(
+	utils: UtilsRecord,
+): CollectionUtils<TItem> {
+	const receiveSync = utils.receiveSync;
+	const truncate = utils.truncate;
+	if (typeof receiveSync === "function" && typeof truncate === "function") {
+		return {
+			receiveSync: receiveSync as CollectionUtils<TItem>["receiveSync"],
+			truncate: truncate as CollectionUtils<TItem>["truncate"],
+		};
+	}
+	throw new Error(
+		"Partial sync requires collection.utils.receiveSync and collection.utils.truncate",
+	);
+}
+
+/** Default fingerprint version: max `updatedAt` as epoch ms. */
+export function defaultPartialSyncVersionMs<TItem extends PartialSyncItem>(
+	row: TItem,
+): number {
+	const v = row.updatedAt;
+	if (v === null) return 0;
+	if (v instanceof Date) return v.getTime();
+	if (typeof v === "number") return v;
+	return 0;
+}
+
+/**
+ * Resolve a row for an id stored in the partial-sync index map. Uses {@link PartialSyncCollection.get}
+ * first; if that misses (e.g. key type / boxed string mismatch vs TanStack’s internal map), scans
+ * {@link PartialSyncCollection.entries} by `String(key)`.
+ */
+export function getPartialSyncRowByMapId<TItem extends PartialSyncItem>(
+	collection: PartialSyncCollection<TItem>,
+	id: string | number,
+): TItem | undefined {
+	const direct = collection.get(id);
+	if (direct !== undefined) return direct;
+	const sid = String(id);
+	for (const [k, row] of collection.entries()) {
+		if (String(k) === sid) return row;
+	}
+	return undefined;
+}
+
+/**
+ * Returns consecutive row ids for `[offset, offset + want)` if all present in the map; else null.
+ */
+export function tryIdsForIndexWindow<TKey extends string | number>(
+	map: Map<number, TKey>,
+	offset: number,
+	want: number,
+	totalCount: number,
+): TKey[] | null {
+	if (totalCount === 0) return null;
+	const n = Math.min(want, Math.max(0, totalCount - offset));
+	if (n === 0) return [];
+	const out: TKey[] = [];
+	for (let i = 0; i < n; i += 1) {
+		const id = map.get(offset + i);
+		if (id === undefined) return null;
+		out.push(id);
+	}
+	return out;
+}
+
+/**
+ * Fingerprint for reconciliation when every index in `[offset, offset + want)` is mapped and rows
+ * exist in the collection.
+ */
+export function computeFingerprintForIndexWindow<TItem extends PartialSyncItem>(
+	collection: PartialSyncCollection<TItem>,
+	map: Map<number, string | number>,
+	offset: number,
+	want: number,
+	getVersionMs: (row: TItem) => number = defaultPartialSyncVersionMs,
+): RangeFingerprint | undefined {
+	if (want <= 0) return undefined;
+	let maxV = 0;
+	let count = 0;
+	for (let i = 0; i < want; i += 1) {
+		const id = map.get(offset + i);
+		if (id === undefined) return undefined;
+		const row = getPartialSyncRowByMapId(collection, id);
+		if (row === undefined) return undefined;
+		count += 1;
+		const ms = getVersionMs(row);
+		if (ms > maxV) maxV = ms;
+	}
+	return { version: maxV, count };
+}
+
+export {
+	defaultPredicateColumnValue,
+	matchesPredicate,
+} from "../partial-sync-predicate-match";

package/src/react/range-conditions-expression.ts

@@ -0,0 +1,70 @@
+import { and, eq, gt, gte, lt, lte, not, type Ref } from "@tanstack/db";
+import { exhaustiveGuard } from "@firtoz/maybe-error";
+import type { PartialSyncRowShape } from "../partial-sync-row-key";
+import type { RangeCondition } from "../sync-protocol";
+
+/**
+ * Row ref from `q.from({ items: collection }).where(({ items }) => …)`.
+ * Column access must match {@link RangeCondition.column} names on the stored row shape.
+ *
+ * Uses TanStack {@link Ref} so column reads are `ExpressionLike` (e.g. for `inArray`), not `unknown`.
+ */
+export type PredicateRowRef = Ref<
+	PartialSyncRowShape & Record<string, unknown>
+>;
+
+/**
+ * Row accepted by {@link buildRangeConditionsAndExpression}: live query refs or plain objects (e.g. tests).
+ * Dynamic `column` access yields `unknown`, which TanStack comparison helpers still accept.
+ */
+export type PredicateRangeBuildRow = PredicateRowRef | Record<string, unknown>;
+
+/**
+ * Builds a TanStack DB `where` expression AND-ing all conditions (same semantics as
+ * {@link matchesPredicate} for plain property rows).
+ */
+export function buildRangeConditionsAndExpression(
+	row: PredicateRangeBuildRow,
+	conditions: RangeCondition[],
+) {
+	if (conditions.length === 0) {
+		throw new Error(
+			"buildRangeConditionsAndExpression: pass a non-empty conditions list",
+		);
+	}
+	const parts = conditions.map((c) => rangeConditionExpression(row, c));
+	if (parts.length === 1) {
+		return parts[0];
+	}
+	const [a, b, ...rest] = parts;
+	return rest.length === 0 ? and(a, b) : and(a, b, ...rest);
+}
+
+function rangeConditionExpression(
+	row: PredicateRangeBuildRow,
+	c: RangeCondition,
+) {
+	const col = row[c.column];
+	switch (c.op) {
+		case "eq":
+			return eq(col, c.value);
+		case "neq":
+			return not(eq(col, c.value));
+		case "gt":
+			return gt(col, c.value);
+		case "gte":
+			return gte(col, c.value);
+		case "lt":
+			return lt(col, c.value);
+		case "lte":
+			return lte(col, c.value);
+		case "between": {
+			if (c.valueTo === undefined) {
+				throw new Error(`between requires valueTo for column ${c.column}`);
+			}
+			return and(gte(col, c.value), lte(col, c.valueTo));
+		}
+		default:
+			exhaustiveGuard(c.op);
+	}
+}

package/src/react/types.ts

@@ -0,0 +1,232 @@
+import type { Collection, UtilsRecord } from "@tanstack/db";
+import type { CacheManager } from "../cache-manager";
+import type {
+	PartialSyncClientBridge,
+	PartialSyncReconcileResult,
+	PartialSyncState,
+} from "../partial-sync-client-bridge";
+import type { PartialSyncViewportAdapter } from "./partial-sync-adapter";
+import type { ConnectPartialSyncTransport } from "../connect-partial-sync";
+import type { SyncClientBridge } from "../sync-client-bridge";
+import type { PartialSyncRowShape } from "../partial-sync-row-key";
+import type { RangeCondition, SyncClientMessage } from "../sync-protocol";
+
+export type {
+	PartialSyncRowRef,
+	PartialSyncRowShape,
+	PartialSyncRowVersion,
+} from "../partial-sync-row-key";
+
+/** Row shape for partial-sync React hooks (mandatory `updatedAt` for fingerprints / reconciliation). */
+export type PartialSyncItem = PartialSyncRowShape;
+
+/**
+ * Minimal collection surface for partial-sync window hooks (TanStack `Collection` satisfies this
+ * when `get` / `entries` are typed consistently).
+ */
+export type PartialSyncCollection<TItem extends PartialSyncItem> = {
+	get(key: string | number): TItem | undefined;
+	subscribeChanges(
+		callback: (changes: unknown[]) => void,
+		options?: { includeInitialState?: boolean },
+	): { unsubscribe: () => void };
+	entries(): IterableIterator<[string | number, TItem]>;
+	/** TanStack collections use `UtilsRecord`; runtime must include `receiveSync` / `truncate`. */
+	utils: UtilsRecord;
+};
+
+export type ViewportInfo = {
+	firstVisibleIndex: number;
+	lastVisibleIndex: number;
+};
+
+/** Per global row index: where the cell’s data comes from (for UI / debugging). */
+export type PartialSyncRowSlot =
+	| "ready"
+	| "ready_global"
+	| "stale_map"
+	| "server"
+	| "none";
+
+export type PartialSyncRowSlotView<TItem extends PartialSyncItem> = {
+	row: TItem | undefined;
+	slot: PartialSyncRowSlot;
+};
+
+export type UsePartialSyncWindowOptions<
+	TItem extends PartialSyncItem,
+	TSortColumn extends keyof TItem & string = keyof TItem & string,
+> = {
+	collection: PartialSyncCollection<TItem>;
+	sort: { column: TSortColumn; direction: "asc" | "desc" };
+	getSortValue: (row: TItem, column: TSortColumn) => unknown;
+
+	wsUrl: string;
+	wsTransport?: ConnectPartialSyncTransport;
+	/** Use a module-level function or `useCallback`; inline arrows are a new reference every render. */
+	serializeJson?: (value: unknown) => string;
+	/** Use a module-level function or `useCallback`; inline arrows are a new reference every render. */
+	deserializeJson?: (raw: string) => unknown;
+
+	getVersionMs?: (row: TItem) => number;
+	getSortPositions?: (row: TItem) => Record<string, unknown>;
+
+	pageLimit?: number;
+	seekCooldownMs?: number;
+	/**
+	 * Stable id for the **logical** collection instance (e.g. `${backend}-${roomId}`). The partial
+	 * window resets (truncate + index map) when this or {@link sort} changes — **not** when the
+	 * TanStack `collection` reference churns. Omit only if the collection instance is stable for the
+	 * hook lifetime; otherwise local edits can spuriously reset the window.
+	 */
+	partialWindowResetKey?: string;
+	/**
+	 * When set, `mutateBatch` / ack / `syncBatch` route through this bridge; `clientId` matches
+	 * {@link PartialSyncClientBridge}. Use with {@link createPartialSyncedCollection} / {@link withSync}.
+	 */
+	mutationBridge?: SyncClientBridge<TItem>;
+	/**
+	 * Called once when the WebSocket transport `send` is ready (same function {@link withSync} / mutation bridge use).
+	 */
+	mergeTransportSend?: (send: (msg: SyncClientMessage) => void) => void;
+	/**
+	 * Must match the server's partial-sync {@link PartialSyncServerBridgeOptions.collectionId} and align with
+	 * {@link SyncClientBridgeOptions.collectionId} on {@link mutationBridge}.
+	 */
+	collectionId?: string;
+	/**
+	 * `confirmed` filters dense `rows` to {@link PartialSyncClientBridge.serverConfirmedKeys} only
+	 * (same semantics as {@link UsePartialSyncViewportOptions.cacheDisplayMode}).
+	 */
+	cacheDisplayMode?: CacheDisplayMode;
+};
+
+export type UsePartialSyncWindowResult<TItem extends PartialSyncItem> = {
+	rows: TItem[];
+	windowStartIndex: number;
+	totalCount: number;
+	/**
+	 * True while a server `requestRangeQuery` is in flight (cursor append or offset seek).
+	 * False for cache-only window moves (`tryIds` / fingerprint `upToDate` without a round-trip).
+	 */
+	rangeRequestInFlight: boolean;
+	hasMore: boolean;
+	bridgeState: PartialSyncState;
+	bridge: PartialSyncClientBridge<TItem>;
+	cacheManager: CacheManager<TItem>;
+	fetchNext: () => Promise<void>;
+	seekToViewport: (
+		firstVisibleIndex: number,
+		opts?: {
+			scrollSettled?: boolean;
+			lastVisibleIndex?: number;
+			/** Skip density/cooldown short-circuits (e.g. index map out of sync with collection). */
+			force?: boolean;
+		},
+	) => void;
+	seekAfterScrollSettled: (
+		firstVisibleIndex: number,
+		lastVisibleIndex?: number,
+	) => void;
+	viewportInfo: ViewportInfo;
+	setViewportInfo: (info: ViewportInfo) => void;
+	lastSeekMeta: {
+		offset: number;
+		reason: "scroll" | "scrollSettled";
+	} | null;
+	/**
+	 * Resolve one global index via index map + collection, and classify the cell.
+	 * Use this for row UI so cached rows still render when the dense `rows` window has not caught up.
+	 */
+	getRowSlot: (globalIndex: number) => PartialSyncRowSlotView<TItem>;
+};
+
+/** Collection usable with {@link useLiveQuery} and partial-sync helpers. */
+export type PartialSyncLiveCollection<TItem extends PartialSyncItem> =
+	PartialSyncCollection<TItem> &
+		Collection<TItem, string | number, UtilsRecord>;
+
+export type CacheDisplayMode = "immediate" | "confirmed";
+
+export type UsePredicateFilteredRowsOptions<
+	TItem extends PartialSyncItem,
+	TSortColumn extends keyof TItem & string = keyof TItem & string,
+> = {
+	collection: PartialSyncLiveCollection<TItem>;
+	conditions: RangeCondition[];
+	sort: { column: TSortColumn; direction: "asc" | "desc" };
+	getSortValue: (row: TItem, column: TSortColumn) => unknown;
+	/**
+	 * For predicate `column` strings when using a custom row shape; the live-query path reads
+	 * properties named in {@link RangeCondition.column} on each row (same as default column read).
+	 */
+	getColumnValue?: (row: TItem, column: string) => unknown;
+	limit?: number;
+	/**
+	 * `immediate`: show all rows matching the predicate (including cache-only).
+	 * `confirmed`: only rows whose keys appear in {@link confirmedRowKeys} (from the bridge).
+	 */
+	cacheDisplayMode?: CacheDisplayMode;
+	/** Required when `cacheDisplayMode` is `"confirmed"`; typically `bridge.serverConfirmedKeys`. */
+	confirmedRowKeys?: ReadonlySet<string | number>;
+	/** Pass `bridge.serverConfirmedKeysRevision` so React re-runs the query when the set mutates. */
+	confirmedKeysRevision?: number;
+	/**
+	 * Row ids that stay visible even when they no longer match the viewport predicate (union with
+	 * predicate hits). Useful for in-progress drags or pinned selections. Rows must already exist
+	 * in the local collection.
+	 */
+	alwaysIncludeRowIds?: readonly string[];
+};
+
+export type UsePartialSyncCollectionOptions<TItem extends PartialSyncItem> = {
+	collection: PartialSyncCollection<TItem>;
+	mutationBridge: SyncClientBridge<TItem>;
+	wsUrl: string;
+	wsTransport?: ConnectPartialSyncTransport;
+	serializeJson?: (value: unknown) => string;
+	deserializeJson?: (raw: string) => unknown;
+	mergeTransportSend?: (send: (msg: SyncClientMessage) => void) => void;
+	collectionId?: string;
+	beforeApplyRows?: (rows: TItem[]) => Promise<void>;
+};
+
+export type UsePartialSyncCollectionResult<TItem extends PartialSyncItem> = {
+	bridge: PartialSyncClientBridge<TItem>;
+	bridgeState: PartialSyncState;
+};
+
+export type UsePartialSyncViewportOptions<
+	TItem extends PartialSyncItem,
+	TViewport,
+	TSortColumn extends keyof TItem & string,
+> = {
+	bridge: PartialSyncClientBridge<TItem>;
+	/** From {@link usePartialSyncCollection}; drives {@link UsePartialSyncViewportResult.totalCount}. */
+	bridgeState: PartialSyncState;
+	collection: PartialSyncLiveCollection<TItem>;
+	adapter: PartialSyncViewportAdapter<TItem, TViewport, TSortColumn>;
+	viewport: TViewport;
+	predicateLimit: number;
+	prefetchPad?: number;
+	quietMs?: number;
+	maxWaitMs?: number;
+	/**
+	 * Used when the bridge has not yet reported `totalCount` (e.g. world size for sparse grids).
+	 */
+	totalCountFallback?: number;
+	getColumnValue?: (row: TItem, column: string) => unknown;
+	cacheDisplayMode?: CacheDisplayMode;
+	/**
+	 * Ids to always include in {@link UsePartialSyncViewportResult.viewportRows} in addition to
+	 * rows matching the viewport predicate (see {@link UsePredicateFilteredRowsOptions.alwaysIncludeRowIds}).
+	 */
+	alwaysIncludeRowIds?: readonly string[];
+	/** After a successful manifest reconcile (re-entry with cached keys), receive `movedHints` etc. */
+	onRangeReconcile?: (result: PartialSyncReconcileResult<TItem>) => void;
+};
+
+export type UsePartialSyncViewportResult<TItem extends PartialSyncItem> = {
+	viewportRows: TItem[];
+	totalCount: number;
+};

package/src/react/usePartialSyncCollection.ts

@@ -0,0 +1,140 @@
+import { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { connectPartialSync } from "../connect-partial-sync";
+import { PartialSyncClientBridge } from "../partial-sync-client-bridge";
+import type { PartialSyncState } from "../partial-sync-client-bridge";
+import type { SyncClientMessage } from "../sync-protocol";
+import {
+	assertSyncUtils,
+	getPartialSyncRowByMapId,
+	primePartialSyncBridgeCachedIdsFromCollection,
+} from "./partial-sync-utils";
+import type {
+	PartialSyncItem,
+	UsePartialSyncCollectionOptions,
+	UsePartialSyncCollectionResult,
+} from "./types";
+
+/**
+ * WebSocket + {@link PartialSyncClientBridge} wiring shared by predicate viewports and custom UIs.
+ * Pair with {@link usePartialSyncViewport} for N-dimensional `rangeQuery` + local predicate rows.
+ */
+export function usePartialSyncCollection<TItem extends PartialSyncItem>({
+	collection,
+	mutationBridge,
+	wsUrl,
+	wsTransport = "json",
+	serializeJson = JSON.stringify,
+	deserializeJson = JSON.parse,
+	mergeTransportSend,
+	collectionId,
+	beforeApplyRows,
+}: UsePartialSyncCollectionOptions<TItem>): UsePartialSyncCollectionResult<TItem> {
+	const [bridgeState, setBridgeState] = useState<PartialSyncState>({
+		status: "offline",
+	});
+
+	const syncUtils = useMemo(
+		() => assertSyncUtils<TItem>(collection.utils),
+		[collection],
+	);
+	const syncUtilsRef = useRef(syncUtils);
+	syncUtilsRef.current = syncUtils;
+
+	const partialClientId = mutationBridge.clientId;
+
+	const collectionRef = useRef(collection);
+	collectionRef.current = collection;
+
+	const bridge = useMemo(
+		() =>
+			new PartialSyncClientBridge<TItem>({
+				clientId: partialClientId,
+				...(collectionId !== undefined ? { collectionId } : {}),
+				collection: {
+					get: (key) => getPartialSyncRowByMapId(collectionRef.current, key),
+					utils: {
+						receiveSync: (messages) =>
+							syncUtilsRef.current.receiveSync(messages),
+					},
+				},
+				send: () => {},
+				onStateChange: (state) => {
+					setBridgeState(state);
+				},
+				...(beforeApplyRows !== undefined ? { beforeApplyRows } : {}),
+			}),
+		[beforeApplyRows, collectionId, partialClientId],
+	);
+
+	const serializeJsonRef = useRef(serializeJson);
+	serializeJsonRef.current = serializeJson;
+	const deserializeJsonRef = useRef(deserializeJson);
+	deserializeJsonRef.current = deserializeJson;
+	const mutationBridgeRef = useRef(mutationBridge);
+	mutationBridgeRef.current = mutationBridge;
+	const mergeTransportSendRef = useRef(mergeTransportSend);
+	mergeTransportSendRef.current = mergeTransportSend;
+
+	/**
+	 * Keep the object returned by `subscribeChanges` and call `.unsubscribe()` on it. Destructuring
+	 * `{ unsubscribe }` drops the method receiver, so TanStack's `unsubscribe()` runs with `this === undefined`
+	 * and throws (e.g. reading `truncateCleanup`).
+	 *
+	 * Declare this layout effect before the WebSocket one so teardown runs `unsubscribe` before
+	 * `disconnect` (layout cleanups run in declaration order in practice).
+	 */
+	useLayoutEffect(() => {
+		primePartialSyncBridgeCachedIdsFromCollection(bridge, collection);
+		let cancelled = false;
+		let seeded = false;
+		const trySeed = () => {
+			if (cancelled || seeded) return;
+			const rows = Array.from(collection.entries(), ([, v]) => v);
+			if (rows.length === 0) return;
+			bridge.seedHydratedLocalRows(rows);
+			seeded = true;
+		};
+		const changeSubscription = collection.subscribeChanges(trySeed, {
+			includeInitialState: true,
+		});
+		queueMicrotask(trySeed);
+		let intervalId: ReturnType<typeof setInterval> | undefined;
+		intervalId = setInterval(() => {
+			trySeed();
+			if (seeded && intervalId !== undefined) {
+				clearInterval(intervalId);
+				intervalId = undefined;
+			}
+		}, 50);
+		const stopId = setTimeout(() => {
+			if (intervalId !== undefined) {
+				clearInterval(intervalId);
+			}
+		}, 10_000);
+		return () => {
+			cancelled = true;
+			changeSubscription.unsubscribe();
+			if (intervalId !== undefined) clearInterval(intervalId);
+			clearTimeout(stopId);
+		};
+	}, [bridge, collection]);
+
+	useLayoutEffect(() => {
+		const disconnect = connectPartialSync(bridge, {
+			url: wsUrl,
+			transport: wsTransport,
+			setTransportSend: (send) => {
+				bridge.setSend((message: SyncClientMessage) => send(message));
+				mergeTransportSendRef.current?.(send);
+			},
+			serializeJson: (value: unknown) => serializeJsonRef.current(value),
+			deserializeJson: (raw: string) => deserializeJsonRef.current(raw),
+			mutationBridge: mutationBridgeRef.current,
+		});
+		return () => {
+			disconnect();
+		};
+	}, [bridge, wsTransport, wsUrl]);
+
+	return { bridge, bridgeState };
+}