@lotics/app-sdk 0.25.0 → 0.27.0

package/dist/src/comments.d.ts

@@ -0,0 +1,71 @@
+/** A file attached to a comment, in the resolved (serving) shape the list returns. */
+export interface AppCommentFile {
+    id: string;
+    /** Storage key — needed to re-send the file when editing a comment. */
+    file_storage_key: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+    preview_url?: string;
+}
+/** One record comment, as returned by the list op. */
+export interface AppComment {
+    id: string;
+    record_id: string;
+    table_id: string;
+    /** The author's member id. */
+    member_id: string;
+    content: string;
+    files: AppCommentFile[] | null;
+    workspace_id: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface CommentsState {
+    /** Comments on the record, oldest first. Empty while loading or unavailable. */
+    comments: AppComment[];
+    /** True on the initial load only — false during background revalidation. */
+    loading: boolean;
+    error: string | null;
+    /**
+     * True only when a member is signed in AND the app declared the `comments`
+     * capability in its manifest. False in a standalone / public (anonymous) app,
+     * and for any app that didn't opt in. Gate the composer on this; mutations
+     * reject (and the backend re-checks the capability) when false.
+     */
+    available: boolean;
+    /**
+     * Post a new comment as the viewing member. `file_ids` are ids from
+     * `useFileUpload().upload()`. No-op for empty content with no files.
+     */
+    createComment: (input: {
+        content: string;
+        file_ids?: string[];
+    }) => Promise<void>;
+    /**
+     * Edit a comment (author-only, enforced server-side). Pass `files` to replace
+     * the attachment set; omit it to keep the comment's current files — a
+     * text-only edit never silently drops attachments.
+     */
+    updateComment: (id: string, input: {
+        content: string;
+        files?: AppCommentFile[];
+    }) => Promise<void>;
+    /** Delete a comment (author-only, enforced server-side). */
+    deleteComment: (id: string) => Promise<void>;
+    /** Re-pull the thread from the server (e.g. after an external change). */
+    refetch: () => void;
+}
+export interface UseCommentsArgs {
+    /** The record whose comments to read and write. */
+    record_id: string;
+}
+/**
+ * ```tsx
+ * const { comments, available, createComment } = useComments({
+ *   record_id: row.__source_record_id,
+ * });
+ * ```
+ */
+export declare function useComments(args: UseCommentsArgs): CommentsState;

package/dist/src/comments.js

@@ -0,0 +1,169 @@
+/**
+ * `useComments` — read and write the comments on a record from a custom-code app.
+ *
+ * Comments are a *members-only* surface and behave differently from `useQuery`
+ * / `useWorkflow`. Those run under the app OWNER's authority (the app is the
+ * capability), which is what lets a public app expose owner-curated data to an
+ * anonymous visitor. Comments are member-to-member discussion tied to a real
+ * author identity, so they run under the VIEWING MEMBER's own authority instead:
+ *
+ *   - read / write authorized against the viewer's own table access + row-scope
+ *   - the comment's author is the viewer (correct attribution)
+ *   - edit / delete are author-only, checked against the viewer
+ *
+ * The bridged host (`app_iframe_host`) holds the member session and proxies each
+ * op to the member's `/v1/records/.../comments` endpoints. A standalone (public)
+ * app has no signed-in member: `available` is false, the list stays empty, and a
+ * mutation rejects. Check `available` before rendering a composer.
+ *
+ * Freshness mirrors `useQuery`: SWR-cached, revalidate on focus / reconnect, and
+ * an explicit refetch after every mutation. There is no realtime push to apps,
+ * so a thread updated by another viewer appears on the next focus / refetch.
+ */
+import { useCallback } from "react";
+import useSWR from "swr";
+import { rpc } from "./rpc.js";
+import { captureAppEvent } from "./analytics.js";
+/** The reduced storage shape the update endpoint accepts for `files`. */
+function toStorageFiles(files) {
+    return (files ?? []).map((f) => ({
+        id: f.id,
+        file_storage_key: f.file_storage_key,
+        filename: f.filename,
+        mime_type: f.mime_type,
+    }));
+}
+/**
+ * Read the app's context once, shared across every hook via a stable SWR key.
+ * Comments need a signed-in member (members-only) AND the app's declared
+ * `comments` capability — both come from here.
+ */
+function useAppContext() {
+    const { data } = useSWR("app-context", () => rpc("context", {}), {
+        revalidateOnFocus: false,
+        revalidateIfStale: false,
+        revalidateOnReconnect: false,
+        shouldRetryOnError: false,
+    });
+    return {
+        memberId: data?.member_id ?? null,
+        commentsEnabled: data?.comments_enabled ?? false,
+        resolved: data !== undefined,
+    };
+}
+let optimisticCounter = 0;
+/**
+ * ```tsx
+ * const { comments, available, createComment } = useComments({
+ *   record_id: row.__source_record_id,
+ * });
+ * ```
+ */
+export function useComments(args) {
+    const { record_id } = args;
+    const { memberId, commentsEnabled, resolved } = useAppContext();
+    const available = memberId != null && commentsEnabled;
+    const swr = useSWR(available ? ["app-comments", record_id] : null, () => rpc("comments.list", { record_id }), {
+        shouldRetryOnError: false,
+    });
+    const comments = swr.data?.comments ?? [];
+    const refetch = useCallback(() => {
+        void swr.mutate();
+    }, [swr]);
+    const createComment = useCallback(async (input) => {
+        if (!available || memberId == null) {
+            throw new Error("Comments are not available in this app.");
+        }
+        const content = input.content.trim();
+        const fileIds = input.file_ids ?? [];
+        if (!content && fileIds.length === 0)
+            return;
+        const now = new Date().toISOString();
+        const optimistic = {
+            id: `cmt_optimistic_${Date.now()}_${optimisticCounter++}`,
+            record_id,
+            // table_id / workspace_id resolve on the refetch (server-owned); the
+            // optimistic row only needs to render until then.
+            table_id: "",
+            member_id: memberId,
+            content,
+            // The real attachments resolve on the refetch; show none meanwhile.
+            files: null,
+            workspace_id: "",
+            created_at: now,
+            updated_at: now,
+        };
+        await swr.mutate(async () => {
+            await rpc("comments.create", {
+                record_id,
+                content,
+                file_ids: fileIds.length > 0 ? fileIds : undefined,
+            });
+            return rpc("comments.list", { record_id });
+        }, {
+            optimisticData: (current) => ({
+                comments: [...(current?.comments ?? []), optimistic],
+            }),
+            rollbackOnError: true,
+            revalidate: false,
+            populateCache: true,
+        });
+        captureAppEvent("app_comment_created", { has_files: fileIds.length > 0 });
+    }, [available, memberId, record_id, swr]);
+    const updateComment = useCallback(async (id, input) => {
+        if (!available)
+            throw new Error("Comments are not available in this app.");
+        const content = input.content.trim();
+        // Omitted files → keep the comment's current attachments (never drop them
+        // on a text-only edit). The update endpoint replaces the whole set.
+        const currentFiles = input.files !== undefined
+            ? input.files
+            : (swr.data?.comments.find((c) => c.id === id)?.files ?? null);
+        const now = new Date().toISOString();
+        await swr.mutate(async () => {
+            await rpc("comments.update", {
+                record_id,
+                comment_id: id,
+                content,
+                files: toStorageFiles(currentFiles),
+            });
+            return rpc("comments.list", { record_id });
+        }, {
+            optimisticData: (current) => ({
+                comments: (current?.comments ?? []).map((c) => c.id === id ? { ...c, content, files: currentFiles, updated_at: now } : c),
+            }),
+            rollbackOnError: true,
+            revalidate: false,
+            populateCache: true,
+        });
+        captureAppEvent("app_comment_updated", {});
+    }, [available, record_id, swr]);
+    const deleteComment = useCallback(async (id) => {
+        if (!available)
+            throw new Error("Comments are not available in this app.");
+        await swr.mutate(async () => {
+            await rpc("comments.delete", { record_id, comment_id: id });
+            return rpc("comments.list", { record_id });
+        }, {
+            optimisticData: (current) => ({
+                comments: (current?.comments ?? []).filter((c) => c.id !== id),
+            }),
+            rollbackOnError: true,
+            revalidate: false,
+            populateCache: true,
+        });
+        captureAppEvent("app_comment_deleted", {});
+    }, [available, record_id, swr]);
+    return {
+        comments,
+        // Unavailable resolves instantly (no fetch); available shows the initial
+        // load until the list lands. Waiting on context counts as loading.
+        loading: available ? swr.isLoading : !resolved,
+        error: swr.error ? swr.error.message : null,
+        available,
+        createComment,
+        updateComment,
+        deleteComment,
+        refetch,
+    };
+}

package/dist/src/hooks.d.ts

@@ -1,7 +1,7 @@
 import type { AppWorkflows, AppQueries } from "./types.js";
 import type { ResolvedMember } from "./members.js";
-interface QueryState<R> {
-    rows: R[];
+/** Fields shared by every query hook's return value. */
+interface QueryStateBase {
     /**
      * True only on the initial load — a request is in flight and there are no
      * rows yet. Stays false during background revalidation and while typing a new
@@ -13,14 +13,22 @@ interface QueryState<R> {
     isValidating: boolean;
     error: string | null;
     /**
-     * Re-run the query from the first page. Use after a known mutation point —
-     * a successful `useWorkflow(alias)()` call — to pull the latest state.
+     * Re-run the query. Use after a known mutation point — a successful
+     * `useWorkflow(alias)()` call — to pull the latest state.
      */
     refetch: () => void;
+}
+/** Return value of `useQuery` — a single fetch, no pagination. */
+interface QueryState<R> extends QueryStateBase {
+    rows: R[];
+}
+/** Return value of `useInfiniteQuery` — append/load-more. */
+interface InfiniteQueryState<R> extends QueryStateBase {
+    /** All loaded pages, flattened and accumulated. */
+    rows: R[];
     /**
-     * Fetch the next page and append it to `rows`. No-op when `pageSize` was not
-     * set or there are no more rows (`hasMore` is false). `loadingMore` is true
-     * while it runs.
+     * Fetch the next page and append it to `rows`. No-op when there are no more
+     * rows (`hasMore` is false). `loadingMore` is true while it runs.
      */
     loadMore: () => void;
     /** True when the last page came back full, so more rows may exist. */
@@ -28,6 +36,23 @@ interface QueryState<R> {
     /** True while a `loadMore` request is in flight. */
     loadingMore: boolean;
 }
+/** Return value of `usePaginatedQuery` — page-model with a total. */
+interface PaginatedQueryState<R> extends QueryStateBase {
+    /** Rows of the current page only (≤ `pageSize`). */
+    rows: R[];
+    /** Total rows in the filtered set (across all pages). `undefined` until the
+     *  count resolves. */
+    total: number | undefined;
+    /** `ceil(total / pageSize)`, or `undefined` until the count resolves. */
+    totalPages: number | undefined;
+    /** Current 0-indexed page. */
+    page: number;
+    pageSize: number;
+    /** True when a next page exists. */
+    hasMore: boolean;
+    /** Jump to a page (0-indexed). Clamped at 0. */
+    setPage: (page: number) => void;
+}
 /**
  * One sort key — the wire shape of the query RPC's `sort`. The server applies
  * these AFTER the named query, bounded to the query's output columns (an
@@ -55,17 +80,11 @@ export interface QueryFilterGroup {
 /**
  * Runtime filter applied AFTER the named query, bounded to its output columns
  * (same exposure invariant as `sort`). Build a group from per-column filters
- * with `columnFilterToConditions` (`@lotics/ui/grid/column_filter`).
+ * with `columnFilterToConditions` (`@lotics/ui/column_filter`).
  */
 export type QueryFilter = QueryFilterCondition | QueryFilterGroup;
-/** Options for `useQuery`. */
-export interface QueryOptions {
-    /**
-     * Page size. Omit to fetch all rows in one request (the server still caps
-     * the maximum). Set it to paginate: the first render loads one page, and
-     * `loadMore()` appends the next.
-     */
-    pageSize?: number;
+/** Options shared by every query hook. */
+export interface BaseQueryOptions {
     /**
      * When `false`, the query does not run: `rows` stays empty, `loading` is
      * false, and no request is sent. Flip it back to `true` to fetch. This is the
@@ -94,6 +113,22 @@ export interface QueryOptions {
      */
     filter?: QueryFilter;
 }
+/** Options for `useQuery` — a single fetch. */
+export interface QueryOptions extends BaseQueryOptions {
+    /** Max rows to fetch in the one request (a cap, not pagination). The server
+     *  still clamps to its own maximum. Omit to fetch up to the server cap. */
+    pageSize?: number;
+}
+/** Options for `useInfiniteQuery` — append/load-more. */
+export interface InfiniteQueryOptions extends BaseQueryOptions {
+    /** Rows per page. `loadMore()` appends the next page. */
+    pageSize: number;
+}
+/** Options for `usePaginatedQuery` — page-model with a total. */
+export interface PaginatedQueryOptions extends BaseQueryOptions {
+    /** Rows per page. Default 25. */
+    pageSize?: number;
+}
 /**
  * Trigger a workflow by alias from the app's manifest.
  *
@@ -128,9 +163,11 @@ export interface WorkflowResult {
     message?: string;
     files?: UploadedFile[];
 }
-type UseQueryArgs<K extends keyof AppQueries & string> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: QueryOptions] : [params: AppQueries[K], opts?: QueryOptions];
+type QueryArgs<K extends keyof AppQueries & string, O> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: O] : [params: AppQueries[K], opts?: O];
 /**
- * Read rows from a query the app's author declared in `lotics.queries`.
+ * Read rows from a query the app's author declared in `lotics.queries` — a
+ * single fetch, no pagination. For long lists use `usePaginatedQuery`
+ * (numbered pages + total) or `useInfiniteQuery` (load-more).
  *
  * The app never sends a raw query AST — it invokes a named query by alias and
  * fills the template's declared `{{params.x}}` value holes. The server holds
@@ -145,8 +182,35 @@ type UseQueryArgs<K extends keyof AppQueries & string> = AppQueries[K] extends R
  * with the declared alias → param-type map, so an undeclared alias is a
  * compile-time error and params are typed per the manifest.
  */
-export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: UseQueryArgs<K>): QueryState<Record<string, unknown>>;
+export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, QueryOptions>): QueryState<Record<string, unknown>>;
 export declare function useQuery(alias: string, params?: Record<string, unknown>, opts?: QueryOptions): QueryState<Record<string, unknown>>;
+/**
+ * Like `useQuery` but append/load-more: the first render loads one page and
+ * `loadMore()` appends the next, accumulating into `rows` (infinite scroll).
+ * For numbered pages + a total, use `usePaginatedQuery`.
+ *
+ * ```tsx
+ * const { rows, loadMore, hasMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
+ * ```
+ */
+export declare function useInfiniteQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions>): InfiniteQueryState<Record<string, unknown>>;
+export declare function useInfiniteQuery(alias: string, params?: Record<string, unknown>, opts?: InfiniteQueryOptions): InfiniteQueryState<Record<string, unknown>>;
+/**
+ * Page-model query with a total — the data hook behind a numbered, jumpable
+ * table (`@lotics/ui/table_picker`, `@lotics/ui/pagination`). It owns the page
+ * cursor and fetches two things: the current page of rows, and a `count` over
+ * the filtered set (keyed independently of page + sort, so paging and
+ * re-sorting never recount). The `(params, filter)` tuple is the result-set
+ * identity: changing it resets to page 0 AND recounts; changing only `sort`
+ * does neither.
+ *
+ * ```tsx
+ * const { rows, total, page, setPage, hasMore } =
+ *   usePaginatedQuery("orders", { q }, { pageSize: 25, sort, filter });
+ * ```
+ */
+export declare function usePaginatedQuery<K extends keyof AppQueries & string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions>): PaginatedQueryState<Record<string, unknown>>;
+export declare function usePaginatedQuery(alias: string, params?: Record<string, unknown>, opts?: PaginatedQueryOptions): PaginatedQueryState<Record<string, unknown>>;
 /** A file the host has stored and resolved serving URLs for. */
 export interface UploadedFile {
     id: string;

package/dist/src/hooks.js

@@ -1,20 +1,22 @@
 /**
  * Typed React hooks for Lotics app data access.
  *
- * The SDK surface is three hooks: `useQuery` for reads, `useWorkflow` for
- * every mutation, and `useFileUpload` for attaching files. App code never
- * writes records directly — all writes flow through declared workflows, which
- * gives the app owner a typed, audited chokepoint and means a publicly-shared
- * app exposes no anonymous direct-write path. An uploaded file is inert until
- * a workflow attaches it, so file upload keeps that same property.
+ * Reads come in three shapes — `useQuery` (single fetch), `useInfiniteQuery`
+ * (append / load-more), and `usePaginatedQuery` (numbered pages + total) — and
+ * every mutation is a `useWorkflow`; `useFileUpload` attaches files. App code
+ * never writes records directly — all writes flow through declared workflows,
+ * which gives the app owner a typed, audited chokepoint and means a
+ * publicly-shared app exposes no anonymous direct-write path. An uploaded file
+ * is inert until a workflow attaches it, so file upload keeps that same property.
  *
  * Every hook is a thin wrapper over the postMessage RPC bridge — the parent
- * does the actual API calls, results stream back through `rpc()`. `useQuery`
- * caches through SWR keyed by (alias, params, pageSize): reads dedupe and the
+ * does the actual API calls, results stream back through `rpc()`. The read
+ * hooks cache through SWR keyed by (alias, params, …): reads dedupe and the
  * cache survives unmount/remount. Mutation / member hooks keep their own local
  * `useState` — they have nothing to share.
  */
 import { useCallback, useEffect, useState } from "react";
+import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
 import { rpc } from "./rpc.js";
 import { getMockRows } from "./mock.js";
@@ -32,31 +34,62 @@ export function useWorkflow(alias) {
         }
     }, [alias]);
 }
+// Shared SWR config: surface a failed query immediately, keep the last good
+// rows (no retry loop that masks the error), and honor the focus/reconnect
+// opt-out.
+function swrConfig(revalidateOnFocus) {
+    return {
+        revalidateOnFocus,
+        revalidateOnReconnect: revalidateOnFocus,
+        shouldRetryOnError: false,
+    };
+}
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
     const enabled = opts?.enabled ?? true;
     const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
     const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
     const filter = opts?.filter;
-    // A registered fixture short-circuits the network in mock / dev mode.
     const mockRows = getMockRows(alias);
-    // The cache key is (alias, params, pageSize, pageIndex), built HERE so an app
-    // never constructs a key — it just calls `useQuery("hoSo")`. SWR canonicalizes
-    // the params object via its stable hash, so every `useQuery` with the same
-    // (alias, params, pageSize) dedupes to one request and one shared cache entry,
-    // and that entry survives unmount/remount — navigating back to a screen shows
-    // cached rows instantly and revalidates in the background (no flash). A `null`
-    // key disables the fetch (mock / disabled / past the last page).
+    // A `null` key disables the fetch (mock / disabled). SWR canonicalizes the
+    // params/sort/filter objects via its stable hash, so identical reads dedupe to
+    // one request + one cache entry that survives unmount/remount.
+    const key = mockRows || !enabled
+        ? null
+        : ["app-query", alias, params ?? {}, pageSize ?? null, sort ?? null, filter ?? null];
+    const swr = useSWR(key, () => rpc("query", {
+        alias,
+        params: params ?? {},
+        limit: pageSize,
+        offset: 0,
+        sort,
+        filter,
+    }), swrConfig(revalidateOnFocus));
+    const refetch = useCallback(() => {
+        void swr.mutate();
+    }, [swr]);
+    return {
+        rows: mockRows ?? swr.data?.rows ?? [],
+        loading: mockRows ? false : swr.isLoading,
+        isValidating: mockRows ? false : swr.isValidating,
+        error: swr.error ? swr.error.message : null,
+        refetch,
+    };
+}
+export function useInfiniteQuery(alias, params, opts) {
+    const pageSize = opts?.pageSize ?? 30;
+    const enabled = opts?.enabled ?? true;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
+    const filter = opts?.filter;
+    const mockRows = getMockRows(alias);
     const getKey = (index, prev) => {
         if (mockRows || !enabled)
             return null;
-        // Non-paginated has only page 0; paginated stops once a short page returns.
-        if (index > 0 && (pageSize == null || prev == null || prev.rows.length < pageSize)) {
+        // Stop once a short page returns.
+        if (index > 0 && (prev == null || prev.rows.length < pageSize))
             return null;
-        }
-        // sort/filter join the key so a re-sort or re-filter is a distinct cache
-        // entry — SWR refetches instead of serving the previous order/subset.
-        return ["app-query", alias, params ?? {}, pageSize ?? null, sort ?? null, filter ?? null, index];
+        return ["app-query-infinite", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, index];
     };
     const swr = useSWRInfinite(getKey, (key) => {
         const index = Number(key[6]);
@@ -64,42 +97,29 @@ export function useQuery(alias, params, opts) {
             alias,
             params: params ?? {},
             limit: pageSize,
-            offset: pageSize != null ? index * pageSize : 0,
+            offset: index * pageSize,
             sort,
             filter,
         });
-    }, {
-        // loadMore appends pages — don't re-fetch earlier pages when `size` grows.
-        revalidateFirstPage: false,
-        // The opt-out covers focus AND reconnect, per the documented contract.
-        revalidateOnFocus,
-        revalidateOnReconnect: revalidateOnFocus,
-        // Surface a failed query immediately and keep the last good rows — no
-        // silent retry loop that would mask the error from the app.
-        shouldRetryOnError: false,
-    });
-    // SWRInfinite leaves an in-flight page slot `undefined` until it resolves
-    // (the typed `QueryPage[]` understates this) — operate on resolved pages only,
-    // so a page being appended never crashes the flatten or skews the counts.
+    }, { revalidateFirstPage: false, ...swrConfig(revalidateOnFocus) });
+    // SWRInfinite leaves an in-flight page slot `undefined` until it resolves —
+    // operate on resolved pages only so a page being appended never crashes the
+    // flatten or skews the counts.
     const pages = (swr.data ?? []).filter((p) => p != null);
     const rows = mockRows ?? pages.flatMap((p) => p.rows ?? []);
     const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
-    const hasMore = pageSize != null && lastPage != null && (lastPage.rows?.length ?? 0) === pageSize;
-    // Appending a page: more pages are requested than have resolved.
+    const hasMore = lastPage != null && (lastPage.rows?.length ?? 0) === pageSize;
     const loadingMore = swr.isValidating && swr.size > pages.length;
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
     const loadMore = useCallback(() => {
-        if (pageSize == null || !hasMore || loadingMore)
+        if (!hasMore || loadingMore)
             return;
         void swr.setSize((n) => n + 1);
-    }, [pageSize, hasMore, loadingMore, swr]);
+    }, [hasMore, loadingMore, swr]);
     return {
         rows,
-        // `loading` = initial load (validating with nothing to show yet);
-        // `isValidating` = any request in flight. Gating a skeleton on `loading`
-        // never flashes on revalidation; use `isValidating` for a subtle indicator.
         loading: mockRows ? false : swr.isLoading,
         isValidating: mockRows ? false : swr.isValidating,
         error: swr.error ? swr.error.message : null,
@@ -109,6 +129,61 @@ export function useQuery(alias, params, opts) {
         loadingMore,
     };
 }
+export function usePaginatedQuery(alias, params, opts) {
+    const pageSize = opts?.pageSize ?? 25;
+    const enabled = opts?.enabled ?? true;
+    const revalidateOnFocus = opts?.revalidateOnFocus ?? true;
+    const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
+    const filter = opts?.filter;
+    const mockRows = getMockRows(alias);
+    // The result-set identity. When it changes, `page` derives back to 0 (not via
+    // an effect, so the stale page never fires a wasted fetch) and the count key
+    // changes (recount). `setPage` re-stamps the current identity.
+    const resetKey = JSON.stringify([params ?? {}, filter ?? null]);
+    const [pageState, setPageState] = useState({ key: resetKey, page: 0 });
+    const page = pageState.key === resetKey ? pageState.page : 0;
+    const setPage = useCallback((p) => setPageState({ key: resetKey, page: Math.max(0, p) }), [resetKey]);
+    const rowsKey = mockRows || !enabled
+        ? null
+        : ["app-query-page", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, page];
+    const rowsSwr = useSWR(rowsKey, () => rpc("query", {
+        alias,
+        params: params ?? {},
+        limit: pageSize,
+        offset: page * pageSize,
+        sort,
+        filter,
+    }), 
+    // Keep the previous page's rows on screen while the next page loads.
+    { keepPreviousData: true, ...swrConfig(revalidateOnFocus) });
+    // Count key omits page AND sort — one count per result-set identity, reused
+    // across page clicks and re-sorts.
+    const countKey = mockRows || !enabled
+        ? null
+        : ["app-query-count", alias, params ?? {}, filter ?? null];
+    const countSwr = useSWR(countKey, () => rpc("query", { alias, params: params ?? {}, filter, count: true }), swrConfig(revalidateOnFocus));
+    const rows = mockRows ?? rowsSwr.data?.rows ?? [];
+    const total = mockRows ? mockRows.length : countSwr.data?.total;
+    const totalPages = total != null ? Math.max(1, Math.ceil(total / pageSize)) : undefined;
+    const hasMore = total != null ? (page + 1) * pageSize < total : rows.length === pageSize;
+    const refetch = useCallback(() => {
+        void rowsSwr.mutate();
+        void countSwr.mutate();
+    }, [rowsSwr, countSwr]);
+    return {
+        rows,
+        total,
+        totalPages,
+        page,
+        pageSize,
+        hasMore,
+        setPage,
+        loading: mockRows ? false : rowsSwr.isLoading,
+        isValidating: mockRows ? false : rowsSwr.isValidating || countSwr.isValidating,
+        error: rowsSwr.error?.message ?? countSwr.error?.message ?? null,
+        refetch,
+    };
+}
 /**
  * Upload files from an app. The bytes are stored via a presigned
  * direct-to-storage upload the host mediates; the API server never proxies

package/dist/src/index.d.ts

@@ -16,8 +16,10 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
-export type { UploadedFile, QueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
+export type { UploadedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, } from "./hooks.js";
+export { useComments } from "./comments.js";
+export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs } from "./comments.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";

package/dist/src/index.js

@@ -15,7 +15,8 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useFileUpload, useMembers } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFileUpload, useMembers, } from "./hooks.js";
+export { useComments } from "./comments.js";
 export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";

package/dist/src/rpc.d.ts

@@ -18,7 +18,7 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal";
+export type RpcOp = "query" | "workflow" | "upload" | "members" | "context" | "openExternal" | "comments.list" | "comments.create" | "comments.update" | "comments.delete";
 /**
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:
@@ -38,5 +38,11 @@ export interface AppContext {
     workspace_id: string;
     organization_id: string;
     member_id: string | null;
+    /**
+     * Whether the app declared the `comments` capability. `useComments` is
+     * available only when this is true AND a member is signed in. False for any
+     * app that didn't opt in, and (vacuously) for standalone visitors.
+     */
+    comments_enabled: boolean;
 }
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

package/dist/src/rpc.js

@@ -223,8 +223,24 @@ function rpcStandalone(op, payload) {
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
+        case "comments.list":
+        case "comments.create":
+        case "comments.update":
+        case "comments.delete":
+            return rejectCommentsStandalone();
     }
 }
+/**
+ * Comments are a members-only collaboration surface. A comment must have an
+ * authenticated member as its author, and a thread can carry member-to-member
+ * discussion — so a standalone (public, anonymous) app has no member to author
+ * as and no business reading other members' threads. `useComments` detects this
+ * up front via the null context `member_id` and never sends a comment op; this
+ * rejection is the belt-and-braces backstop for any direct `rpc()` caller.
+ */
+function rejectCommentsStandalone() {
+    return Promise.reject(new Error("Comments are available only in embedded apps — a signed-in member is required."));
+}
 async function standaloneMembers(p) {
     const { app_id } = await boot();
     const qs = p.group ? `?group_id=${encodeURIComponent(p.group)}` : "";
@@ -261,8 +277,10 @@ async function standaloneContext() {
         app_name: info.app_name,
         workspace_id: info.workspace_id,
         organization_id: info.organization_id,
-        // No host session in standalone mode — the visitor is anonymous.
+        // No host session in standalone mode — the visitor is anonymous, so
+        // comments are unavailable regardless of the capability flag.
         member_id: null,
+        comments_enabled: info.comments_enabled,
     };
 }
 async function standaloneQuery(p) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {