@lotics/app-sdk 0.124.6 → 0.124.8

package/AGENTS.md

@@ -14,7 +14,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 and `total: { where }` a count per named filter, from one scan — `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`/`readLockedBy`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push** and `answeredAt` (the server answering again what a screen drew), 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 and `total: { where }` a count per named filter, from one scan — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes, `exportApp` for the file of an Export of a JSON app; 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`/`readLockedBy`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push** and `answeredAt` (the server answering again what a screen drew), 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`, `useRecordings` over several aliases. |
 | [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-BWMAO5IY.js → chunk-YONY7UPS.js}

@@ -241,6 +241,7 @@ var TABLE_ID_PATTERN = new RegExp(
   "i"
 );
 var PREFIXED_ID_PATTERN = new RegExp(`^[a-z]{3}_[${ID_ALPHABET}]{${ID_LENGTH}}$`);
+var MEMBER_ID_PATTERN = new RegExp(`^[${ID_ALPHABET}]{${ID_LENGTH},}$`);
 
 // ../shared/src/table_field_keys.ts
 var nanoid2 = customAlphabet(ID_ALPHABET, 6);

package/dist/hooks.d.ts

@@ -3,8 +3,7 @@ import { type AttachmentPiles, type AttachmentPilesOptions, type AttachmentsOpti
 import { type AiContextValue } from "./rpc.js";
 import { type AgentUIPart, type PendingChoice, type AgentRunLanding } from "./agent_stream.js";
 import type { AppWorkflows, AppWorkflowResults, AppAgents, AppAgentResults } from "./types.js";
-import type { ResolvedMember } from "./shared_types.js";
-import type { PhotoPlace } from "./row.js";
+import type { PhotoPlace, ResolvedMember } from "./shared_types.js";
 export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, AgentRunLanding } from "./agent_stream.js";
 export { buildChoiceOutput } from "./agent_stream.js";
 /**

package/dist/index.d.ts

@@ -5,10 +5,11 @@ 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, exportQuery, useFieldOptions } from "./queries.js";
+export { useQuery, useQueries, queryAll, exportQuery, exportApp, useFieldOptions } from "./queries.js";
 export type { QueryCall, QueryState, RowOf, QueryOptions, ColumnKeyOf, FieldOptions, FieldOptionsState, FieldOptionsOptions, FigureUnits, } from "./queries.js";
 export type { QueryRow, QuerySortKey, QueryFieldSortKey, QueryFirstSortKey, QueryFilter, QueryFilterCondition, QueryFilterFieldCondition, QueryFilterRecordIdCondition, QueryFilterGroup, ExportCall, ExportFile, ExportReport, ExportTab, } from "./shared_types.js";
 export type { ExportedFile } from "./shared_types.js";
+export type { ExportNarrowing } from "./shared_types.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";
@@ -28,15 +29,14 @@ export { openApp, peekApp } from "./open_app.js";
 export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { renameFile } from "./rename_file.js";
-export { readMembers, readSelect } from "./shared_types.js";
-export type { ResolvedMember, ResolvedOption } from "./shared_types.js";
-export type { AppFixture, MockExport, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
+export { readFiles, readMembers, readSelect } from "./shared_types.js";
+export type { AppFile, PhotoPlace, ResolvedMember, ResolvedOption } from "./shared_types.js";
+export type { AppFixture, MockExport, MockExportApp, MockQuery, MockQueryCall, MockWorkflow } from "./mock.js";
 export type { MockAgent, MockAgentRun } from "./mock_agent_run.js";
 export type { AppWorkflows, AppWorkflowResults, AppQueries, AppQueryColumns, AppAgents, AppAgentResults } from "./types.js";
 export { row, readLinks } from "./shared_types.js";
 export type { ResolvedLink } from "./shared_types.js";
-export { readFiles, readLocked, readLockedBy, readCreatedAt, readUpdatedAt, PENDING } from "./row.js";
-export type { AppFile, PhotoPlace } from "./row.js";
+export { readLocked, readLockedBy, readCreatedAt, readUpdatedAt, PENDING } from "./row.js";
 export { useNewRecord, newRecordId } from "./new_record.js";
 export type { NewRecordApi } from "./new_record.js";
 export { useRecents } from "./use_recents.js";

package/dist/index.js

@@ -49,7 +49,7 @@ import {
   subtractDecimal,
   sumDecimal,
   urlParam
-} from "./chunk-BWMAO5IY.js";
+} from "./chunk-YONY7UPS.js";
 
 // src/mount.tsx
 import { createRoot } from "react-dom/client";
@@ -95,6 +95,10 @@ function getMockExport(alias) {
   if (!isMockMode()) return null;
   return registeredFixture?.exports?.[alias] ?? null;
 }
+function getMockExportApp(key) {
+  if (!isMockMode()) return null;
+  return registeredFixture?.exportApps?.[key] ?? null;
+}
 function getMockRecordings() {
   if (!isMockMode()) return null;
   return registeredFixture?.recordings ?? null;
@@ -712,7 +716,7 @@ function useKey(key, fetcher, opts = {}) {
     if (slot === null) return;
     const answered2 = slot.askedAt > 0;
     slot.mounts.set(id, { focus });
-    if (!answered2 || arrival && seeded.current !== key || slot.outdated) void ask(slot, slot.outdated);
+    if (slot.outdated || slot.error === null && (!answered2 || arrival && seeded.current !== key)) void ask(slot, slot.outdated);
     return () => {
       slot.mounts.delete(id);
     };
@@ -10876,9 +10880,6 @@ function readMembers(value) {
   }
   return out;
 }
-
-// src/row.ts
-var PENDING = "__pending";
 function placeOf(value) {
   if (typeof value !== "object" || value === null) return void 0;
   const latitude = Reflect.get(value, "latitude");
@@ -10920,6 +10921,9 @@ function readFiles(v) {
   }
   return out;
 }
+
+// src/row.ts
+var PENDING = "__pending";
 function readLocked(rowValue) {
   if (!rowValue || typeof rowValue !== "object") return false;
   return row.bool(rowValue["__source_locked"]) === true;
@@ -13922,6 +13926,20 @@ function overlayAsked(alias, params, narrowing, askedAt, totalsOf, rows, back, a
   return { rows: back(overlaid.rows), pending: overlaid.pending };
 }
 
+// ../shared/src/app_screen/read_criteria.ts
+function statedSort(sort2) {
+  return sort2 === void 0 || sort2.length === 0 ? void 0 : [...sort2];
+}
+function readCriteria(read2) {
+  const sort2 = statedSort(read2.sort);
+  return {
+    params: { ...read2.params },
+    ...read2.filter === void 0 ? {} : { filter: read2.filter },
+    ...sort2 === void 0 ? {} : { sort: sort2 },
+    ...read2.aggregate === void 0 ? {} : { aggregate: read2.aggregate }
+  };
+}
+
 // src/queries.ts
 function pageOf(mocked, call) {
   const start = call.keyset === true ? Number(call.cursor ?? 0) : call.offset ?? 0;
@@ -13963,10 +13981,8 @@ async function askRows(key, alias, askedAt, call, since = askedAt) {
   if (mocked !== null) return pageOf(await mocked, call);
   const answer = await rpc("query", {
     alias,
-    params: call.params,
+    ...readCriteria(call),
     ...call.limit === void 0 ? {} : { limit: call.limit },
-    ...call.sort === void 0 ? {} : { sort: call.sort },
-    ...call.filter === void 0 ? {} : { filter: call.filter },
     ...call.keyset === true ? { keyset: true, ...call.cursor == null ? {} : { cursor: call.cursor } } : { offset: call.offset ?? 0 }
   });
   noteAnswer(key, alias, askedAt, answer.rows, since);
@@ -14000,7 +14016,7 @@ function useQuery(alias, params = {}, opts = {}) {
   const live = opts.revalidateOnChange ?? true;
   const aliases = live ? [alias] : [];
   const apart = live ? [] : ["held"];
-  const sort2 = opts.sort !== void 0 && opts.sort.length > 0 ? opts.sort : void 0;
+  const sort2 = statedSort(opts.sort);
   const filter2 = opts.filter;
   const wantsRows = opts.rows ?? true;
   const totalAsked = opts.total ?? opts.page !== void 0;
@@ -14119,9 +14135,6 @@ function useQuery(alias, params = {}, opts = {}) {
     }
   };
 }
-function sortOf(call) {
-  return call.sort === void 0 || call.sort.length === 0 ? void 0 : [...call.sort];
-}
 async function settle(read2) {
   try {
     return { answer: await read2, error: null };
@@ -14132,13 +14145,13 @@ async function settle(read2) {
 async function askGroups(key, alias, askedAt, aggregate, call) {
   const mocked = getMockRows(alias, { ...call, aggregate });
   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 });
+  const answer = await rpc("query", { alias, ...readCriteria({ ...call, aggregate }) });
   noteAnswer(key, alias, askedAt, []);
   return answer;
 }
 async function askCall(key, call, askedAt) {
   const params = call.params ?? {};
-  const sort2 = sortOf(call);
+  const sort2 = statedSort(call.sort);
   const rows = call.rows === false ? null : settle(
     call.aggregate !== void 0 ? askGroups(key, call.alias, askedAt, call.aggregate, { params, filter: call.filter, sort: sort2 }) : askRows(key, call.alias, askedAt, { params, filter: call.filter, sort: sort2 })
   );
@@ -14147,7 +14160,7 @@ async function askCall(key, call, askedAt) {
 }
 function useQueries(calls, opts = {}) {
   const enabled = opts.enabled ?? true;
-  const shape = JSON.stringify(calls.map((call) => [call.alias, call.params ?? {}, call.filter ?? null, sortOf(call) ?? null, call.aggregate ?? null, call.total ?? false, call.rows ?? true]));
+  const shape = JSON.stringify(calls.map((call) => [call.alias, call.params ?? {}, call.filter ?? null, statedSort(call.sort) ?? null, call.aggregate ?? null, call.total ?? false, call.rows ?? true]));
   const key = !enabled || calls.length === 0 ? null : JSON.stringify(["calls", shape]);
   const answers = useKey(key, (askedAt) => Promise.all(calls.map((call) => askCall(key ?? "", call, askedAt))), {
     focus: opts.revalidateOnFocus ?? true,
@@ -14158,7 +14171,7 @@ function useQueries(calls, opts = {}) {
     () => calls.map((call, at2) => {
       const answer = answers.data?.[at2];
       const rows = answer?.rows?.answer;
-      const drawn2 = rows === void 0 ? { rows: [], pending: pendingRead(call.alias) } : call.aggregate !== void 0 ? overlayGroups(call.alias, call.params ?? {}, call.filter, call.aggregate, answers.askedAt, rows.rows) : overlayRead(call.alias, call.params ?? {}, call.filter, sortOf(call), answers.askedAt, rows.rows, true);
+      const drawn2 = rows === void 0 ? { rows: [], pending: pendingRead(call.alias) } : call.aggregate !== void 0 ? overlayGroups(call.alias, call.params ?? {}, call.filter, call.aggregate, answers.askedAt, rows.rows) : overlayRead(call.alias, call.params ?? {}, call.filter, statedSort(call.sort), answers.askedAt, rows.rows, true);
       const count = answer?.count?.answer;
       const overlaid = count === void 0 ? void 0 : overlayCount(call.alias, call.params ?? {}, call.filter, answers.askedAt, count.total);
       const counted = overlaid === void 0 ? void 0 : { total: overlaid.rows, pending: overlaid.pending };
@@ -14190,25 +14203,29 @@ function useQueries(calls, opts = {}) {
 }
 var QUERY_ALL_PAGE = 1e3;
 async function queryAll(alias, params = {}, opts = {}) {
-  const sort2 = opts.sort === void 0 || opts.sort.length === 0 ? void 0 : [...opts.sort];
-  const mocked = getMockRows(alias, { params, filter: opts.filter, sort: sort2 });
+  const criteria = readCriteria({ params, filter: opts.filter, sort: opts.sort });
+  const mocked = getMockRows(alias, criteria);
   if (mocked !== null) return mocked;
   const pages = [];
   for (let offset = 0; ; ) {
-    const page = await rpc("query", { alias, params, limit: QUERY_ALL_PAGE, offset, sort: sort2, filter: opts.filter });
+    const page = await rpc("query", { alias, ...criteria, limit: QUERY_ALL_PAGE, offset });
     pages.push(page.rows);
     offset += page.rows.length;
     if (!page.truncated || page.rows.length === 0) return pages.flat();
   }
 }
 async function exportQuery(alias, call) {
-  const sort2 = call.sort === void 0 || call.sort.length === 0 ? void 0 : [...call.sort];
-  const tabs = call.tabs?.map((tab) => ({ ...tab, sort: tab.sort === void 0 || tab.sort.length === 0 ? void 0 : [...tab.sort] }));
-  const body = { alias, params: call.params ?? {}, filter: call.filter, sort: sort2, ...tabs === void 0 ? {} : { tabs }, report: call.report, file: call.file, ...call.labels === void 0 ? {} : { labels: call.labels } };
+  const tabs = call.tabs?.map((tab) => ({ ...tab, sort: statedSort(tab.sort) }));
+  const body = { alias, params: call.params ?? {}, filter: call.filter, sort: statedSort(call.sort), ...tabs === void 0 ? {} : { tabs }, report: call.report, file: call.file, ...call.labels === void 0 ? {} : { labels: call.labels } };
   const mocked = getMockExport(alias);
   if (mocked !== null) return mocked(body);
   return (await rpc("export", body)).file;
 }
+async function exportApp(key, narrowing) {
+  const mocked = getMockExportApp(key);
+  if (mocked !== null) return mocked(narrowing);
+  return (await rpc("export", { export: { key, ...narrowing } })).file;
+}
 var NO_UNITS = {};
 function useFieldOptions(alias, opts) {
   const enabled = opts?.enabled ?? true;
@@ -14648,6 +14665,7 @@ export {
   askAi,
   buildChoiceOutput,
   downloadFile,
+  exportApp,
   exportQuery,
   hostSpec,
   installRpcTransport,

package/dist/mock.d.ts

@@ -10,6 +10,7 @@ import type { QueryAggregate } from "./shared_types.js";
 import type { WorkflowResult } from "./hooks.js";
 import type { MockAgent } from "./mock_agent_run.js";
 import type { ExportedFile } from "./shared_types.js";
+import type { ExportNarrowing } from "./shared_types.js";
 import type { ExportCall, QuerySortKey } from "./shared_types.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. */
@@ -29,6 +30,8 @@ export type MockQuery = Array<Record<string, unknown>> | ((call: MockQueryCall)
 export type MockExport = (call: ExportCall & {
     alias: string;
 }) => ExportedFile | Promise<ExportedFile>;
+/** The file an Export of the app makes of its narrowing, as a function of the call — return a slow promise to review the pending state. */
+export type MockExportApp = (narrowing: ExportNarrowing) => ExportedFile | Promise<ExportedFile>;
 export interface AppFixture {
     queries?: Record<string, MockQuery>;
     workflows?: Record<string, MockWorkflow>;
@@ -36,6 +39,8 @@ export interface AppFixture {
     agents?: Record<string, MockAgent>;
     /** By the query exported. */
     exports?: Record<string, MockExport>;
+    /** By the key of the Export made. */
+    exportApps?: Record<string, MockExportApp>;
     /** `useRecording(alias)` reads as available; `start`/`stop` change nothing. */
     recordings?: Record<string, RecordingState>;
 }
@@ -50,4 +55,6 @@ export declare function getMockWorkflow(alias: string): MockWorkflow | null;
 export declare function getMockAgent(alias: string): MockAgent | null;
 /** Null for an unmocked alias, which the server exports. */
 export declare function getMockExport(alias: string): MockExport | null;
+/** Null for an unmocked key, which the server exports. */
+export declare function getMockExportApp(key: string): MockExportApp | null;
 export declare function getMockRecordings(): Record<string, RecordingState> | null;

package/dist/queries.d.ts

@@ -2,6 +2,7 @@ import type { QueryAggregate } from "./shared_types.js";
 import type { AppQueries, AppQueryColumns } from "./types.js";
 import type { ResolvedOption } from "./shared_types.js";
 import type { ExportedFile } from "./shared_types.js";
+import type { ExportNarrowing } from "./shared_types.js";
 import type { ExportCall, QueryFilter, QueryRow, QuerySortKey } from "./shared_types.js";
 /**
  * The row type of alias `K`: its projected columns plus the two addressing
@@ -152,6 +153,13 @@ export declare function queryAll(alias: string, params?: Record<string, unknown>
  * Resolves a link to download the file, signed for at most an hour.
  */
 export declare function exportQuery(alias: string, call: ExportCall): Promise<ExportedFile>;
+/**
+ * The file the server makes of one Export of the app — named by its `key` — over the register as `narrowing` states it
+ * (the tab, status, chips, search, period, window, order, grouping and folder; `per` the value a report of one is made
+ * for). The server reads the rows, the band's readings and the names, under the caller's own access. Resolves a link to
+ * download the file, signed for at most an hour.
+ */
+export declare function exportApp(key: string, narrowing: ExportNarrowing): Promise<ExportedFile>;
 /** One select column's full option set. */
 export interface FieldOptions {
     /** The source field's display name. */

package/dist/rename_file.d.ts

@@ -1,4 +1,4 @@
-import type { AppFile } from "./row.js";
+import type { AppFile } from "./shared_types.js";
 /**
  * A file under another name: a NEW file over the same bytes, its extension kept exactly (`"scan.pdf"` →
  * `"Invoice 9.pdf"`, never `.html`). Nothing holds it until a save puts it in the old one's place — a files field's

package/dist/router.js

@@ -2,7 +2,7 @@ import {
   isEmbedded,
   postHostNotification,
   setUrlParams
-} from "./chunk-BWMAO5IY.js";
+} from "./chunk-YONY7UPS.js";
 
 // src/router.tsx
 import { useEffect } from "react";

package/dist/row.d.ts

@@ -5,34 +5,6 @@
  */
 /** The column a predicted row carries, so no surface opens a row the server has not answered for. */
 export declare const PENDING = "__pending";
-/** A files cell entry; `url`/`thumbnail_url` are presigned (24h) and load from the sandboxed frame. */
-export interface AppFile {
-    id: string;
-    filename: string;
-    mime_type: string;
-    url: string;
-    thumbnail_url?: string;
-    /** Bytes; absent on older files — sort by the raw number, format at display. */
-    size?: number | null;
-    /** ISO upload timestamp. */
-    created_at?: string;
-    /** The document template the file was generated from (`dtl_…`); absent on a file a person brought. */
-    document_template_id?: string;
-    /** Where the device that took the photo stood as it took it, as it reported; absent on a file uploaded with none, and
-     *  on every read of an app not declaring `capabilities.photo_places` or by a caller outside its organization. */
-    place?: PhotoPlace;
-}
-/** Where a device stood: degrees north and east, and how many metres off it said it may be. */
-export interface PhotoPlace {
-    latitude: number;
-    longitude: number;
-    accuracy: number;
-}
-/**
- * The presigned files, skipping any without a `url`. A lookup arrives one
- * level deeper, flattened as in {@link readLinks}.
- */
-export declare function readFiles(v: unknown): AppFile[];
 /**
  * Whether the row's record is locked (`__source_locked`): its table refuses
  * every write to it until a manager unlocks it, and an app reads it

package/dist/rpc.d.ts

@@ -1,5 +1,5 @@
 import type { AppAbsence } from "./shared_types.js";
-import type { AppFile } from "./shared_types.js";
+import type { SpecFile } from "./shared_types.js";
 import type { AskUserChoiceOutput } from "./agent_stream.js";
 import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
 /**
@@ -104,7 +104,7 @@ export type RpcTransport = (op: RpcOp, payload: unknown) => Promise<unknown>;
  *  last install wins, and a page installs its own before it mounts. */
 export declare function installRpcTransport(transport: RpcTransport): void;
 /** What the host answers `spec`: the app's compiled spec itself, never the route's wrapper around it. */
-export type HostSpec = AppFile;
+export type HostSpec = SpecFile;
 /** The app's spec, as the host hands it over the bridge. */
 export declare function hostSpec(): Promise<HostSpec>;
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;