@lotics/app-sdk 0.101.2 → 0.102.1

package/AGENTS.md

@@ -15,7 +15,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 
 | Doc | Read it for |
 |---|---|
-| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
 | [docs/queries.md](./docs/queries.md) | **The query engine reference** — AST node kinds, per-field-type operators, filters/params/pruning, free-text search, combining tables, shaping (aggregates, date buckets, windows), runtime refinement bounds, limits and the efficiency playbook. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path; `useWorkflows` for writes that are data), the `WorkflowResult` resolve-never-throw contract (`field_errors`), typed inputs, every write drawn on every read from the press — predicted from the workflow's own steps, taken back on a refusal, `pending` meanwhile — the re-read a successful write triggers over the tables its body names, diff-before-update, locked records, `useNewRecord`, read-after-write ordering (`writesSettled()`), `useRecording`. |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY reference** — the JS subset a body may use, opaque `fld_*`/`opt_*` keys, every step form, the accepted sugar, helpers, record-write surfaces, the traps and the verify loop. |

package/dist/{chunk-ARV5FAU5.js → chunk-ZOFKWF6V.js}

@@ -898,6 +898,8 @@ function rpcStandalone(op, payload) {
   switch (op) {
     case "query":
       return standaloneQuery(payload);
+    case "export":
+      return standaloneExport(payload);
     case "field_options":
       return standaloneFieldOptions(payload);
     case "workflow":
@@ -1029,6 +1031,10 @@ async function standaloneQuery(payload) {
   const { app_id } = await boot();
   return apiCall("POST", `/v1/apps/${app_id}/query`, payload, { appId: app_id });
 }
+async function standaloneExport(payload) {
+  const { app_id } = await boot();
+  return apiCall("POST", `/v1/apps/${app_id}/export`, payload, { appId: app_id });
+}
 async function standaloneFieldOptions(p) {
   const { app_id } = await boot();
   return apiCall("POST", `/v1/apps/${app_id}/field-options`, { alias: p.alias }, { appId: app_id });

package/dist/hooks.d.ts

@@ -151,6 +151,8 @@ export interface MembersOptions {
      * declares. Omit for the whole roster.
      */
     group?: string;
+    /** `false` reads no roster: `members` stays empty and `loading` false. Default `true`. */
+    enabled?: boolean;
 }
 /**
  * The organization's members, for an assign picker. Member-only, and gated on

package/dist/index.d.ts

@@ -5,8 +5,8 @@ export { reportAppError } from "./error_report.js";
 export type { AppErrorKind } from "./error_report.js";
 export { useWorkflow, useWorkflows, writesSettled, useFileUpload, useAttachments, useAttachmentPiles, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export type { UploadedFile, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunLanding, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, } from "./hooks.js";
-export { useQuery, useQueries, queryAll, useFieldOptions } from "./queries.js";
-export type { QueryRow, QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, } from "./queries.js";
+export { useQuery, useQueries, queryAll, exportQuery, useFieldOptions } from "./queries.js";
+export type { QueryRow, QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, ExportCall, ExportFile, ExportReport, } from "./queries.js";
 export type { AttachedFile, AttachmentPiles, AttachmentPilesOptions, AttachmentsOptions, AttachmentsState } from "./attachments.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
@@ -27,7 +27,7 @@ export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
 export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
-export type { AppFixture, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
+export type { AppFixture, MockExport, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
 export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
 export { row, readLinks, readFiles, readLocked, readCreatedAt, readUpdatedAt, PENDING } from "./row.js";
 export type { ResolvedLink, AppFile } from "./row.js";

package/dist/index.js

@@ -21,7 +21,7 @@ import {
   subscribeRecordings,
   subscribeUrlParams,
   urlParam
-} from "./chunk-ARV5FAU5.js";
+} from "./chunk-ZOFKWF6V.js";
 
 // src/mount.tsx
 import { createRoot } from "react-dom/client";
@@ -59,6 +59,10 @@ function getMockWorkflow(alias) {
   if (!isMockMode()) return null;
   return registeredFixture?.workflows?.[alias] ?? null;
 }
+function getMockExport(alias) {
+  if (!isMockMode()) return null;
+  return registeredFixture?.exports?.[alias] ?? null;
+}
 function getMockRecordings() {
   if (!isMockMode()) return null;
   return registeredFixture?.recordings ?? null;
@@ -24134,6 +24138,7 @@ function appWorkflowOutputDepth(output) {
   if (output.type === "array") return 1 + appWorkflowOutputDepth(output.items);
   return 1;
 }
+var APP_ALIAS_REGEX = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 var MAX_APP_CAPABILITY_DESCRIPTION = 300;
 var APP_ANONYMOUS_REQUEST_MAX_BYTES = 256 * 1024;
 var APP_UPLOAD_MAX_BYTES = 25 * 1024 * 1024;
@@ -24166,6 +24171,13 @@ var appWorkflowContractSchema = zod_default.object({
   inputs: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional(),
   outputs: zod_default.record(zod_default.string(), appWorkflowOutputSchema).optional()
 });
+var APP_EXPORT_REPORT_KEYS = ["title", "lines", "readings"];
+var appExportTemplateSchema = zod_default.object({
+  template_id: zod_default.string().min(1).describe("The document template (`dtl_\u2026`) filled: an Excel workbook, or an HTML page made a PDF."),
+  rows: zod_default.string().regex(APP_ALIAS_REGEX).refine((key) => !APP_EXPORT_REPORT_KEYS.some((taken) => taken === key), {
+    message: `The rows are listed under a key of their own, never ${APP_EXPORT_REPORT_KEYS.join(", ")}.`
+  }).describe(`The key the template lists the rows under, beside ${APP_EXPORT_REPORT_KEYS.join(", ")}.`)
+}).strict();
 var appQueryDeclarationSchema = zod_default.object({
   ast: zod_default.unknown().describe(
     "Query AST template (a QueryNode). Validated server-side via parseQueryNode at deploy. May embed {{params.<name>}} tokens in filter value positions."
@@ -24175,6 +24187,9 @@ var appQueryDeclarationSchema = zod_default.object({
   ),
   description: zod_default.string().optional().describe(
     `What this query returns, in one line \u2014 read by an agent choosing between the app's aliases. An alias is a JS identifier, which names a query without saying what it covers. Capped at ${MAX_APP_CAPABILITY_DESCRIPTION} characters.`
+  ),
+  templates: zod_default.record(zod_default.string().regex(APP_ALIAS_REGEX), appExportTemplateSchema).optional().describe(
+    "Document templates an export of this query's rows may fill, by the name the export asks for. An export names one of these or none; a template it does not declare is refused."
   )
 });
 var appAgentDeclarationSchema = zod_default.object({
@@ -28006,7 +28021,7 @@ function useAiContext(slot, context) {
 function useMembers(opts) {
   const group = opts?.group;
   const roster = useKey(
-    JSON.stringify(["members", group ?? null]),
+    opts?.enabled === false ? null : JSON.stringify(["members", group ?? null]),
     async () => {
       const members2 = (await rpc("members", { group })).members ?? [];
       noteMembers(members2);
@@ -30649,23 +30664,27 @@ function overlayAsked(alias, params, narrowing, askedAt, totalsOf, rows, back, a
 }
 
 // src/queries.ts
-function mockedRows(alias, call) {
-  const mocked = getMockRows(alias, call);
-  if (mocked === null) return void 0;
+function pageOf(mocked, call) {
   const start = call.keyset === true ? Number(call.cursor ?? 0) : call.offset ?? 0;
   const end = call.limit === void 0 ? mocked.length : start + call.limit;
   const rows = mocked.slice(start, end);
   const more = end < mocked.length;
   return { rows, truncated: call.keyset !== true && more, next_cursor: call.keyset === true && more ? String(end) : null };
 }
-function mockedCount(alias, call) {
+function countOf(mocked, by) {
+  return { total: mocked.length, ...by === void 0 ? {} : { counts: countsOf(mocked, by) } };
+}
+function knownRows(alias, call) {
+  const mocked = getMockRows(alias, call);
+  return Array.isArray(mocked) ? pageOf(mocked, call) : void 0;
+}
+function knownCount(alias, call) {
   const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  if (mocked === null) return void 0;
-  return { total: mocked.length, ...call.by === void 0 ? {} : { counts: countsOf(mocked, call.by) } };
+  return Array.isArray(mocked) ? countOf(mocked, call.by) : void 0;
 }
 async function askRows(key, alias, askedAt, call, since = askedAt) {
-  const mocked = mockedRows(alias, call);
-  if (mocked !== void 0) return mocked;
+  const mocked = getMockRows(alias, call);
+  if (mocked !== null) return pageOf(await mocked, call);
   const answer = await rpc("query", {
     alias,
     params: call.params,
@@ -30678,8 +30697,8 @@ async function askRows(key, alias, askedAt, call, since = askedAt) {
   return answer;
 }
 async function askCount(key, alias, askedAt, call) {
-  const mocked = mockedCount(alias, call);
-  if (mocked !== void 0) return mocked;
+  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
+  if (mocked !== null) return countOf(await mocked, call.by);
   const answer = await rpc("query", {
     alias,
     params: call.params,
@@ -30720,7 +30739,7 @@ function useQuery(alias, params = {}, opts = {}) {
       limit: opts.page ?? opts.limit,
       offset: opts.page === void 0 ? 0 : page * opts.page
     }),
-    { focus, aliases: [alias], known: mocking ? () => mockedRows(alias, { params, filter: filter2, sort, limit: opts.page ?? opts.limit, offset: opts.page === void 0 ? 0 : page * opts.page }) : void 0 }
+    { focus, aliases: [alias], known: mocking ? () => knownRows(alias, { params, filter: filter2, sort, limit: opts.page ?? opts.limit, offset: opts.page === void 0 ? 0 : page * opts.page }) : void 0 }
   );
   const feedKey = !enabled || !wantsRows || opts.more === void 0 ? null : JSON.stringify(["feed", alias, call, opts.more]);
   const feedSize = opts.more ?? 0;
@@ -30761,7 +30780,7 @@ function useQuery(alias, params = {}, opts = {}) {
   const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, { params, filter: filter2, by }), {
     focus,
     aliases: [alias],
-    known: mocking ? () => mockedCount(alias, { params, filter: filter2, by }) : void 0
+    known: mocking ? () => knownCount(alias, { params, filter: filter2, by }) : void 0
   });
   const version3 = useWrittenVersion();
   const drawn2 = useMemo3(() => {
@@ -30823,7 +30842,7 @@ async function settle(read2) {
 }
 async function askGroups(key, alias, askedAt, aggregate, call) {
   const mocked = getMockRows(alias, { ...call, aggregate });
-  if (mocked !== null) return { rows: aggregateRows(mocked, aggregate), truncated: false };
+  if (mocked !== null) return { rows: aggregateRows(await mocked, aggregate), truncated: false };
   const answer = await rpc("query", { alias, params: call.params, aggregate, filter: call.filter, sort: call.sort });
   noteAnswer(key, alias, askedAt, []);
   return answer;
@@ -30892,6 +30911,13 @@ async function queryAll(alias, params = {}, opts = {}) {
     if (!page.truncated || page.rows.length === 0) return pages.flat();
   }
 }
+async function exportQuery(alias, call) {
+  const sort = call.sort === void 0 || call.sort.length === 0 ? void 0 : [...call.sort];
+  const body = { alias, params: call.params ?? {}, filter: call.filter, sort, report: call.report, file: call.file };
+  const mocked = getMockExport(alias);
+  if (mocked !== null) return mocked(body);
+  return (await rpc("export", body)).file;
+}
 var NO_UNITS = {};
 function useFieldOptions(alias, opts) {
   const enabled = opts?.enabled ?? true;
@@ -31317,6 +31343,7 @@ export {
   askAi,
   buildChoiceOutput,
   downloadFile,
+  exportQuery,
   isEmbedded,
   isWithinZone,
   mount,

package/dist/mock.d.ts

@@ -6,8 +6,8 @@
  * `useFileUpload` is not mocked.
  */
 import type { QueryAggregate } from "./shared_types.js";
-import type { WorkflowResult } from "./hooks.js";
-import type { QuerySortKey } from "./queries.js";
+import type { UploadedFile, WorkflowResult } from "./hooks.js";
+import type { ExportCall, QuerySortKey } from "./queries.js";
 import type { RecordingState } from "./recording_state.js";
 /** A result, or a function of the inputs — return a slow promise to review the pending state. */
 export type MockWorkflow = WorkflowResult | ((inputs: Record<string, unknown>) => WorkflowResult | Promise<WorkflowResult>);
@@ -19,11 +19,18 @@ export interface MockQueryCall {
     /** The groups the call asks for: a fixture answers the query's rows, and they are folded into these after it. */
     aggregate?: QueryAggregate;
 }
-/** Rows, or a function of the call — the only way to honour `filter`/`sort`/`limit`, which the fixture path has no engine for. */
-export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall) => Array<Record<string, unknown>>);
+/** Rows, or a function of the call — the only way to honour `filter`/`sort`/`limit`, which the fixture path has no
+ *  engine for. Return a promise to hold the read loading until it settles. */
+export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall) => Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>>);
+/** The file an export of a query makes, as a function of the call — return a slow promise to review the pending state. */
+export type MockExport = (call: ExportCall & {
+    alias: string;
+}) => UploadedFile | Promise<UploadedFile>;
 export interface AppFixture {
     queries?: Record<string, MockQuery>;
     workflows?: Record<string, MockWorkflow>;
+    /** By the query exported. */
+    exports?: Record<string, MockExport>;
     /** `useRecording(alias)` reads as available; `start`/`stop` change nothing. */
     recordings?: Record<string, RecordingState>;
 }
@@ -31,7 +38,9 @@ export declare function registerMockFixture(fixture: AppFixture | undefined): vo
 /** The raw `?__mock=1` flag, fixture or not; false where `window.location` is absent. */
 export declare function hasMockFlag(): boolean;
 /** Null for an unmocked alias, which reads real data. */
-export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | null;
+export declare function getMockRows(alias: string, call: MockQueryCall): Array<Record<string, unknown>> | Promise<Array<Record<string, unknown>>> | null;
 /** Null for an unmocked alias, which executes for real. */
 export declare function getMockWorkflow(alias: string): MockWorkflow | null;
+/** Null for an unmocked alias, which the server exports. */
+export declare function getMockExport(alias: string): MockExport | null;
 export declare function getMockRecordings(): Record<string, RecordingState> | null;

package/dist/queries.d.ts

@@ -1,6 +1,9 @@
 import type { QueryAggregate } from "./shared_types.js";
 import type { AppQueries, AppQueryColumns } from "./types.js";
 import type { ResolvedOption } from "./select.js";
+import type { UploadedFile } from "./hooks.js";
+import type { ReportLanguage } from "./shared_types.js";
+import type { ReportColumn, ReportReading } from "./shared_types.js";
 /**
  * One row of a query whose columns codegen could not read (a dynamic alias, a
  * bare `from_table`). Values stay `unknown` — the cell readers narrow them.
@@ -169,12 +172,44 @@ export interface QueryCall {
 export declare function useQueries(calls: readonly QueryCall[], opts?: Pick<QueryOptions, "enabled" | "revalidateOnFocus">): QueryState<QueryRow>[];
 /**
  * Every row a declared query matches, read a page at a time to the end — for what must hold every row
- * (a saved sheet), never for a screen, which pages. The server's rows as stored: no write is drawn over them.
+ * (an act over every row in view), never for a screen, which pages, nor for a file, which `exportQuery` makes on the
+ * server. The server's rows as stored: no write is drawn over them.
  */
 export declare function queryAll(alias: string, params?: Record<string, unknown>, opts?: {
     filter?: QueryFilter;
     sort?: readonly QuerySortKey[];
 }): Promise<QueryRow[]>;
+/** What an export states of its rows beside them: the page's title, one line per thing narrowing them, and the
+ *  figures over them as the screen drew them. */
+export interface ExportReport {
+    title: string;
+    lines: string[];
+    readings: ReportReading[];
+}
+/** The file an export makes: the default report workbook — its words in `language`, the rows under `columns` on the
+ *  tab `sheet` — or a template the query declares under `templates`, by its name there. */
+export type ExportFile = {
+    kind: "workbook";
+    language: ReportLanguage;
+    sheet: string;
+    columns: ReportColumn[];
+} | {
+    kind: "template";
+    template: string;
+};
+export interface ExportCall {
+    params?: Record<string, unknown>;
+    filter?: QueryFilter;
+    sort?: readonly QuerySortKey[];
+    report: ExportReport;
+    file: ExportFile;
+}
+/**
+ * Every row a declared query matches — narrowed by `filter` and ordered by `sort` as a page of it is — made into one
+ * file by the server, so no row reaches the browser. Past the most rows one export holds it is refused, never cut.
+ * Resolves the stored file, its URL signed for the caller.
+ */
+export declare function exportQuery(alias: string, call: ExportCall): Promise<UploadedFile>;
 /** One select column's full option set. */
 export interface FieldOptions {
     /** The source field's display name. */

package/dist/router.js

@@ -1,7 +1,7 @@
 import {
   isEmbedded,
   setUrlParams
-} from "./chunk-ARV5FAU5.js";
+} from "./chunk-ZOFKWF6V.js";
 
 // src/router.tsx
 import { useEffect } from "react";

package/dist/rpc.d.ts

@@ -8,7 +8,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
+export type RpcOp = "query" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
 export interface AgentRunPayload {
     alias: string;
     session_id: string;

package/dist/shared_types.d.ts

@@ -4,5 +4,16 @@
  * tarball. Written at every build, never edited.
  */
 export type QueryAggregate = { by?: readonly string[]; day?: string; sum?: string; };
+export type ReportColumn = { key: string; header: string; type: "number" | "text" | "date"; };
+export type ReportLanguage = "vi" | "en";
+export type ReportPart = { label: string; value: number; share: number | null; };
+export type ReportPivotColumn = { label: string; total: number | null; };
+export type ReportPivotRow = { label: string; values: number[]; total: number | null; };
+export type ReportPoint = { label: string; value: number; partial: boolean; };
+export type ReportReading = (ReportReadingHead & { kind: "metric"; value: number | null; }) | (ReportReadingHead & { kind: "breakdown"; byLabel: string; parts: ReportPart[]; total: number | null; }) | (ReportReadingHead & { kind: "trend"; points: ReportPoint[]; }) | (ReportReadingHead & { kind: "pivot"; rowsLabel: string; columnsLabel: string; columns: ReportPivotColumn[]; rows: ReportPivotRow[]; total: number | null; }) | { kind: "failed"; label: string; };
+export type ReportReadingHead = { label: string; valueLabel: string; unit: string | null; truncated: boolean; };
 export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
 export type TableRecordFilters = TableRecordFiltersConditionNode | TableRecordFiltersTraversalNode | TableRecordFiltersGroupNode;
+export type TableRecordFiltersConditionNode = { node_type: "condition"; field_key?: string | undefined; type?: string | undefined; operator: string; value?: unknown; unit_option?: string | undefined; };
+export type TableRecordFiltersGroupNode = { node_type: "group"; logic: "and" | "or"; children: (TableRecordFilters)[]; };
+export type TableRecordFiltersTraversalNode = { node_type: "traversal"; path: string[]; condition: TableRecordFiltersConditionNode; };

package/docs/data_fetching.md

@@ -23,7 +23,8 @@ and by `lotics app create --custom` and `lotics app deploy`. Every hook reads th
 | `useQuery(alias, params?, { more: n })` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
 | `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 | `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
-| `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set (an export): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
+| `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
+| `exportQuery(alias, { params, filter, sort, report, file })` | a promise of the file | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `report` is `{ title, lines, readings }`; `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, each column `{ key, header, type }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows it rejects, never cuts; each caller makes at most 60 exports a minute. The file's `url` is signed for the caller: open it with `openExternal` |
 
 Every hook answers the same `QueryState`: `rows`, `truncated`, `total`, `counts`, `loading`,
 `isValidating`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,

package/docs/members_and_options.md

@@ -170,6 +170,7 @@ in it, while a resolved CELL keeps naming them.
 `image` is the avatar URL (a presigned URL valid 24 hours, or the member's external OAuth photo) and
 may be `null`. `name` may be null/empty for members without a display name — fall back to `email`. On failure the hook does not throw: it
 resolves `{ members: [], loading: false, error }`.
+`{ enabled: false }` reads nothing until the screen needs the roster.
 
 Every hook reading one `group` shares one roster: it is read again when a screen reading it mounts, never on focus.
 

package/docs/queries.md

@@ -45,6 +45,14 @@ Queries live on the app, as an alias → declaration map. `set_app_query` binds
 - **`description`** — one line saying what the query returns, capped at 300 characters. No app
   code reads it: it is what the **agents** that reach this app's data (its declared agents, a
   member's chat while the app is open) read to choose between your aliases.
+- **`templates`** — the document templates an `exportQuery` of this alias may fill, by the name
+  the export asks for: `{ "<name>": { "template_id": "dtl_…", "rows": "<key>" } }`. The template
+  is filled with `{ title, lines, readings, <key>: every row }`, each row keyed by output column —
+  a figure, a yes/no, a date or moment as stored (ISO), anything else its words (options,
+  members, linked rows and files by name, comma-joined). An excel template makes a workbook, an
+  html one a PDF. Binding refuses a template that is not a live excel or html template of the
+  app's workspace, one the app's owner may not use, or one reading at its root anything but
+  those keys; `rows` is never `title`, `lines` or `readings`.
 - Aliases must be valid JS identifiers (`useQuery("openOrders")` and the generated types depend on it).
 
 A deploy never touches the bindings; `get_app_query` reads one back. The **server holds the
@@ -56,7 +64,7 @@ query's reach (a token in a `table_id` or field-key position fails validation).
 
 Binding fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
 
-1. isn't a valid identifier, or the declaration isn't `{ ast, params?, description? }` (a
+1. isn't a valid identifier, or the declaration isn't `{ ast, params?, description?, templates? }` (a
    description over 300 characters is refused here too);
 2. references `{{params.x}}` without declaring param `x` (typos can't silently widen);
 3. doesn't parse as a `QueryNode` **as the raw template** (the runtime parses the stored
@@ -226,7 +234,7 @@ supports the full §5 operator matrix **except**: `traversal` nodes, `locked`, a
 `record_id` works on any row-level derived query (rejected over a `group`, which has no row
 identity). When a `filter` directly wraps a `union` of `project(from_table)` arms and every
 condition targets bare passthrough columns, the engine pushes the predicate into each arm's
-source filter automatically (making it index-servable); otherwise it evaluates post-union.
+source filter automatically, where it runs once per record; otherwise it evaluates post-union.
 
 ### `join` — combine two row sets
 
@@ -537,9 +545,9 @@ Negation-shaped inner operators (`has_none_of`, `not_equals`, `is_none_of`,
 
 Traversals are **source-layer only** (rejected on derived columns — push them into
 `from_table.filter`). Each hop reaches the linked rows by primary key from the ids in the link
-cell. Under an OR beside column conditions a traversal runs once per row and takes the column
-conditions off their indexes with it; give it a `union` arm of its own when the other arms must
-stay index-served. Two access classes:
+cell. Under an OR beside column conditions a traversal runs once per row and takes a membership
+condition off its index with it; give it a `union` arm of its own when the other arms must keep
+theirs. Two access classes:
 
 - **Self-scoped** — inner operator `is_current_member` / `is_not_current_member`: tests only
   the viewer's own membership on the linked row, leaks nothing, and is exempt from the linked
@@ -863,7 +871,7 @@ ordering and scoping into the template or its params.
 Any other execution failure returns a generic `query execution failed` (the real error — which
 may embed SQL — is server-logged only). Bind-time and validation errors are always specific.
 
-### Index reality, in plain terms
+### What a query reads, in plain terms
 
 Records are stored partitioned by workspace, so a query reads only its own workspace's slice; a
 `from_table` narrows that slice to the table's rows, and within them:
@@ -871,39 +879,18 @@ Records are stored partitioned by workspace, so a query reads only its own works
 - **GIN-served (fast at any size):** *positive* exact-membership filters at the **source
   layer** — `select`/`select_member`/`select_record_link` `has_any_of` / `has_all_of`, and
   `is_current_member`. These compile to containment the JSONB GIN index serves.
-- **Trigram-served:** `from_table.search` (§7).
-- **B-tree-served (automatic for bound queries):** text `equals`, number and date
-  comparisons (exact and range), `from_table.sort` fields, and a one-key `sort` node over a
-  number or date field the rows pass unchanged — for fields referenced in a **bound named
-  query's template**. The platform provisions a partial expression index per referenced
-  field automatically: built online whenever `set_app_query` or `set_app_queries` binds a query, re-synced daily,
-  capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
-  A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
-  so it still gets its index. Index-seek speed at any table size once provisioned.
-- **Table scan (linear in table size):** everything else — text `contains`, negations
-  (`has_none_of`, `is_none_of`, `not_*`), emptiness, files predicates, and predicates/sorts on
-  fields that appear **only** in the runtime `filter`/`sort` options rather than the bound
-  template. Fine on thousands of rows; on very large tables these dominate latency and are the
-  usual timeout cause.
-
-**Filter shape drives latency.** Equality/range/sort predicates in the bound template are
-index-served; lead with those or a GIN-served membership filter / `search`, and let scan-shaped
-predicates refine the already-narrowed set. Derived-layer filters run over the subquery result
-(no index), so **filter at the source layer whenever the field exists there** — the runtime
-filter is for caller-driven refinement, not for the main cut (a runtime-only field gets no
-managed index). (The engine pushes eligible filter-over-union predicates down automatically,
-but don't rely on that for other shapes.)
-
-**A sorted page reads in its sort index — declare the order it is read in.** A page sorted by one
-column that passes a number or date field unchanged (a bare `project` source with no `type`
-override, an `unpivot` passthrough, or a row column that reads the same field in every row) reads
-the table in that field's sort index and stops at the page, instead of reading every row and
-sorting. Over a `union`, each arm is paged this way on its own and the arms are merged, so a
-register over several tables or `unpivot` sides is fast at any size — don't hand-split it into
-per-table queries you merge client-side. The index exists when a bound template sorts that field
-in the same direction and blank position: give the query its default order as a top-level `sort`,
-and a page the app sorts the same way is served. A text column, a computed, literal or cast column,
-a sort on more than one key, and a cursor (`keyset`) page sort every row.
+- **Trigram-served:** `from_table.search` (§7), within the one table.
+- **Every row of the table:** everything else — text equality and `contains`, number and date
+  comparisons, sorts, negations, emptiness, files predicates. Fine on thousands of rows; the cost
+  grows with the table, and on very large tables these dominate latency and are the usual
+  timeout cause.
+
+**Filter shape drives latency.** Lead with a GIN-served membership filter or `search`, which
+narrow the table before its rows are read, and let the other conditions refine that set.
+Derived-layer filters run over the subquery result, after any `unpivot` fan-out, so **filter at
+the source layer whenever the field exists there** — the runtime filter is for caller-driven
+refinement, not for the main cut. (The engine moves eligible filter-over-union predicates into
+each arm's source automatically, but don't rely on that for other shapes.)
 
 **An aggregate arm you cannot filter costs its whole table, every execution.** A `join` whose right
 side is a `group` over entire tables, keyed on a value the LEFT side supplies at run time, has no

package/docs/runtime.md

@@ -62,15 +62,18 @@ Activation is a **two-step gate** — both must hold, so demo data shipping in t
 bundle never leaks into normal traffic:
 
 1. A fixture is registered via `mount({ fixture })` (`AppFixture` type:
-   `dist/mock.d.ts` — `{ queries?, workflows?, recordings? }`).
+   `dist/mock.d.ts` — `{ queries?, workflows?, exports?, recordings? }`).
 2. The page URL carries `?__mock=1` (exactly `1`). Without the flag the fixture
    is completely inert.
 
 When active, the [query hooks](./data_fetching.md) return `fixture.queries[alias]`
-instead of making any request (`loading` stays `false`); a read with `enabled: false` asks
+instead of making any request (`loading` stays `false`, except for a function fixture that
+returns a promise: the read stays loading until it settles, to review a pending state); a read with `enabled: false` asks
 the fixture nothing, as it asks the server nothing. **Partial mocking is
 supported**: an alias absent from the fixture still flows through the real
-transport. Calling `mount` again (HMR) replaces the registration last-write-wins.
+transport. `fixture.exports[alias]` answers `exportQuery(alias, call)` — a
+function of the call returning the file, or a promise of it to review the
+pending state. Calling `mount` again (HMR) replaces the registration last-write-wins.
 
 - **Fixture rows stand in for wire rows.** They pass through the same code path
   as fetched rows, so shape them exactly like the query's real output — the same
@@ -223,9 +226,9 @@ const { rows } = await rpc<{ rows: Record<string, unknown>[] }>("query", {
 
 `rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>` sends one op over
 whichever transport is active. **Prefer the hooks** — they add the SDK's cache,
-loading/error state, analytics, and typing from your declared aliases; every row
-of a set for a full export is `queryAll` ([data_fetching](./data_fetching.md)), fed
-to `downloadFile` (below). `rpc()` exists for the imperative cases neither
+loading/error state, analytics, and typing from your declared aliases; a file of
+every row of a set is `exportQuery`, made by the server ([data_fetching](./data_fetching.md)).
+`rpc()` exists for the imperative cases neither
 models. `T` is *your* assertion — the SDK does not validate the result shape.
 
 The full `RpcOp` union (`dist/rpc.d.ts`), each op's payload, and where its
@@ -234,6 +237,7 @@ semantics are documented:
 | Op | Payload | Resolves to | Owning doc |
 |---|---|---|---|
 | `query` | `{ alias, params?, limit?, offset?, … }` | `{ rows }` | [queries](./queries.md), [data fetching](./data_fetching.md) |
+| `export` | `{ alias, params?, filter?, sort?, report, file }` | `{ file }` | [data fetching](./data_fetching.md) |
 | `field_options` | `{ alias }` | `{ fields }` | [members & options](./members_and_options.md) |
 | `workflow` | `{ alias, inputs }` | `WorkflowResult` | [mutations](./mutations.md) |
 | `upload` | `{ file: File }` (the `File` crosses the bridge by structured clone) | uploaded-file object | [files](./files.md) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.101.2",
+  "version": "0.102.1",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {