reflectdb 0.1.3 → 0.2.0

package/dist/cjs/htmx/index.d.cts

@@ -0,0 +1,760 @@
+type OpType = "insert" | "update" | "delete";
+type OpStatus = "pending" | "synced" | "rejected";
+/**
+* Server-side conflict policy for concurrent writes to the same row.
+*
+* Scope note for `"merge"`: the server resolves per column using the **client
+* op HLCs** recorded in reflectdb's mirror, so two clients editing different
+* fields both land. The per-column clocks the client sees on a broadcast are a
+* different domain — a diff-driven broadcast can't attribute a column to the
+* op that produced it, so every column changed in one broadcast carries that
+* broadcast's HLC. Client-side merge therefore orders *broadcasts* against each
+* other and against local optimistic state; it does not reconstruct per-column
+* causality between clients. Column-level convergence is a server guarantee.
+*/
+type ConflictPolicy = "lww" | "merge" | "server" | CustomConflictPolicy;
+interface CustomConflictPolicy {
+	policy: "custom";
+	resolve: ConflictResolver;
+}
+interface ConflictResolver {
+	(incoming: {
+		op: OpType;
+		payload: Record<string, unknown> | null;
+		hlc: string;
+	}, existing: {
+		row: Record<string, unknown>;
+		colClocks: Record<string, string>;
+	}, meta: {
+		table: string;
+		rowId: string;
+		userId: string;
+	}): {
+		row: Record<string, unknown>;
+	};
+}
+type ErrorReason = "outside_shape" | "readonly_query" | "rate_limited" | "buffer_full" | "server_conflict" | "custom_conflict" | "merge_stale" | "clock_drift" | "replay" | "batch_too_large" | "schema_outdated" | "auth_revoked" | "compacted" | "mutation_rejected" | "server_error" | "unknown_query";
+interface HelloMessage {
+	type: "hello";
+	/** Highest protocol version the client prefers. Retained for back-compat. */
+	protocolVersion: number;
+	/** All versions the client can speak. Omit for legacy single-version clients. */
+	supportedVersions?: readonly number[];
+	clientId: string;
+	token: string;
+}
+interface BootstrapMessage {
+	type: "bootstrap";
+	syncParams?: Record<string, Record<string, unknown>>;
+}
+interface ResumeMessage {
+	type: "resume";
+	since: string;
+}
+interface OpsMessage {
+	type: "ops";
+	ops: ClientOp[];
+	token: string;
+}
+interface ClientOp {
+	id: string;
+	table: string;
+	op: OpType;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	hlc: string;
+	batchId?: string;
+	batchSize?: number;
+	batchSeq?: number;
+}
+interface SyncDeclareMessage {
+	type: "sync_declare";
+	table: string;
+	params?: Record<string, unknown>;
+	window?: number;
+}
+interface LoadMoreMessage {
+	type: "load_more";
+	table: string;
+	count: number;
+}
+interface UnsyncMessage {
+	type: "unsync";
+	table: string;
+}
+interface AuthMessage {
+	type: "auth";
+	token: string;
+}
+interface EphemeralMessage {
+	type: "ephemeral";
+	key: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+}
+interface HelloAckMessage {
+	type: "hello_ack";
+	protocolVersion: number;
+	serverId: string;
+}
+interface HelloRejectMessage {
+	type: "hello_reject";
+	reason: string;
+	supported: number[];
+}
+interface SnapshotMessage {
+	type: "snapshot";
+	table: string;
+	rows: Record<string, unknown>[];
+	colClocks: Record<string, Record<string, string>>;
+	append?: boolean;
+	totalCount?: number;
+	/**
+	* Primary key column name for this table. Self-contained per message so the
+	* client doesn't depend on `bootstrap_complete.tableMeta` arriving first.
+	* When omitted (older servers), the client falls back to tableMeta, then "id".
+	*/
+	pk?: string;
+}
+interface BootstrapCompleteMessage {
+	type: "bootstrap_complete";
+	serverHlc: string;
+	tableMeta: Record<string, TableMeta>;
+}
+interface TableMeta {
+	serverSet: string[];
+	readonly: string[];
+	broadcast: "consistent" | "eager" | "eager-durable";
+	/** Primary key column name. Defaults to "id" when omitted (older servers). */
+	pk?: string;
+}
+interface DeltaMessage {
+	type: "delta";
+	table: string;
+	op: OpType;
+	rowId: string;
+	payload: Record<string, unknown> | null;
+	hlc: string;
+	colClocks?: Record<string, string>;
+}
+interface AckMessage {
+	type: "ack";
+	opIds: string[];
+}
+interface RejectMessage {
+	type: "reject";
+	opId?: string;
+	batchId?: string;
+	reason: ErrorReason;
+	serverRow?: Record<string, unknown>;
+}
+interface ResumeCompleteMessage {
+	type: "resume_complete";
+	serverHlc: string;
+}
+interface ResumeRejectedMessage {
+	type: "resume_rejected";
+	reason: string;
+	serverHlc: string;
+}
+interface ShapeChangedMessage {
+	type: "shape_changed";
+	table: string;
+	reason: "auth_changed" | "params_changed" | "server_policy";
+}
+interface DisconnectMessage {
+	type: "disconnect";
+	reason: string;
+}
+interface ReauthMessage {
+	type: "reauth";
+}
+interface CountChangedMessage {
+	type: "count_changed";
+	table: string;
+	totalCount: number;
+}
+interface EphemeralEvent {
+	type: "ephemeral";
+	key: string;
+	clientId: string;
+	userId: string;
+	data: Record<string, unknown>;
+	ttlMs?: number;
+}
+type ClientMessage = HelloMessage | BootstrapMessage | ResumeMessage | OpsMessage | SyncDeclareMessage | LoadMoreMessage | UnsyncMessage | AuthMessage | EphemeralMessage;
+type ServerMessage = HelloAckMessage | HelloRejectMessage | SnapshotMessage | BootstrapCompleteMessage | DeltaMessage | AckMessage | RejectMessage | ResumeCompleteMessage | ResumeRejectedMessage | ShapeChangedMessage | DisconnectMessage | ReauthMessage | EphemeralEvent | CountChangedMessage;
+interface ClientTransport {
+	send(message: ClientMessage): Promise<void>;
+	subscribe(handler: (message: ServerMessage) => void): void;
+	close(): Promise<void>;
+}
+interface ClientStorageAdapter {
+	getRows(table: string): Promise<LocalRow[]>;
+	getAllRows(): Promise<LocalRow[]>;
+	putRow(table: string, rowId: string, row: LocalRow): Promise<void>;
+	deleteRow(table: string, rowId: string): Promise<void>;
+	clearTable(table: string): Promise<void>;
+	getPendingOps(): Promise<PendingOp[]>;
+	putPendingOps(ops: PendingOp[]): Promise<void>;
+	appendPendingOps(ops: PendingOp[]): Promise<void>;
+	updatePendingOps(ops: PendingOp[]): Promise<void>;
+	removePendingOps(opIds: string[]): Promise<void>;
+	clearPendingOps(): Promise<void>;
+	getMeta(key: string): Promise<string | null>;
+	setMeta(key: string, value: string): Promise<void>;
+	deleteMeta(key: string): Promise<void>;
+	clear(): Promise<void>;
+}
+interface PendingOp {
+	op: ClientOp;
+	status: OpStatus;
+	rejectedReason: ErrorReason | null;
+	createdAt: number;
+	/**
+	* Row state captured just before the optimistic apply. Restored on reject
+	* so a rejected optimistic insert collapses back to no-row (instead of
+	* leaving a tombstone), and a rejected update reverts to the merged row
+	* the client had before touching it.
+	*/
+	preState?: {
+		data: Record<string, unknown> | null;
+		colClocks: Record<string, string>;
+		serverHlc: string | null;
+	} | null;
+}
+interface LocalRow {
+	table: string;
+	rowId: string;
+	data: Record<string, unknown> | null;
+	colClocks: Record<string, string>;
+	serverHlc: string | null;
+}
+declare class ClientStore {
+	private pendingOps;
+	private rows;
+	private tableMeta;
+	private storage;
+	private pendingWrites;
+	private writeChain;
+	constructor(storage?: ClientStorageAdapter);
+	/**
+	* Load durable state into memory.
+	*
+	* @param options.tables — hydrate only these tables. Rows only ever reach
+	*   local storage through a subscription, so restoring just the tables the
+	*   client is actually subscribed to reads no less than it needs. Omit to
+	*   load every row of every table the client has ever synced.
+	*/
+	hydrate(options?: {
+		tables?: string[];
+	}): Promise<void>;
+	flush(): Promise<void>;
+	private enqueue;
+	addPendingOp(op: ClientOp): void;
+	getPendingOps(): PendingOp[];
+	markSynced(opIds: string[]): void;
+	markRejected(opId: string, reason: ErrorReason): void;
+	rejectBatch(batchId: string, reason: ErrorReason): void;
+	private autoTrimRejected;
+	clearRejected(): void;
+	setRow(table: string, rowId: string, data: Record<string, unknown> | null, colClocks: Record<string, string>, serverHlc: string | null): void;
+	getRow(table: string, rowId: string): LocalRow | undefined;
+	/** Internal: includes tombstones for HLC comparison in applyDelta. */
+	private getRowEntry;
+	getRows(table: string, includeDeleted?: boolean): LocalRow[];
+	clearTable(table: string): void;
+	applySnapshot(table: string, rows: Record<string, unknown>[], colClocks: Record<string, Record<string, string>>, append?: boolean, pk?: string): void;
+	applyDelta(table: string, op: string, rowId: string, payload: Record<string, unknown> | null, hlc: string, colClocks?: Record<string, string>): void;
+	/**
+	* Guarantee a materialized row carries its own primary key.
+	*
+	* A delta's payload is not always a whole row: eager broadcasts forward the
+	* writer's payload verbatim, and the typed API omits the pk from what a
+	* client may write — so an eagerly-broadcast insert describes a row with no
+	* id in it. Rows are addressed by `rowId` everywhere in the protocol, so the
+	* key is never in doubt; only the materialized object was missing it, and
+	* `rows.map(r => r.id)` came back undefined.
+	*/
+	private withPk;
+	revertOp(opId: string, serverRow: Record<string, unknown> | null | undefined): void;
+	setTableMeta(meta: Record<string, {
+		serverSet: string[];
+		readonly: string[];
+		broadcast?: "consistent" | "eager" | "eager-durable";
+		pk?: string;
+	}>): void;
+	getTableMeta(table: string): {
+		serverSet: string[];
+		readonly: string[];
+		broadcast: "consistent" | "eager" | "eager-durable";
+		pk: string;
+	} | undefined;
+	applyOptimistic(op: ClientOp): void;
+	clear(): Promise<void>;
+}
+interface SyncClientConfig {
+	clientId: string;
+	transport: ClientTransport;
+	token: string;
+	storage?: ClientStorageAdapter;
+	onSync?: (table: string) => void;
+	/**
+	* Structured error callback. `reason` is drawn from the protocol's
+	* ErrorReason taxonomy when the error originates server-side; local
+	* failures (reauth/transport) use a "local:*" namespace so consumers
+	* can switch on the string.
+	*/
+	onError?: (error: {
+		opId?: string;
+		batchId?: string;
+		table?: string;
+		reason: ErrorReason | `local:${string}`;
+		message?: string;
+	}) => void;
+	onReauth?: () => Promise<string>;
+	/** Max reconnect backoff in ms (before jitter). Default: 30_000. */
+	maxReconnectDelayMs?: number;
+	/**
+	* Load every stored row at boot instead of only the tables this client is
+	* subscribed to. Needed only if you read rows for a table before calling
+	* `sync()` on it. Default: false.
+	*/
+	hydrateAllTables?: boolean;
+}
+type SyncClientState = "hydrating" | "disconnected" | "connecting" | "connected" | "bootstrapping" | "synced";
+interface SyncOptions {
+	window?: number;
+}
+declare class SyncClient {
+	private config;
+	private transport;
+	private opCreator;
+	private store;
+	private state;
+	/** Version agreed on in hello_ack. Null until first successful handshake. */
+	private negotiatedProtocolVersion;
+	private syncedTables;
+	private serverHlc;
+	private listeners;
+	private version;
+	private tableVersions;
+	private tableListeners;
+	private connectResolve;
+	private connectReject;
+	private connectInFlight;
+	private ephemeralListeners;
+	private totalCounts;
+	private syncOptions;
+	private bootstrapScheduled;
+	private initialized;
+	private syncParams;
+	private reconnectTimer;
+	private reconnectAttempts;
+	private closed;
+	/**
+	* Ops already transmitted, mapped to when they were sent. Without this,
+	* every mutation re-sends the whole pending set: 50 rapid edits before the
+	* first ack land as 1+2+…+50 = 1275 ops on the wire, each one a `reserveOp`
+	* insert server-side. Cleared on disconnect so a reconnect resends them.
+	*/
+	private inFlightOps;
+	/**
+	* How long an op may sit unacked before a later push retries it. A frame can
+	* be dropped without the connection dying — a full server-side queue, for
+	* one — and without this the op would stay marked in-flight, never re-sent,
+	* until the connection happens to drop. Resends are idempotent server-side.
+	*/
+	private static readonly IN_FLIGHT_TTL_MS;
+	/** Tail of the serialized push chain; also the coalescing slot. */
+	private pushChain;
+	private pushPending;
+	constructor(config: SyncClientConfig);
+	init(): Promise<void>;
+	connect(): Promise<void>;
+	close(): Promise<void>;
+	getState(): SyncClientState;
+	/** Version negotiated with the server. Null before the first hello_ack. */
+	getProtocolVersion(): number | null;
+	sync(table: string, params?: Record<string, unknown>, options?: SyncOptions): Promise<void>;
+	loadMore(table: string, count: number): Promise<void>;
+	getTotalCount(table: string): number | null;
+	unsync(table: string): Promise<void>;
+	bootstrap(): Promise<void>;
+	/**
+	* Schedule a bootstrap in the next microtask.
+	* Multiple calls within the same tick are coalesced into one bootstrap.
+	*/
+	scheduleBootstrap(): void;
+	resume(): Promise<void>;
+	insert(table: string, rowId: string, payload: Record<string, unknown>): ClientOp;
+	update(table: string, rowId: string, payload: Record<string, unknown>): ClientOp;
+	delete(table: string, rowId: string): ClientOp;
+	batch(ops: Array<{
+		table: string;
+		op: OpType;
+		rowId: string;
+		payload: Record<string, unknown> | null;
+	}>): ClientOp[];
+	/**
+	* Transmit pending ops.
+	*
+	* Concurrent calls are coalesced: at most one push runs and at most one
+	* more is queued behind it, so a burst of mutations (every `useSync`
+	* mutation calls this) produces one send per op rather than one send of
+	* everything pending per mutation. The returned promise resolves once the
+	* caller's own ops have been handed to the transport.
+	*/
+	push(): Promise<void>;
+	private doPush;
+	/** Forget which ops are on the wire — used when the connection drops. */
+	private clearInFlight;
+	sendEphemeral(params: {
+		key: string;
+		userId: string;
+		data: Record<string, unknown>;
+		ttlMs?: number;
+	}): Promise<void>;
+	subscribeEphemeral(key: string, listener: (event: EphemeralEvent) => void): () => void;
+	getRows(table: string, options?: {
+		includeDeleted?: boolean;
+	}): Record<string, unknown>[];
+	getRow(table: string, rowId: string): Record<string, unknown> | null;
+	getPendingCount(): number;
+	getStore(): ClientStore;
+	/**
+	* Subscribe to store changes. Returns an unsubscribe function.
+	* Compatible with React's useSyncExternalStore.
+	*/
+	subscribe(listener: () => void): () => void;
+	/**
+	* Subscribe to changes for a specific table. Returns an unsubscribe function.
+	* More efficient than subscribe() — only fires when the given table changes.
+	*/
+	subscribeTable(table: string, listener: () => void): () => void;
+	/** Returns a version number that increments on every data change. */
+	getVersion(): number;
+	/** Returns a version number for a specific table. Only increments when that table changes. */
+	getTableVersion(table: string): number;
+	private notify;
+	/**
+	* Reset client state. With no argument, wipes everything (pending ops,
+	* rows, server HLC, subscriptions). With `tables`, only those tables'
+	* rows + subscriptions are dropped — useful for logging out of a single
+	* scope or evicting a stale dataset without losing pending ops elsewhere.
+	*/
+	clear(opts?: {
+		tables?: string[];
+	}): Promise<void>;
+	private handleMessage;
+	private mergeServerHlc;
+	private persistMeta;
+	private persistSyncSubscriptions;
+	private handleReauth;
+	private scheduleReconnect;
+}
+interface VanillaSyncConfig {
+	url: string;
+	token: string;
+	tables?: string[];
+	clientId?: string;
+	storage?: ClientStorageAdapter;
+	onReauth?: () => Promise<string>;
+	onError?: (error: {
+		opId?: string;
+		reason: string;
+	}) => void;
+}
+interface TableBinding<T = Record<string, unknown>> {
+	getRows(options?: {
+		includeDeleted?: boolean;
+	}): T[];
+	insert(rowId: string, payload: Partial<T>): void;
+	update(rowId: string, payload: Partial<T>): void;
+	remove(rowId: string): void;
+	onChange(cb: () => void): () => void;
+	destroy(): void;
+}
+interface EphemeralBinding<T = Record<string, unknown>> {
+	getEvents(): Record<string, T>;
+	broadcast(data: T): Promise<void>;
+	onChange(cb: (events: Record<string, T>) => void): () => void;
+	destroy(): void;
+}
+interface VanillaSync {
+	client: SyncClient;
+	connect(): Promise<void>;
+	close(): Promise<void>;
+	getState(): SyncClientState;
+	onStateChange(cb: (state: SyncClientState) => void): () => void;
+	getPendingCount(): number;
+	onPendingChange(cb: (count: number) => void): () => void;
+	sync<T extends object = Record<string, unknown>>(table: string, options?: {
+		params?: Record<string, unknown>;
+		includeDeleted?: boolean;
+		window?: number;
+	}): TableBinding<T>;
+	getRow<T extends object = Record<string, unknown>>(table: string, rowId: string): T | null;
+	onRowChange<T extends object = Record<string, unknown>>(table: string, rowId: string, cb: (row: T | null) => void): () => void;
+	ephemeral<T extends object>(config: {
+		key: string;
+		userId: string;
+		ttlMs?: number;
+	}): EphemeralBinding<T>;
+	getTotalCount(table: string): number | null;
+	onTotalCountChange(table: string, cb: (count: number | null) => void): () => void;
+	loadMore(table: string, count: number): void;
+}
+declare const REFLECT_SCHEME = "reflect:";
+interface ReflectAction {
+	table: string;
+	rowId?: string;
+	params: URLSearchParams;
+}
+/**
+* Parse a `reflect:<table>[/<rowId>][?<params>]` action.
+*
+* Returns null for anything that is not a reflect action, which is how the
+* fetch shim decides whether to handle a request or let htmx hit the network.
+*
+* htmx rewrites GET/DELETE actions through `new URL(action, document.baseURI)`
+* before the fetch runs. `reflect:` is a non-special scheme, so the URL parser
+* keeps an opaque path and `href` round-trips unchanged (`reflect:todos` stays
+* `reflect:todos`, query params land as `reflect:todos?a=b`). Parsing the raw
+* string rather than going through `URL` keeps both spellings working.
+*/
+declare function parseReflectAction(action: string): ReflectAction | null;
+type ReflectOperation = {
+	kind: "read";
+	table: string;
+	rowId?: string;
+	params: URLSearchParams;
+} | {
+	kind: "insert";
+	table: string;
+	rowId: string;
+	payload: Record<string, unknown>;
+} | {
+	kind: "update";
+	table: string;
+	rowId: string;
+	payload: Record<string, unknown>;
+} | {
+	kind: "remove";
+	table: string;
+	rowId: string;
+} | {
+	kind: "error";
+	status: number;
+	message: string;
+};
+/** Anything htmx hands us as a request body: URLSearchParams or FormData. */
+type ReflectBody = Iterable<[string, FormDataEntryValue]> | null | undefined;
+interface ResolveOptions {
+	/** Used as the row id for POSTs that do not carry one. Injected for tests. */
+	generateRowId?: () => string;
+}
+/**
+* Map an action + HTTP method + form body onto a store operation.
+*
+* The mapping is deliberately REST-shaped so the attributes read like ordinary
+* htmx: `hx-get` reads, `hx-post` inserts, `hx-put`/`hx-patch` update,
+* `hx-delete` removes.
+*/
+declare function resolveOperation(action: string, method: string, body?: ReflectBody, options?: ResolveOptions): ReflectOperation | null;
+/**
+* Flatten a form body into a payload.
+*
+* Repeated keys collapse into an array so `<select multiple>` and checkbox
+* groups survive. File entries are dropped: a File cannot cross the op log.
+*/
+declare function collectPayload(body: ReflectBody): Record<string, unknown>;
+/** The request context htmx hands to `htmx:config:request` listeners. */
+interface HtmxRequestContext {
+	sourceElement: Element;
+	target?: Element;
+	swap?: string;
+	request: {
+		action: string;
+		method: string;
+		headers: Record<string, string>;
+		body?: ReflectBody;
+	};
+	/**
+	* htmx runs `ctx.fetch ||= window.fetch` after `htmx:config:request`, so a
+	* listener that assigns here owns the response and htmx still performs the
+	* swap, OOB handling, settling and history it normally would.
+	*/
+	fetch?: (action: string, request: unknown) => Promise<Response>;
+}
+interface HtmxLike {
+	ajax(verb: string, path: string, options?: Record<string, unknown>): Promise<unknown>;
+	/** `metaCharacter` rewrites the `:` in htmx's own event names when set. */
+	config?: {
+		metaCharacter?: string;
+	};
+}
+interface ReflectViewInput<T> {
+	/** Every row for a collection read; the single row (or none) for a row read. */
+	rows: T[];
+	table: string;
+	/** Set when the action addressed one row: `reflect:todos/abc`. */
+	rowId?: string;
+	/** Query string of the action, for filtering and sorting inside the view. */
+	params: URLSearchParams;
+}
+/** Renders local rows to the HTML fragment htmx will swap in. */
+type ReflectView<T = Record<string, unknown>> = (input: ReflectViewInput<T>) => string;
+/** Coerces a form body before it reaches the op log (checkboxes, numbers, …). */
+type ReflectParse<T = Record<string, unknown>> = (payload: Record<string, unknown>) => Partial<T>;
+interface HtmxSyncConfig extends VanillaSyncConfig {
+	/** The htmx instance to attach to — import it yourself and pass it in. */
+	htmx: HtmxLike;
+}
+interface HtmxSync {
+	/** The underlying vanilla sync, for anything the attributes cannot express. */
+	sync: VanillaSync;
+	/** Register the renderer for a table. Required before any read of it. */
+	view<T extends object = Record<string, unknown>>(table: string, view: ReflectView<T>): HtmxSync;
+	/** Register an optional payload coercion for writes to a table. */
+	parse<T extends object = Record<string, unknown>>(table: string, parse: ReflectParse<T>): HtmxSync;
+	/** Attach the `reflect:` fetch shim to htmx. Idempotent. */
+	install(): HtmxSync;
+	/** Detach the shim and drop every element binding. */
+	uninstall(): void;
+	/** Re-render bound elements now — one table, or all of them. */
+	refresh(table?: string): void;
+	connect(): Promise<void>;
+	close(): Promise<void>;
+	getState(): SyncClientState;
+	onStateChange(cb: (state: SyncClientState) => void): () => void;
+	getPendingCount(): number;
+	onPendingChange(cb: (count: number) => void): () => void;
+}
+declare function createHtmxSync2(config: HtmxSyncConfig): HtmxSync;
+interface DrizzleTableLike {
+	$inferSelect: Record<string, unknown>;
+	$inferInsert: Record<string, unknown>;
+}
+/**
+* Value supplied per serverSet field in the schema's object form.
+* Either a static value or a function that receives the request context.
+*
+* The static arm is enumerated rather than written as `unknown`: a union with
+* `unknown` collapses to `unknown`, which strips the contextual type from the
+* callback arm and makes every `(ctx) => …` an implicit `any` under `strict`.
+*/
+type ServerSetSchemaValue = ((ctx: {
+	auth: unknown;
+	params: unknown;
+}) => unknown) | string | number | bigint | boolean | symbol | null | undefined | Date | readonly unknown[] | Record<string, unknown>;
+/**
+* Schema-side `serverSet` declaration. Two shapes:
+*  - `string[]` — keys only; values are supplied at `implement(...)` time.
+*  - `Record<string, ServerSetSchemaValue>` — keys + values collocated in schema.
+*/
+type SchemaServerSet = readonly string[] | Readonly<Record<string, ServerSetSchemaValue>>;
+interface SyncQueryDef {
+	/** Drizzle table — row type derived from $inferSelect */
+	table?: DrizzleTableLike;
+	/** Phantom row type for non-drizzle usage: `{} as MyRow` */
+	row?: Record<string, unknown>;
+	/** Database tables for change detection. Falls back to query key name. */
+	tables?: string[];
+	/** Phantom value for params type: `{} as { orgId: string }` */
+	params?: Record<string, unknown>;
+	/** Primary key column name. Defaults to "id". Single-column only. */
+	pk?: string;
+	conflict?: ConflictPolicy;
+	readonly?: readonly string[];
+	serverSet?: SchemaServerSet;
+	countHints?: boolean;
+}
+/**
+* Read-only computed query. Compiles down to `server.query(...)` with a
+* throwing mutate so the type system blocks `useSync(...).insert/update/remove`
+* and the runtime rejects any direct write attempt.
+*/
+interface SyncViewDef {
+	__view: true;
+	row?: Record<string, unknown>;
+	params?: Record<string, unknown>;
+	tables?: string[];
+	/** Tables to watch for change-detection. Defaults to `tables` or query key. */
+	deps?: string[];
+}
+/**
+* Typed ephemeral channel. Sugar over the runtime `useEphemeral` hook —
+* derives a stable key from the schema name + serialized params and gives
+* `peers`/`set` a typed `state`.
+*/
+interface SyncPresenceDef {
+	__presence: true;
+	state?: Record<string, unknown>;
+	params?: Record<string, unknown>;
+	ttlMs?: number;
+}
+type SyncQueryEntry = SyncQueryDef | SyncViewDef | SyncPresenceDef;
+type SyncQueryMap = Record<string, SyncQueryEntry>;
+/** Row type: from `table.$inferSelect` if drizzle, otherwise from `row` phantom */
+type InferRow<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = TQueries[K] extends {
+	table: DrizzleTableLike;
+} ? TQueries[K]["table"]["$inferSelect"] : TQueries[K] extends {
+	row: infer R extends Record<string, unknown>;
+} ? R : Record<string, unknown>;
+/** Primary key column name. Defaults to "id". */
+type PkOf<TDef> = TDef extends {
+	pk: infer P extends string;
+} ? P : "id";
+/** Extract serverSet field names from either array form or object form. */
+type InferServerSetKeys<TDef> = TDef extends {
+	serverSet: readonly (infer S extends string)[];
+} ? S : TDef extends {
+	serverSet: infer O extends Readonly<Record<string, unknown>>;
+} ? keyof O & string : never;
+/**
+* Row minus readonly fields, serverSet fields, and the primary key.
+* View defs collapse to `never` to block client-side writes at the type level.
+* Presence defs aren't writable rows; they collapse to `never` too.
+*/
+type InferWritableRow<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = TQueries[K] extends {
+	__view: true;
+} | {
+	__presence: true;
+} ? never : Omit<InferRow<TQueries, K>, (TQueries[K] extends {
+	readonly: readonly (infer R extends string)[];
+} ? R : never) | InferServerSetKeys<TQueries[K]> | PkOf<TQueries[K]>>;
+type TypedReflectView<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = (input: ReflectViewInput<InferRow<TQueries, K>>) => string;
+type TypedReflectParse<
+	TQueries extends SyncQueryMap,
+	K extends keyof TQueries
+> = (payload: Record<string, unknown>) => Partial<InferWritableRow<TQueries, K>>;
+interface TypedHtmxSync<TQueries extends SyncQueryMap> {
+	sync: VanillaSync;
+	view<K extends keyof TQueries & string>(table: K, view: TypedReflectView<TQueries, K>): TypedHtmxSync<TQueries>;
+	parse<K extends keyof TQueries & string>(table: K, parse: TypedReflectParse<TQueries, K>): TypedHtmxSync<TQueries>;
+	install(): TypedHtmxSync<TQueries>;
+	uninstall(): void;
+	refresh<K extends keyof TQueries & string>(table?: K): void;
+	connect(): Promise<void>;
+	close(): Promise<void>;
+	getState(): SyncClientState;
+	onStateChange(cb: (state: SyncClientState) => void): () => void;
+	getPendingCount(): number;
+	onPendingChange(cb: (count: number) => void): () => void;
+}
+interface SyncHtmxHooks<TQueries extends SyncQueryMap> {
+	createHtmxSync: (config: HtmxSyncConfig) => TypedHtmxSync<TQueries>;
+}
+declare function createSyncHtmx<TQueries extends SyncQueryMap>(): SyncHtmxHooks<TQueries>;
+export { HtmxLike, HtmxRequestContext, HtmxSync, HtmxSyncConfig, REFLECT_SCHEME, ReflectAction, ReflectBody, ReflectOperation, ReflectParse, ReflectView, ReflectViewInput, ResolveOptions, SyncHtmxHooks, TypedHtmxSync, TypedReflectParse, TypedReflectView, collectPayload, createHtmxSync2 as createHtmxSync, createSyncHtmx, parseReflectAction, resolveOperation };