@pylonsync/react 0.3.292 → 0.3.294

package/dist/Form.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "method" | "action"> {
+    /** The `route.ts` handler path (e.g. "/notes"). */
+    action: string;
+    /** HTTP method. Default "post" (the only method usable without JS). */
+    method?: "post" | "put" | "patch" | "delete";
+    /** Opt out of client interception — force a native full-page submit. */
+    navigate?: boolean;
+    children?: React.ReactNode;
+}
+export declare function Form({ action, method, navigate, children, ...rest }: FormProps): React.JSX.Element;

package/dist/Image.d.ts

@@ -0,0 +1,39 @@
+import React from "react";
+export interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" | "width" | "height" | "loading" | "srcSet"> {
+    /** Source URL — site-relative (`/foo.jpg`) or http(s) (allowlisted via env). */
+    src: string;
+    /** Intrinsic width in CSS px (used for aspect ratio + the 1x candidate). */
+    width: number;
+    /** Intrinsic height in CSS px. */
+    height: number;
+    /** Required alt text. Pass `""` for purely decorative images. */
+    alt: string;
+    /**
+     * JPEG/WebP quality 1..=100. Default 75 — matches Next.js.
+     * PNG ignores it (lossless).
+     */
+    quality?: number;
+    /**
+     * Override the candidate widths used in `srcset`. By default we
+     * emit 1x and 2x of `width`, capped at 3840px.
+     */
+    widths?: number[];
+    /**
+     * `<img sizes>` attribute. Default `100vw` — change to match the
+     * container width so the browser picks the smallest srcset
+     * candidate that fits. Example: `(max-width: 768px) 100vw, 50vw`.
+     */
+    sizes?: string;
+    /** Skip lazy-loading + bump fetch priority. Use for above-the-fold hero images. */
+    priority?: boolean;
+    /**
+     * Skip the Pylon optimizer and render `src` directly. Useful for
+     * SVGs (the optimizer rejects them as a security precaution),
+     * animated GIFs, or formats Pylon doesn't process. The browser
+     * still gets `width`/`height` for layout stability, but there's
+     * no `srcset` and no caching beyond whatever the source URL
+     * declares.
+     */
+    unoptimized?: boolean;
+}
+export declare function Image({ src, width, height, alt, quality, widths, sizes, priority, unoptimized, className, style, ...rest }: ImageProps): React.JSX.Element;

package/dist/Link.d.ts

@@ -0,0 +1,27 @@
+import React from "react";
+declare global {
+    interface Window {
+        __pylon?: {
+            prefetch: (href: string) => Promise<void>;
+            navigate: (href: string, opts?: {
+                push?: boolean;
+                replace?: boolean;
+            }) => Promise<void>;
+            /** Current route's dynamic params (read by useParams). A getter on the
+             *  runtime side, so it always reflects the latest navigation. */
+            readonly params?: Record<string, string>;
+        };
+    }
+}
+export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    /** Destination path. Same-origin paths get client-side nav; off-origin paths render as plain <a>. */
+    href: string;
+    /**
+     * Prefetch the destination on viewport entry. Default true.
+     * Set `false` to skip prefetch (useful for links the user
+     * is unlikely to follow — pagination tail, etc.).
+     */
+    prefetch?: boolean;
+    children?: React.ReactNode;
+}
+export declare function Link({ href, prefetch, children, ...rest }: LinkProps): React.JSX.Element;

package/dist/db.d.ts

@@ -0,0 +1,163 @@
+import { SyncEngine, type Row, type SyncEngineConfig } from "@pylonsync/sync";
+import { type QueryOptions, type UseQueryReturn, type UseQueryOneReturn, type UseReactiveQueryReturn, type UseMutationReturn, type UseInfiniteQueryReturn, type AggregateSpec, type UseAggregateReturn, type SearchSpec, type UseSearchReturn } from "./hooks";
+import { type UploadedFile } from "./index";
+/**
+ * Initialize the pylon client. Call once at app startup.
+ *
+ * ```ts
+ * import { init } from "@pylonsync/react";
+ * init({ baseUrl: "http://localhost:4321" });
+ * ```
+ *
+ * Omitting `baseUrl` in a browser context falls back to
+ * `window.location.origin` — the right answer for same-origin
+ * deployments (Next.js + Vercel rewrites, embedded SPA). Passing an
+ * explicit `baseUrl` always wins. We deliberately do NOT default to
+ * `http://localhost:4321` in browsers — that footgun caused production
+ * dashboards to fire requests at the engineer's dev port.
+ */
+export declare function init(config?: Partial<SyncEngineConfig> & {
+    baseUrl?: string;
+}): void;
+/** Module-internal accessor for the global sync engine. Exported so
+ *  hooks living outside this file (e.g. `useRoom`) can share the same
+ *  engine instance and benefit from the same lazy-start / lazy-init
+ *  semantics — without re-implementing the resolution rules. */
+export declare function getSync(): SyncEngine;
+/**
+ * Live query with loading/error state.
+ *
+ * ```tsx
+ * const { data, loading, error } = db.useQuery<Todo>("Todo", {
+ *   where: { done: false },
+ *   orderBy: { createdAt: "desc" },
+ * });
+ * ```
+ */
+export declare const db: {
+    /** Live query for entity rows with loading/error state. */
+    useQuery<T = Row>(entity: string, options?: QueryOptions): UseQueryReturn<T>;
+    /** Live query for a single row by ID. */
+    useQueryOne<T = Row>(entity: string, id: string): UseQueryOneReturn<T>;
+    /**
+     * Reactive query — Convex-style auto-rerunning server handler.
+     *
+     * The server runs your `query()` handler with dependency tracking
+     * (every `ctx.db.*` read is recorded), registers the subscription,
+     * and pushes the initial result. Any future mutation touching the
+     * dep set triggers a re-run + push.
+     *
+     * ```tsx
+     * const { data: feed, loading } = db.useReactiveQuery<FeedItem[]>(
+     *   "getFeed",
+     *   { userId: currentUser.id },
+     * );
+     * ```
+     *
+     * Authoring side: define the handler with `query()` from
+     * `@pylonsync/functions`. Any handler is eligible — no opt-in flag.
+     */
+    useReactiveQuery<T = unknown>(fnName: string, args?: unknown): UseReactiveQueryReturn<T>;
+    /**
+     * Server-side function call with mutation state (loading, data, error).
+     *
+     * ```tsx
+     * const placeBid = db.useMutation<{lotId: string}, {accepted: boolean}>("placeBid");
+     * await placeBid.mutate({ lotId: "x", amount: 150 });
+     * ```
+     *
+     * For optimistic UI, pass an `optimistic` builder — the framework
+     * paints the row into the local store immediately, threads a
+     * matching id through to the server function, and reconciles the
+     * canonical broadcast as an in-place merge. See
+     * docs/concepts/optimistic-updates for the full pattern.
+     *
+     * ```tsx
+     * const send = db.useMutation<{channelId: string; body: string}, {messageId: string}>(
+     *   "sendMessage",
+     *   {
+     *     optimistic: (args, ctx) => ({
+     *       entity: "Message",
+     *       data: { id: ctx.id, ...args, authorId: me.id, createdAt: ctx.now },
+     *     }),
+     *   }
+     * );
+     * ```
+     */
+    useMutation<TArgs = Record<string, unknown>, TResult = unknown>(fnName: string, options?: {
+        optimistic?: import("./hooks").OptimisticBuilder<TArgs>;
+    }): UseMutationReturn<TArgs, TResult>;
+    /** Paginated live query with loadMore(). */
+    useInfiniteQuery<T = Row>(entity: string, options?: {
+        pageSize?: number;
+    }): UseInfiniteQueryReturn<T>;
+    /**
+     * Live aggregate query (count / sum / avg / groupBy). Automatically
+     * re-runs when the entity's rows change in the sync replica — dashboard
+     * charts stay up to date without polling.
+     */
+    useAggregate<Row = Record<string, unknown>>(entity: string, spec: AggregateSpec): UseAggregateReturn<Row>;
+    /**
+     * Live faceted full-text search. Returns ranked hits + per-facet
+     * counts + total; re-runs when the entity's rows change so facet
+     * counts and result lists stay in lockstep with writes.
+     *
+     * ```tsx
+     * const { hits, facetCounts, total } = db.useSearch<Product>("Product", {
+     *   query: "red sneakers",
+     *   filters: { category: "shoes" },
+     *   facets: ["brand", "color"],
+     *   sort: ["price", "desc"],
+     * });
+     * ```
+     */
+    useSearch<T = Row>(entity: string, spec: SearchSpec): UseSearchReturn<T>;
+    /** Entity-level optimistic CRUD (not server-side functions). */
+    useEntity(entity: string): {
+        insert: (data: Row) => Promise<string>;
+        update: (id: string, data: Partial<Row>) => Promise<void>;
+        remove: (id: string) => Promise<void>;
+    };
+    /** Get the sync engine instance. */
+    readonly sync: SyncEngine;
+    /** Insert a row (optimistic). */
+    insert(entity: string, data: Row): Promise<string>;
+    /** Update a row (optimistic). */
+    update(entity: string, id: string, data: Partial<Row>): Promise<void>;
+    /** Delete a row (optimistic). */
+    delete(entity: string, id: string): Promise<void>;
+    /** Set presence data. */
+    setPresence(data: Record<string, unknown>): void;
+    /** Publish to a topic. */
+    publishTopic(topic: string, data: unknown): void;
+    /**
+     * Call a server-side function (query, mutation, or action).
+     *
+     * Routes through `SyncEngine.fn` (not the free `callFn`) so the response's
+     * `X-Pylon-Change-Seq` header triggers a fallback pull when the WS
+     * broadcast for the same event hasn't landed yet — closes the gap where
+     * a mutation succeeds but the cached query doesn't observe the new row.
+     *
+     * ```ts
+     * const result = await db.fn("placeBid", { lotId: "x", amount: 150 });
+     * ```
+     */
+    fn<T = unknown>(name: string, args?: Record<string, unknown>): Promise<T>;
+    /**
+     * Stream output from a server-side function as SSE chunks.
+     *
+     * ```ts
+     * for await (const chunk of db.streamFn("chat", { message: "hi" })) {
+     *   console.log(chunk);
+     * }
+     * ```
+     */
+    streamFn(name: string, args?: Record<string, unknown>): AsyncGenerator<string, unknown, unknown>;
+    /** Upload a file to /api/files/upload. */
+    uploadFile(input: File | Blob | ArrayBuffer | Uint8Array, options?: {
+        filename?: string;
+        contentType?: string;
+    }): Promise<UploadedFile>;
+    /** Upload via multipart/form-data with extra fields. */
+    uploadFileMultipart(file: File | Blob, fields?: Record<string, string>): Promise<UploadedFile>;
+};

package/dist/hooks.d.ts

@@ -0,0 +1,388 @@
+import { SyncEngine, type Row } from "@pylonsync/sync";
+/** Operator-based filter matching the server's query_filtered API. */
+export type QueryFilter = Record<string, unknown> & {
+    $order?: Record<string, "asc" | "desc">;
+    $limit?: number;
+};
+/** Include syntax for nested relations: `{ author: {}, tags: {} }`. */
+export type IncludeSpec = Record<string, Record<string, unknown>>;
+export interface QueryOptions {
+    /** Filter by fields and operators (server-side). */
+    where?: QueryFilter;
+    /** Expand relations inline (server-side graph query). */
+    include?: IncludeSpec;
+    /** Limit number of rows. */
+    limit?: number;
+    /** Order by field(s). */
+    orderBy?: Record<string, "asc" | "desc">;
+}
+export interface UseQueryReturn<T> {
+    data: T[];
+    loading: boolean;
+    error: Error | null;
+    /** Re-fetch from the server. Rarely needed — data is live. */
+    refetch: () => void;
+}
+export interface UseQueryOneReturn<T> {
+    data: T | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+/**
+ * Live query hook. Returns rows for an entity with loading/error state.
+ *
+ * Automatically re-renders when underlying data changes via the sync engine.
+ *
+ * ```tsx
+ * const { data: todos, loading, error } = useQuery<Todo>(sync, "Todo");
+ * ```
+ *
+ * With filters and ordering:
+ *
+ * ```tsx
+ * const { data } = useQuery<Todo>(sync, "Todo", {
+ *   where: { done: false, priority: { $gte: 3 } },
+ *   orderBy: { createdAt: "desc" },
+ *   limit: 20,
+ * });
+ * ```
+ *
+ * Filter/order/limit are applied client-side against the sync store;
+ * the sync engine pulls the full entity in the background.
+ */
+export declare function useQuery<T = Row>(sync: SyncEngine, entity: string, options?: QueryOptions): UseQueryReturn<T>;
+/**
+ * Live single-row query by ID. Returns the row or null, with loading/error state.
+ *
+ * ```tsx
+ * const { data: todo, loading } = useQueryOne<Todo>(sync, "Todo", todoId);
+ * ```
+ */
+export declare function useQueryOne<T = Row>(sync: SyncEngine, entity: string, id: string): UseQueryOneReturn<T>;
+export interface UseReactiveQueryReturn<T> {
+    /** Latest server-pushed result. `null` until the initial run lands. */
+    data: T | null;
+    /** True until the first result lands (or the first error). */
+    loading: boolean;
+    /** Most recent error from the server-side handler, if any. */
+    error: Error | null;
+}
+/**
+ * Subscribe to a server-side `query()` handler with automatic re-run
+ * on dependency changes. Mirrors Convex's reactive query model:
+ *
+ * 1. Mount: client sends `reactive-subscribe` over WS with `fn_name`
+ *    + `args`. Server runs the handler under the connection's auth,
+ *    records which entities the handler read via `ctx.db.*`, registers
+ *    the subscription, and pushes the initial result.
+ * 2. On every server-side mutation, the runtime's reactive registry
+ *    looks up subs whose dep set overlaps the changed entity, re-runs
+ *    them, hashes the result, and pushes only when the hash changed.
+ * 3. Unmount: client sends `reactive-unsubscribe`; server tears down
+ *    the registration and stops re-running.
+ *
+ * Auth context for re-runs is captured at subscribe time — the
+ * subscriber's identity, not the mutating user's. Policy gates the
+ * handler runs at first execution apply on every re-run.
+ *
+ * ```tsx
+ * const { data, loading } = useReactiveQuery<MessageWithAuthor[]>(
+ *   sync,
+ *   "getMessagesWithAuthors",
+ *   { channelId: "c_1" },
+ * );
+ * ```
+ *
+ * Args object identity matters: changing the args reference triggers
+ * an unsubscribe + resubscribe with a fresh sub_id. Stabilize via
+ * `useMemo` if you build args inline on every render.
+ */
+export declare function useReactiveQuery<T = unknown>(sync: SyncEngine, fnName: string, args?: unknown): UseReactiveQueryReturn<T>;
+export interface UseMutationReturn<TArgs, TResult> {
+    mutate: (args: TArgs) => Promise<TResult>;
+    mutateAsync: (args: TArgs) => Promise<TResult>;
+    loading: boolean;
+    data: TResult | null;
+    error: Error | null;
+    reset: () => void;
+}
+/**
+ * Builder for the optimistic ghost row painted in the local store
+ * before the server function returns. Receives the args passed to
+ * `mutate()` plus a `ctx` object the framework fills in for you:
+ *
+ * - `ctx.id`  — the freshly-minted Pylon-shaped row id (40-char hex)
+ *               that the framework also threads into the mutation
+ *               args as `_optimisticId`. Use this as the row's `id`
+ *               so the optimistic ghost and the canonical broadcast
+ *               share the same `row_id` and the WS update is an
+ *               in-place merge instead of a delete-then-replace flash.
+ * - `ctx.now` — `new Date().toISOString()` evaluated once, so the
+ *               optimistic ghost has a `createdAt` that's stable
+ *               across the same gesture.
+ *
+ * Return either a single `{ entity, data }` for the common one-row
+ * case or an array for mutations that touch multiple entities (e.g.
+ * an "accept invite" that inserts a Membership AND an AuditLog row).
+ */
+export interface OptimisticContext {
+    id: string;
+    now: string;
+}
+export type OptimisticChange = {
+    entity: string;
+    data: Row;
+};
+export type OptimisticBuilder<TArgs> = (args: TArgs, ctx: OptimisticContext) => OptimisticChange | OptimisticChange[];
+export interface UseMutationOptions<TArgs> {
+    token?: string;
+    /**
+     * Paint a row into the local store immediately, before the server
+     * function returns. The row uses `ctx.id` as its `id` and the
+     * framework threads that id through the mutation args as
+     * `_optimisticId` — your server function should accept it and pass
+     * it on to `ctx.db.insert("Entity", { id: args._optimisticId, ... })`
+     * (the runtime honors caller-supplied ids for any 40-char hex value).
+     *
+     * The WS broadcast that follows will carry the same `row_id`, so the
+     * canonical row lands as a field-level merge on top of the
+     * optimistic ghost — no flash, no temp-row swap, no manual cleanup.
+     *
+     * On rejection, the optimistic insert is rolled back without leaving
+     * a tombstone, so retrying the mutation works.
+     */
+    optimistic?: OptimisticBuilder<TArgs>;
+    /**
+     * Active sync engine. Required when `optimistic` is set so the hook
+     * can paint the ghost into the right store; ignored otherwise. The
+     * `db.useMutation` wrapper supplies this automatically via `getSync`.
+     */
+    sync?: SyncEngine;
+}
+/**
+ * Hook for calling a server-side mutation/action function.
+ *
+ * ```tsx
+ * const placeBid = useMutation<{lotId: string; amount: number}, {accepted: boolean}>(
+ *   "placeBid"
+ * );
+ *
+ * const onClick = async () => {
+ *   const result = await placeBid.mutate({ lotId: "lot_1", amount: 150 });
+ *   if (result.accepted) alert("Bid placed!");
+ * };
+ * ```
+ *
+ * For optimistic UI, pass an `optimistic` builder. See
+ * `OptimisticBuilder` above for the contract.
+ */
+export declare function useMutation<TArgs = Record<string, unknown>, TResult = unknown>(fnName: string, options?: UseMutationOptions<TArgs>): UseMutationReturn<TArgs, TResult>;
+export interface UseInfiniteQueryReturn<T> {
+    data: T[];
+    loading: boolean;
+    hasMore: boolean;
+    loadMore: () => void;
+    error: Error | null;
+}
+/**
+ * Paginated query hook that accumulates pages as you `loadMore()`.
+ *
+ * ```tsx
+ * const { data, hasMore, loadMore, loading } = useInfiniteQuery<Todo>(
+ *   sync, "Todo", { pageSize: 20 }
+ * );
+ * ```
+ */
+export declare function useInfiniteQuery<T = Row>(sync: SyncEngine, entity: string, options?: {
+    pageSize?: number;
+}): UseInfiniteQueryReturn<T>;
+export type PaginatedQueryStatus = "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted";
+export interface UsePaginatedQueryReturn<T> {
+    /** Rows loaded so far, across all pages. */
+    results: T[];
+    /** State-machine value — render based on this rather than booleans. */
+    status: PaginatedQueryStatus;
+    /** Fetch the next page. Idempotent: no-op while loading or exhausted. */
+    loadMore: (numItems?: number) => void;
+    /** The most recent error, if any. Resets on the next successful load. */
+    error: Error | null;
+}
+/**
+ * Cursor-paginated live query. Pairs with `ctx.db.paginate()` server-side
+ * and the `GET /api/entities/:entity/cursor` endpoint.
+ *
+ * ```tsx
+ * const { results, status, loadMore } = usePaginatedQuery<Order>(
+ *   sync,
+ *   "Order",
+ *   { initialNumItems: 20 }
+ * );
+ *
+ * return (
+ *   <>
+ *     {results.map(o => <Row key={o.id} order={o} />)}
+ *     {status === "CanLoadMore" && <button onClick={() => loadMore()}>More</button>}
+ *     {status === "LoadingMore" && <Spinner />}
+ *     {status === "Exhausted" && <footer>end</footer>}
+ *   </>
+ * );
+ * ```
+ *
+ * Same engine as `useInfiniteQuery`; different surface. Prefer this one in
+ * new code — the `status` enum makes exhaustive rendering easier to get
+ * right than `hasMore/loading` booleans.
+ */
+export declare function usePaginatedQuery<T = Row>(sync: SyncEngine, entity: string, options?: {
+    initialNumItems?: number;
+}): UsePaginatedQueryReturn<T>;
+/**
+ * Low-level hook returning `{subscribe, getSnapshot, getServerSnapshot}` for
+ * `useSyncExternalStore`. Prefer [`useQuery`] above for most cases; use this
+ * when you need precise control over subscription timing.
+ */
+export declare function useQueryRaw(sync: SyncEngine, entity: string): {
+    subscribe: (callback: () => void) => () => void;
+    getSnapshot: () => Row[];
+    getServerSnapshot: () => Row[];
+};
+export declare function useQueryOneRaw(sync: SyncEngine, entity: string, id: string): {
+    subscribe: (callback: () => void) => () => void;
+    getSnapshot: () => Row | null;
+    getServerSnapshot: () => Row | null;
+};
+/**
+ * Entity-level CRUD helpers backed by the sync engine (optimistic updates).
+ * Separate from [`useMutation`] which calls server-side TypeScript functions.
+ */
+export declare function useEntityMutation(sync: SyncEngine, entity: string): {
+    insert: (data: Row) => Promise<string>;
+    update: (id: string, data: Partial<Row>) => Promise<void>;
+    remove: (id: string) => Promise<void>;
+};
+export declare const useLiveList: typeof useQueryRaw;
+export declare const useLiveRow: typeof useQueryOneRaw;
+export declare function useInsert(sync: SyncEngine, entity: string): (data: Row) => Promise<string>;
+export declare function useUpdate(sync: SyncEngine, entity: string): (id: string, data: Partial<Row>) => Promise<void>;
+export declare function useDelete(sync: SyncEngine, entity: string): (id: string) => Promise<void>;
+export declare function useAction(sync: SyncEngine, entity: string, actionFn: (data: Row) => Promise<void>): (data: Row) => Promise<void>;
+export interface UseFnReturn<TResult> {
+    call: (args?: Record<string, unknown>) => Promise<TResult>;
+    loading: boolean;
+    data: TResult | null;
+    error: Error | null;
+    reset: () => void;
+}
+/**
+ * Call a server-side function with loading/error/data state.
+ * Prefer [`useMutation`] for new code — same functionality, better API.
+ */
+export declare function useFn<TResult = unknown>(name: string, options?: {
+    token?: string;
+}): UseFnReturn<TResult>;
+/**
+ * Aggregate spec — server matches this shape in
+ * `POST /api/aggregate/:entity`. The server auto-injects an `orgId`
+ * clamp into `where` when the caller has a tenant, so a malicious
+ * client can't sum across orgs.
+ */
+export interface AggregateSpec {
+    /** "*" for COUNT(*), a column name for COUNT(col). */
+    count?: string;
+    /** Columns to sum. */
+    sum?: string[];
+    /** Columns to average. */
+    avg?: string[];
+    /** Columns to take the minimum of. */
+    min?: string[];
+    /** Columns to take the maximum of. */
+    max?: string[];
+    /** Columns to COUNT DISTINCT. */
+    countDistinct?: string[];
+    /**
+     * Group keys. Each entry is either a column name, or a date-bucket
+     * spec `{ field, bucket }` where bucket ∈ hour/day/week/month/year.
+     */
+    groupBy?: (string | {
+        field: string;
+        bucket: "hour" | "day" | "week" | "month" | "year";
+    })[];
+    /** Equality filter applied before aggregation. */
+    where?: Record<string, unknown>;
+}
+export interface UseAggregateReturn<Row = Record<string, unknown>> {
+    data: Row[] | null;
+    loading: boolean;
+    error: Error | null;
+    /** Re-run the query. Rarely needed — the hook refreshes on sync notify. */
+    refresh: () => void;
+}
+/**
+ * Run an aggregate query and keep it fresh as the sync store mutates.
+ *
+ * The hook re-fetches whenever the given entity changes in the local
+ * sync replica — so charts stay live without polling. Subscribes to
+ * the entity's sync events; any change triggers a debounced re-fetch.
+ *
+ * ```tsx
+ * const { data } = useAggregate(sync, "Order", {
+ *   count: "*",
+ *   groupBy: [{ field: "createdAt", bucket: "day" }],
+ *   where: { status: "delivered" },
+ * });
+ * ```
+ */
+export declare function useAggregate<Row = Record<string, unknown>>(sync: SyncEngine, entity: string, spec: AggregateSpec): UseAggregateReturn<Row>;
+export interface SearchSpec {
+    /** Free-text match across the entity's declared `text` fields. */
+    query?: string;
+    /** Equality filters. Keys must be facet fields in the entity's schema. */
+    filters?: Record<string, string | number | boolean>;
+    /** Facet fields to return counts for. If omitted, all declared facets. */
+    facets?: string[];
+    /** Sort by `[field, "asc" | "desc"]`. Field must be in `sortable`. */
+    sort?: [string, "asc" | "desc"];
+    /** Zero-indexed page. Default 0. */
+    page?: number;
+    /** Results per page. Clamped server-side to 1..=100. Default 20. */
+    pageSize?: number;
+}
+export interface UseSearchReturn<T = Row> {
+    /** The current page of hits, already sorted. */
+    hits: T[];
+    /** `{facet: {value: count}}` for every declared (or requested) facet. */
+    facetCounts: Record<string, Record<string, number>>;
+    /** Total hit count across all pages. */
+    total: number;
+    /** Server-reported query latency in ms. */
+    tookMs: number;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Live faceted search hook. Wraps the `POST /api/search/:entity`
+ * endpoint, re-runs the query when the sync replica signals a write
+ * on the target entity, and returns ranked hits plus live facet
+ * counts in one call.
+ *
+ * ```tsx
+ * const { hits, facetCounts, total, loading } = useSearch<Product>(
+ *   sync, "Product",
+ *   {
+ *     query: "red sneakers",
+ *     filters: { category: "shoes" },
+ *     facets: ["brand", "color"],
+ *     sort: ["price", "desc"],
+ *     page: 0, pageSize: 20,
+ *   },
+ * );
+ * ```
+ *
+ * Live-update model matches `useAggregate`: subscribes to the sync
+ * store and re-fetches on any change for this entity. Facet counts
+ * reflect server-computed bitmap intersections — adding/removing a
+ * Product row drops the freshly-recomputed counts back into the UI
+ * in under 100ms on typical catalogs.
+ */
+export declare function useSearch<T = Row>(sync: SyncEngine, entity: string, spec: SearchSpec): UseSearchReturn<T>;