@lotics/app-sdk 0.100.1 → 0.101.0

package/dist/src/hooks.d.ts

@@ -1,781 +0,0 @@
-import { type ImageFidelity } from "./upload/optimize.js";
-import { type AttachmentsOptions, type AttachmentsState } from "./attachments.js";
-import { type AiContextValue } from "./rpc.js";
-import { type AgentUIPart, type PendingChoice, type AgentRunLanding } from "./agent_stream.js";
-import type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
-import type { ResolvedMember } from "./members.js";
-import type { ResolvedOption } from "./select.js";
-export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, AgentRunLanding } from "./agent_stream.js";
-export { buildChoiceOutput } from "./agent_stream.js";
-/**
- * One row of a query result whose COLUMNS are not known: a dynamic alias, or a
- * query whose AST names no projection (a bare `from_table`). Where codegen could
- * read them, `RowOf` states them instead and there is no index signature — see
- * that type, which is where the reason lives.
- *
- * The projected values stay `unknown` either way: a column's TYPE is the field's
- * and the manifest does not carry it, so the cell readers (`row.text`,
- * `readLinks`, `readFiles`, …) are what narrow them.
- *
- * The `__source_*` columns are different in kind: the compiler injects them at
- * every layer, and they are the only way to address the RECORD a row came from
- * — what `useComments`, a workflow's `record_id` input, and `useAiContext`'s
- * record refs all need. Typed as `unknown` they were unusable without a cast,
- * which is how this SDK's own examples came to show code that does not compile.
- *
- * They are OPTIONAL, and that is the honest shape rather than a hedge: a
- * grouped query collapses rows, so its output has no originating record and the
- * compiler emits no addressing columns for it (the platform's own `record_id`
- * filter refuses such a query for exactly this reason). Narrow before use —
- * on an aggregate row these are genuinely absent, not merely unproven.
- *
- * The line for what belongs here is "consumed RAW", not "starts with
- * `__source_`". A row also carries `__source_locked`, `__created_at` /
- * `__updated_at` and per-projection `__src_field_*`, and each of those has a
- * reader that owns its decoding (`readLocked`, the `row.*` helpers) — a reader
- * IS the narrowing, so a type here would duplicate it. Only these two are
- * handed straight to a `record_id` / `table_id` parameter with nothing in
- * between, which is why only these two needed a type.
- */
-export interface QueryRow {
-    [column: string]: unknown;
-    /** The record this row came from. Absent on a grouped/aggregated row. */
-    __source_record_id?: string;
-    /** The table that record lives in. Absent on a grouped/aggregated row. */
-    __source_table_id?: string;
-}
-/**
- * The row type of alias `K`: the columns that alias PROJECTS, plus the two
- * addressing columns, and nothing else.
- *
- * `.lotics/app_queries.d.ts` already names every projected column
- * (`AppQueryColumns`), read off the query's AST by the same rule the server
- * names them by. A read is bounded to that union for the same reason a
- * `filter`/`sort` key is — except the failure is quieter. A key the query does
- * not carry is refused by the server; a COLUMN it does not carry comes back
- * `undefined`, which every cell reader answers with its empty value, so a
- * misspelt column, a renamed field and a projection moved to another alias all
- * render as a blank cell in a member's browser with no error anywhere. Removing
- * the index signature is what turns that silence into a `tsc` error, which is
- * what `lotics app check` refuses to ship.
- *
- * An alias with no `AppQueryColumns` entry keeps `QueryRow` — a union that could
- * be wrong is worse than none, the rule `ColumnKeyOf` already follows.
- */
-export type RowOf<K extends string> = K extends keyof AppQueryColumns ? {
-    [C in AppQueryColumns[K] & string]: unknown;
-} & Pick<QueryRow, "__source_record_id" | "__source_table_id"> : QueryRow;
-/** 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
-     * query (the previous rows remain visible), so consumers never blank data to a
-     * spinner on refetch. Use `isValidating` for a subtle refetch indicator.
-     */
-    loading: boolean;
-    /** True whenever any request is in flight (initial load or revalidation). */
-    isValidating: boolean;
-    error: string | null;
-    /**
-     * 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[];
-    /**
-     * True when the limit cut the result — more rows matched than arrived, so
-     * `rows` is SHORT and anything folded from it (a total, a ratio, a KPI strip)
-     * is under-reported. Without it the cap is invisible: no error, no empty
-     * state, just numbers that look right.
-     *
-     * The limit is your `pageSize` when you set one and the server's row cap
-     * otherwise. False while loading and under a fixture.
-     */
-    truncated: boolean;
-}
-/** 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 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. */
-    hasMore: boolean;
-    /** 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
- * un-projected `field_key` is rejected), so an app can sort by any column it
- * actually selects without the query template declaring it.
- */
-export interface QuerySortKey<C extends string = string> {
-    /** One of the query's projected outputs — `AppQueryColumns[alias]` on a
-     *  typed alias, so a column the query does not carry is a compile error
-     *  rather than the server's request-time refusal. */
-    field_key: C;
-    order: "asc" | "desc";
-    /**
-     * Where rows BLANK in this column sit — `"bottom"` when omitted, which is what
-     * you want for "the ones with a value first".
-     *
-     * It earns its place on a MULTI-KEY sort over columns that are blank by
-     * position rather than by accident — a pipeline's per-step date stamps, say,
-     * where the first non-blank column IS the row's rank. Reading such a ladder
-     * from the top with blanks at the bottom orders it furthest-along-first; the
-     * reverse reading needs blanks on TOP, and with only the default there is no
-     * way to express it, so the column can be sorted one way and not the other.
-     */
-    blank_position?: "top" | "bottom";
-}
-/** A filter condition over one output column (wire shape of a filter node).
- *  `C` is the key's type — see `QuerySortKey`. */
-export interface QueryFilterFieldCondition<C extends string = string> {
-    node_type: "condition";
-    field_key: C;
-    type?: string;
-    operator: string;
-    value?: unknown;
-}
-/**
- * A condition on the row's OWN id rather than on a field — the fetch-by-id
- * filter. It carries no `field_key` because a record has no field holding its
- * own id, and the engine dispatches on `type` before it reads one.
- */
-export interface QueryFilterRecordIdCondition {
-    node_type: "condition";
-    type: "record_id";
-    operator: string;
-    value?: unknown;
-}
-export type QueryFilterCondition<C extends string = string> = QueryFilterFieldCondition<C> | QueryFilterRecordIdCondition;
-/** A boolean group of filter nodes (wire shape — recursive). */
-export interface QueryFilterGroup<C extends string = string> {
-    node_type: "group";
-    logic: "and" | "or";
-    children: Array<QueryFilterCondition<C> | QueryFilterGroup<C>>;
-}
-/**
- * Runtime filter applied AFTER the named query, bounded to its output columns
- * (same exposure invariant as `sort`) — at compile time through `C`, and again
- * on the server. Build a group from per-column filters with
- * `columnFilterToConditions` (`@lotics/ui/column_filter`).
- */
-export type QueryFilter<C extends string = string> = QueryFilterCondition<C> | QueryFilterGroup<C>;
-/**
- * The type a runtime `filter`/`sort` key takes on alias `K`: the union codegen
- * wrote into `AppQueryColumns`, else `string` (the server's check is then the
- * only one). A computed key must be narrowed to the union to compile.
- */
-export type ColumnKeyOf<K extends string> = K extends keyof AppQueryColumns ? AppQueryColumns[K] & string : string;
-/** Options shared by every query hook. `C` is the filter/sort key's type — see
- *  `ColumnKeyOf`. */
-export interface BaseQueryOptions<C extends string = string> {
-    /**
-     * 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
-     * primitive for search-as-you-type (skip until the user types) and for detail
-     * queries (skip until a row is selected) — a parameterized search filter
-     * matches everything on an empty term, so an always-on query would dump the
-     * whole table on first paint. Default `true`.
-     */
-    enabled?: boolean;
-    /**
-     * When `false`, the query does not auto-refetch on window focus / tab return /
-     * network reconnect (`refetch()` still works). Default `true`, right for
-     * dashboards that should stay fresh. Set `false` for transient queries — a
-     * search bound to an ephemeral term, or on-demand detail — where a refocus
-     * re-run is wasted work and a visible reload.
-     */
-    revalidateOnFocus?: boolean;
-    /**
-     * Sort the result by output columns at runtime. Changing it re-queries (it is
-     * part of the cache key). Empty/omitted leaves the query's own order intact.
-     */
-    sort?: QuerySortKey<C>[];
-    /**
-     * Filter the result by output columns at runtime. Changing it re-queries.
-     * Compose from per-column UI filters via `columnFilterToConditions`.
-     */
-    filter?: QueryFilter<C>;
-}
-/** Options for `useQuery` — a single fetch. */
-export interface QueryOptions<C extends string = string> extends BaseQueryOptions<C> {
-    /** 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<C extends string = string> extends BaseQueryOptions<C> {
-    /** Rows per page. `loadMore()` appends the next page. */
-    pageSize: number;
-}
-/**
- * Options for `useCount` — one number, no rows.
- *
- * `sort` and `pageSize` are absent rather than ignored. A count is a single-row
- * COUNT over the filtered set; ordering it and paginating it are meaningless,
- * and an option a hook silently drops is worse than one that will not compile.
- */
-export type CountOptions<C extends string = string> = Omit<BaseQueryOptions<C>, "sort">;
-/** Return value of `useCount` — the size of a filtered set, and nothing else. */
-interface CountState extends QueryStateBase {
-    /** Rows in the filtered set. `undefined` until the count resolves. */
-    total: number | undefined;
-}
-/** Options for `usePaginatedQuery` — page-model with a total. */
-export interface PaginatedQueryOptions<C extends string = string> extends BaseQueryOptions<C> {
-    /** Rows per page. Default 25. */
-    pageSize?: number;
-    /**
-     * The total, when the SCREEN already knows it — which suppresses the hook's
-     * own count request entirely.
-     *
-     * Three states, all of them in the type: **omitted** → the hook counts;
-     * **`null`** → yours, not resolved yet; **a number** → yours, use it. `null`
-     * is what makes the option usable at all, because the natural source is an
-     * aggregate that is still loading on the first render — with only
-     * "number-or-nothing" the hook would fire the count it exists to avoid and
-     * throw the result away the moment the real number landed. So read it as
-     * `?? null`:
-     *
-     * ```tsx
-     * const summary = useQuery("orderStats", params);   // one ungrouped aggregate
-     * const rows = usePaginatedQuery("orders", params, {
-     *   pageSize: 100,
-     *   total: (summary.rows[0]?.row_count as number | undefined) ?? null,
-     * });
-     * ```
-     *
-     * Until the number arrives the hook reports `total: undefined` and `hasMore`
-     * falls back to "the page came back full" — exactly its behaviour while a
-     * count is in flight.
-     *
-     * Worth reaching for when a screen already renders the same figure: a `count`
-     * request re-executes the whole named query server-side, so a summary reading
-     * "N items" beside a table of those N rows is otherwise paying for that number
-     * twice, and both executions grow with the filtered set.
-     *
-     * The number must count the SAME set the query returns — the hook derives
-     * `totalPages` and `hasMore` from it and cannot tell that it doesn't.
-     *
-     * `refetch()` does not refresh it; it is yours, so refresh its source.
-     */
-    total?: number | null;
-}
-/**
- * Trigger a workflow by alias from the app's manifest.
- *
- * The alias must be declared in `package.json` "lotics.workflows" and synced
- * to `apps.workflows` on the last deploy.
- *
- * Per-app CLI codegen (`lotics app pull` / `app dev` / `app deploy`) writes
- * `.lotics/app_workflows.d.ts` augmenting `AppWorkflows` with the declared
- * alias → input-type map. Result:
- *   - Undeclared alias → compile-time error at the `useWorkflow("...")` site
- *   - Declared with full `{workflow_id, inputs}` form → callable typed as
- *     `(inputs: <DeclaredShape>) => Promise<WorkflowResult>`
- *   - Declared with shorthand (bare workflow_id) → callable typed as
- *     `(inputs?: Record<string, unknown>) => Promise<WorkflowResult>` (untyped inputs)
- *
- * ```tsx
- * const issue = useWorkflow("issueInvoiceStorageDrop");
- * // Guard the addressing column: a grouped query's rows carry none, and the
- * // workflow would be handed `undefined` where it declares a record.
- * if (row.__source_record_id) await issue({ record_id: row.__source_record_id });
- * ```
- */
-export declare function useWorkflow<K extends keyof AppWorkflows & string>(alias: K): UseWorkflowFn<K>;
-export declare function useWorkflow(alias: string): (inputs?: Record<string, unknown>) => Promise<WorkflowResult>;
-type ResultDataOf<K extends string> = K extends keyof AppWorkflowResults ? AppWorkflowResults[K] : unknown;
-type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? AppWorkflows[K] extends Record<string, never> ? (inputs?: Record<string, never>) => Promise<WorkflowResult<ResultDataOf<K>>> : (inputs: AppWorkflows[K]) => Promise<WorkflowResult<ResultDataOf<K>>> : (inputs?: Record<string, unknown>) => Promise<WorkflowResult<ResultDataOf<K>>>;
-/**
- * Result of an app-workflow run — the execute endpoint's response. `files` holds
- * any document a workflow step generated (e.g. via a `generate_*_from_template`
- * tool), resolved for download: read `files[0].url` and pass it to `openExternal`.
- * A workflow that generates no file resolves with `files` absent.
- *
- * `data` is the structured value the workflow returned via `return({ data })`,
- * typed per the alias's declared `outputs` schema (`unknown` when none was declared).
- *
- * A transport/gateway failure (a Cloudflare 524 timeout on a long run, any 5xx,
- * or a non-JSON error page) **resolves** with `{ status: "error", message }` —
- * a body-free, friendly message — rather than rejecting with a raw HTML body.
- * So an app handles every failure (handled workflow error AND transport error)
- * by checking `result.status === "error"`; it never receives gateway HTML.
- */
-export interface WorkflowResult<TData = unknown> {
-    status: "success" | "error";
-    message?: string;
-    files?: UploadedFile[];
-    data?: TData;
-    /**
-     * Per-input refusals, keyed by the INPUT name the alias declares — what a
-     * form wires straight onto the control that is wrong
-     * (`<FormField error={result.field_errors?.ly_do}>`), where `message` can
-     * only say it at the dialog's scope.
-     *
-     * Either half of the round trip fills it: the SERVER, when the payload does
-     * not match what the alias declares, and the workflow's own
-     * `return({ field_errors })`. One key, so a screen wires the control once
-     * rather than branching on which half refused. A step whose write the
-     * target table refuses (its `before_*` workflow, a unique tuple) keys its
-     * sentence by the FIELD key (`fld_…`) instead, since the table has never
-     * heard of the input. Absent when nothing named a field — and an older
-     * server names none.
-     */
-    field_errors?: Record<string, string>;
-}
-/**
- * The (params, opts) tail of a query hook for alias `K`: `params` optional when
- * the alias declares none, required otherwise, then an optional `opts` — a
- * variadic tuple so `f("a", { … })` and `f("a", params, { … })` both type-check.
- * ONE conditional signature, never a typed overload beside a loose
- * `alias: string` one: a rejected filter key would fall through to the loose
- * overload and compile.
- */
-type QueryArgs<K extends string, O> = K extends keyof AppQueries ? AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>, opts?: O] : [params: AppQueries[K], opts?: O] : [params?: Record<string, unknown>, opts?: O];
-/**
- * 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
- * the canonical AST; this is what bounds a public app's data exposure to
- * exactly the queries the manifest declares.
- *
- * ```tsx
- * const { rows, loading } = useQuery("openOrders", { status: "open" });
- * ```
- *
- * Per-app CLI codegen writes `.lotics/app_queries.d.ts` augmenting `AppQueries`
- * with the declared alias → param-type map, so an undeclared alias is a
- * compile-time error and params are typed per the manifest. The same file names
- * the alias's projected columns, which is what bounds a ROW read — see `RowOf`.
- */
-export declare function useQuery<K extends string>(alias: K, ...args: QueryArgs<K, QueryOptions<ColumnKeyOf<K>>>): QueryState<RowOf<K>>;
-/** The resolved option set of one select column, plus an index for value
- *  rendering. The companion to a query row, for select fields. */
-export interface FieldOptions {
-    /** The source field's display name — e.g. a picker/section label. */
-    label: string;
-    /**
-     * Every option of the field — `{ key, label, color, mark? }`. Includes options not
-     * present in any current row, so a freshly-added option appears in a picker
-     * without an app change, and a removed one drops out.
-     */
-    options: ResolvedOption[];
-    /**
-     * Resolve one option by key — for COLORING A STORED VALUE: pair with
-     * `readSelect(cell)[0]?.key`. `undefined` for an unknown key (option removed
-     * after the cell was written); render the cell's own label with a neutral
-     * badge in that case.
-     */
-    byKey: (key: string) => ResolvedOption | undefined;
-}
-/** Return value of `useFieldOptions`. `C` is the column key's type — the alias's
- *  projected outputs, see `ColumnKeyOf`. */
-export interface FieldOptionsState<C extends string = string> {
-    /**
-     * Resolved option sets keyed by the query's OUTPUT column name — the alias's
-     * own columns, so a key belonging to another query is a `tsc` error rather
-     * than a `[]` picker nobody can open.
-     *
-     * EVERY key is optional, and that is the shape rather than a hedge: a select
-     * column the server could not resolve to a source field (a UNION output whose
-     * arms disagree, a computed column) is genuinely absent, and a non-select
-     * column never had options. Read through it (`fields.status?.options ?? []`).
-     */
-    fields: Partial<Record<C, FieldOptions>>;
-    loading: boolean;
-    isValidating: boolean;
-    error: string | null;
-    /** Re-fetch — after a known field-config change (rare). */
-    refetch: () => void;
-}
-/** Options for `useFieldOptions`. */
-export interface FieldOptionsOptions {
-    /** Defer the fetch until true — e.g. a picker that only needs options once an
-     *  edit drawer opens. Defaults to true. */
-    enabled?: boolean;
-}
-/**
- * Resolve the full option set (key, label, color) of a named query's `select`
- * columns — the picker companion to `useQuery`. Where a query CELL carries only
- * the options a record actually holds (key + label, no color), this returns each
- * select column's COMPLETE option list with colors, straight from the field
- * config — so it populates a dropdown AND colors a stored value, and a freshly
- * added/removed option flows through with no app change.
- *
- * Addressed by the same alias you query: the option sets resolve from the named
- * query's output columns, scoped exactly like running it, and `fields` is keyed
- * by that same union — the alias that CARRIES the column is the one to ask, and
- * asking another is a compile error instead of an empty picker. A column the
- * server can't map to a source select field (UNION output, computed column) is
- * absent, so every key is optional.
- *
- * ```tsx
- * const { fields } = useFieldOptions("records");
- * // populate + color a picker:
- * <Select variant="native" options={fields.status?.options ?? []}
- *   renderOptionContent={(o) => <Status option={o} />} />
- * // color a stored value:
- * <Status option={fields.status?.byKey(readSelect(r.status)[0]?.key ?? "")} />
- * ```
- */
-export declare function useFieldOptions<K extends keyof AppQueries & string>(alias: K, opts?: FieldOptionsOptions): FieldOptionsState<ColumnKeyOf<K>>;
-export declare function useFieldOptions(alias: string, opts?: FieldOptionsOptions): FieldOptionsState;
-/**
- * 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 string>(alias: K, ...args: QueryArgs<K, InfiniteQueryOptions<ColumnKeyOf<K>>>): InfiniteQueryState<RowOf<K>>;
-/**
- * Page-model query with a total — the data hook behind a numbered, jumpable
- * table (pairs with `@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 string>(alias: K, ...args: QueryArgs<K, PaginatedQueryOptions<ColumnKeyOf<K>>>): PaginatedQueryState<RowOf<K>>;
-/**
- * HOW MANY rows a query matches — one number, no rows fetched.
- *
- * The shape behind a facet chip, a queue badge, a "N awaiting approval" tile:
- * the screen wants the size of a set it is not listing. Reach for it instead of
- * the two things that used to stand in for it, both of which are worse:
- *
- * - `usePaginatedQuery(alias, params, { pageSize: 1 })` buys a row nobody
- *   renders — two requests for one integer, against a server that bounds how
- *   many app queries run at once.
- * - A hand-rolled `rpc("query", { count: true })` is one request and leaves the
- *   cache: it does not dedupe with the page beside it, does not revalidate on
- *   focus, and never hears the host's post-write refetch. The number then goes
- *   stale over a set that has moved while everything around it updates, which
- *   is the failure worth avoiding — a count that is quietly wrong costs more
- *   than a count that costs a request.
- *
- * ONE COUNT PER FILTERED SET. The cache key is `(alias, params, filter)` — the
- * very key `usePaginatedQuery` counts under — so a table and a badge over the
- * same set issue ONE count between them, and a page click or a re-sort reuses
- * it (a count is sort- and page-independent).
- *
- * **N counts over one source should not be N hooks.** Each declared query
- * re-executes its whole `from` tree, so four facets mounted as four `useCount`s
- * are four full scans that land in the same burst. When the counts differ only
- * by a bucket the rows can be grouped on, one `group` query returns them all in
- * a single scan and folds client-side (queries.md §10) — and its figure can be
- * handed to `usePaginatedQuery`'s `total` so the list stops counting too. This
- * hook is for the count that has no sibling to group with.
- *
- * ```tsx
- * const { total } = useCount("orders", { q }, { filter: unpaidFilter });
- * return <Status label={total == null ? "…" : `${total}`} />;
- * ```
- */
-export declare function useCount<K extends string>(alias: K, ...args: QueryArgs<K, CountOptions<ColumnKeyOf<K>>>): CountState;
-/** A file the host has stored and resolved serving URLs for. */
-export interface UploadedFile {
-    id: string;
-    filename: string;
-    mime_type: string;
-    url?: string;
-    thumbnail_url?: string;
-}
-interface FileUploadState {
-    /**
-     * Upload one file. Resolves to the stored file; pass `UploadedFile.id` into
-     * a `useWorkflow` call to attach it to a record. Rejects on failure — the
-     * file is never partially stored.
-     *
-     * `fidelity` says how much of the image must survive storage; it defaults to
-     * `"high"`, which keeps the text of a photographed document legible. Only
-     * photographs are affected — a PDF, Word or Excel file is stored untouched at
-     * every step. Pass `"standard"` for bulk visual capture (a forty-photo survey,
-     * where the volume is what costs you), or `"original"` when the pixels
-     * themselves are the evidence.
-     */
-    upload: (file: File, options?: {
-        fidelity?: ImageFidelity;
-    }) => Promise<UploadedFile>;
-    /** True while any upload from this hook is in flight. */
-    uploading: boolean;
-    /** Message of the most recent failed upload, cleared when a new one starts. */
-    error: string | null;
-}
-/**
- * Upload files from an app. The bytes are stored via a presigned
- * direct-to-storage upload the host mediates; the API server never proxies
- * them. Works the same in a public (anonymous) app and a member-facing one.
- *
- * ```tsx
- * const { upload, uploading } = useFileUpload();
- * const submit = useWorkflow("submitApplication");
- * const cccd = await upload(file);
- * await submit({ ...fields, cccd_file_id: cccd.id });
- * ```
- */
-export declare function useFileUpload(): FileUploadState;
-/**
- * Attachments with the optimistic-preview UX: a local object-URL preview shows
- * the INSTANT a file is added, the upload runs in the background, and the
- * stored `file_id` lands in `files` when it completes. Picking is the app's
- * (button / paste / drop) — pass the resulting `File[]` to `add`, or to
- * `attach` where a write has to wait for the ids.
- *
- * WHICH LIFECYCLE is the caller's one decision. A composer accumulates and
- * clears when it sends; a record's section passes what its row now holds as
- * `landed`, and each entry leaves the queue as the pile takes it over.
- *
- * ```tsx
- * const { files, add, remove, clear, uploading, fileIds } = useAttachments();
- * const design = useWorkflow("design");
- * // attach:  <Button icon="paperclip" onPress={() => pickFiles({ accept: "image/*" }).then(add)} />
- * // preview: map each AttachedFile to a @lotics/ui DisplayFile (snake_case → camelCase) — the
- * //          app owns this data→UI adapter; the SDK never imports @lotics/ui:
- * //   files.map((f) => (
- * //     <FileThumbnail
- * //       file={{ id: f.id, filename: f.filename, mimeType: f.mime_type, url: f.preview_url }}
- * //       uploading={f.status === "uploading"} onRemove={() => remove(f.id)} />
- * //   ))
- * // send:    design({ photo: fileIds[0] }); clear();
- * ```
- *
- * The queue is `useAttachmentQueue`, bound here to the app's own upload.
- */
-export declare function useAttachments(options?: AttachmentsOptions): AttachmentsState;
-/**
- * Publish a slice of the CURRENT SCREEN's view state to the app's ambient chat
- * agent, so a member chatting alongside the app gets an agent that knows what
- * they are looking at — which list is filtered to what, which record is open,
- * what is typed into a form. Declarative and lifecycle-bound: mounting or
- * changing `context` pushes it to the host; unmounting, renaming the `slot`, or
- * passing `null` clears it. Independent components may publish different `slot`s
- * concurrently (a list screen + an open detail drawer); the newest value per
- * slot wins.
- *
- * **Push-only, and a SNAPSHOT of what the app already RENDERED to this member** —
- * never a channel for chat to pull app-authority data. `records` are passed as
- * raw `{ table_id, record_id }` refs (unresolved); the member's own chat agent
- * acts on them only where that member's IAM already allows. The host feeds
- * `description`/`data` into the agent's prompt as clearly-labeled DATA, never as
- * instructions.
- *
- * Host-enforced caps (exceeding them truncates/drops — never an error): `slot`
- * ≤ 50 chars; `description` ≤ 1000 chars (truncated with "…"); `records` ≤ 20;
- * `data` must JSON-serialize to ≤ 2000 chars or the `data` field is dropped (the
- * description is kept); ≤ 8 slots per app (a 9th evicts the least-recently
- * updated).
- *
- * ```tsx
- * useAiContext("orders_list", {
- *   description: `Viewing ${rows.length} orders filtered to status=open, sorted by due date.`,
- *   // `flatMap` + the guard, not `map`: the addressing columns are absent on a
- *   // GROUPED query's rows, so a ref built without checking carries `undefined`
- *   // and points the agent at nothing.
- *   records: rows.flatMap((r) =>
- *     r.__source_table_id && r.__source_record_id
- *       ? [{ table_id: r.__source_table_id, record_id: r.__source_record_id }]
- *       : [],
- *   ),
- *   data: { filter: "status=open", sort: "due_date desc" },
- * });
- * ```
- *
- * No-ops with no embedding host (standalone on the app's own origin — there is no
- * chat surface to inform) and in mock mode. Since 0.52.
- */
-export declare function useAiContext(slot: string, context: AiContextValue | null): void;
-interface MembersState {
-    /** Members of the app's organization, for assign / member-picker UIs. */
-    members: ResolvedMember[];
-    loading: boolean;
-    error: string | null;
-}
-/** Options for `useMembers`. */
-export interface MembersOptions {
-    /**
-     * Restrict to one member group, as `GRP.<group>` from `.lotics/app_fields.ts`
-     * (a pasted `grp_…` id is refused by `lotics app check` — it resolves to
-     * nothing in a copy of the app). The group must be declared on a `member`
-     * workflow input's `group` — listing an undeclared group errors. Omit to list
-     * the whole org roster.
-     */
-    group?: string;
-}
-/**
- * List the members of the app's organization — the candidate set for an
- * "assign to a member" picker. Each member is `{ id, name, email, image }`
- * (`image` = avatar URL, may be null). Resolves through the host (member-only;
- * an anonymous public visitor gets an error). Names may be empty for members
- * without a display name set — fall back to `email`.
- *
- * Gated: the app must DECLARE that it works with members — it needs a workflow
- * whose manifest declares a `member`-typed input. Passing `{ group }` restricts
- * to that group, and is only honored if some member input declares that
- * `group` — so an app can only list (and assign into) groups it declares.
- *
- * ```tsx
- * const { members } = useMembers({ group: GRP.sale });
- * // <Select variant="native" options={members.map((m) => ({
- * //   value: m.id, label: m.name || m.email || m.id, image: m.image,
- * // }))} />
- * ```
- */
-export declare function useMembers(opts?: MembersOptions): MembersState;
-type AgentOutputOf<K extends string> = K extends keyof AppAgentResults ? AppAgentResults[K] : unknown;
-/** Options for one `run(...)` call — the app-owned session key it belongs to. */
-export interface AgentRunOptions {
-    /** Groups this run with prior runs in the same working session; the agent
-     *  re-reads them for context. Mint a new id to "clear context". */
-    sessionId: string;
-    /** Deliberately abort the run in flight and start this one in its place.
-     *  Without it, `run()` is SINGLE-FLIGHT: a call while a run is streaming
-     *  returns the in-flight run's promise instead of starting (and billing) a
-     *  second run — so an accidental double-press resolves with the first run's
-     *  result. The aborted-and-replaced run still executes and bills server-side;
-     *  replacement is a deliberate act, never a side effect of an extra click. */
-    replace?: boolean;
-}
-/** The live state + controls returned by `useAgentRun`. */
-export interface UseAgentRun<TInput, TOutput> {
-    /** Start a run — streams progress into this hook's state and resolves with how
-     *  the leg ENDED (`settled` / `parked` / `failed` / `aborted`). Read `kind`
-     *  rather than the hook's state: this value is a snapshot at settle, whereas
-     *  the state has not committed yet when the promise resolves. SINGLE-FLIGHT —
-     *  a second call while one is streaming joins the first (see `replace`). */
-    run: (input: TInput, opts: AgentRunOptions) => Promise<AgentRunLanding<TOutput>>;
-    /** Stop listening locally (no server effect) — the run keeps executing
-     *  server-side and its result lands in the session history. Used on unmount. */
-    abort: () => void;
-    /** Explicitly stop the run server-side (saves tokens) AND locally. Wire a
-     *  user-facing "Stop" button to this, not `abort`. */
-    cancel: () => void;
-    /** `awaiting_input` = the run is PARKED on a question the agent asked
-     *  (`pendingChoice` carries it); `answerChoice` continues the run. */
-    status: "idle" | "streaming" | "awaiting_input" | "completed" | "error";
-    /** The ordered run transcript as ai-sdk `parts` — prose interleaved with tool
-     *  calls, in stream order. Feed straight to `@lotics/ui` `AgentRun`:
-     *  `<AgentRun parts={run.parts} state={run.status === "streaming" ? "streaming" : run.status === "error" ? "error" : "done"} />`
-     *  — no hand-assembly. */
-    parts: AgentUIPart[];
-    /** The agent's pending ask — non-null exactly while `status` is
-     *  `awaiting_input`. `questions` maps 1:1 onto `@lotics/ui`'s `ClarifyWizard`
-     *  (`{question, options: {label, description}[], allow_custom}`). */
-    pendingChoice: PendingChoice | null;
-    /** Answer the pending ask and CONTINUE the run — one `{value, custom}` per
-     *  question, aligned by index (exactly what `ClarifyWizard`'s `onSubmit`
-     *  yields). Streams the continuation into the same `parts` and resolves like
-     *  `run` — a landing, which may be `parked` again for a follow-up ask. Rejects
-     *  when nothing is pending, or when the server refuses the answer (the run
-     *  stays parked; show the error and keep the wizard open). */
-    answerChoice: (answers: {
-        value: string;
-        custom: boolean;
-    }[]) => Promise<AgentRunLanding<TOutput>>;
-    /** The agent's ANSWER prose (every `text` part concatenated), accumulating live —
-     *  excludes thinking (`reasoning` is its own part). For a FREE-TEXT agent this IS
-     *  the result; a structured agent's result is `output`. Derived from `parts`. */
-    text: string;
-    /** The structured result once the run completes — the agent's `submit_result`
-     *  output. `undefined` when the run produced none (a free-text agent, or one that
-     *  finished without submitting); a free-text answer lives in `text`, never here.
-     *  So it is safe to treat a present `output` as the declared shape — but still
-     *  validate untrusted inner fields (the model authored the `submit_result` body,
-     *  so e.g. an array field may be missing/mistyped). */
-    output?: TOutput;
-    error?: string;
-}
-/**
- * Run a streaming agent declared in `package.json` lotics.agents and invoked by
- * alias. `run(input, { sessionId })` starts it; progress streams into `status` +
- * the ordered `parts` transcript (feed straight to `@lotics/ui` `AgentRun`). A
- * STRUCTURED agent's result lands in `output`; a FREE-TEXT agent's answer is the
- * transcript's prose (`text`). Read the session's history with `useAgentRuns`.
- *
- * ```tsx
- * const recognize = useAgentRun("recognize");
- * await recognize.run({ image_file_id }, { sessionId });
- * // <AgentRun parts={recognize.parts} state={recognize.status === "streaming" ? "streaming" : "done"} />
- * // then read recognize.output (structured) or recognize.text (free-text)
- * ```
- */
-export declare function useAgentRun<K extends keyof AppAgents & string>(alias: K): UseAgentRun<AppAgents[K], AgentOutputOf<K>>;
-export declare function useAgentRun(alias: string): UseAgentRun<Record<string, unknown>, unknown>;
-/** One persisted run in a session's history (the `/agent-runs` row shape). */
-export interface AgentRunRecord {
-    id: string;
-    agent_alias: string;
-    session_id: string;
-    status: string;
-    input: Record<string, unknown> | null;
-    output: unknown;
-    error_message: string | null;
-    started_at: string;
-    completed_at: string | null;
-    /** Single-run GET only, while `status` is "awaiting_input": the pending ask
-     *  derived server-side from the transcript — lets a reconnecting client
-     *  rebuild the question without the live stream. */
-    pending_interactive?: {
-        tool_call_id: string;
-        tool_name: string;
-        input: unknown;
-    } | null;
-}
-interface AgentRunsState {
-    runs: AgentRunRecord[];
-    loading: boolean;
-    error: string | null;
-    refetch: () => void;
-}
-/**
- * The run history of a session, oldest-first — the persisted outputs the app
- * renders as a session log (NOT a chat: a flat list of past runs). Refetch
- * after a `run(...)` completes to pull in the new one.
- *
- * ```tsx
- * const { runs } = useAgentRuns(sessionId);
- * ```
- */
-export declare function useAgentRuns(sessionId: string, opts?: {
-    enabled?: boolean;
-    revalidateOnFocus?: boolean;
-}): AgentRunsState;