@lotics/app-sdk 0.100.1 → 0.101.0

package/AGENTS.md

@@ -1,30 +1,31 @@
-# @lotics/app-sdk — the SDK reference index
+# @lotics/app-sdk — the custom-app reference index
 
-The **data + RPC** runtime for Lotics custom-code apps: typed React hooks over an origin-locked
-postMessage bridge, cell decoders, and the `mount()` entry point. **Data + RPC only — no UI.**
-Render with **`@lotics/ui`** (read `node_modules/@lotics/ui/AGENTS.md`); the two pair — the SDK
-fetches/mutates, `@lotics/ui` draws.
+**A custom-code Lotics app reads and writes through this package.** `@lotics/app-sdk` is the typed
+hooks over the host bridge, the cell readers and `mount()`; `@lotics/app-sdk/router` is
+`AppRouter`. Data and RPC only — no component. What the app draws is its own.
 
-This file is the index. The comprehensive contract references live in **`docs/`** — read the
-owning area doc before building; it is the contract for a backend you cannot see. The **exact
-signature** of any hook or reader is its shipped source: `dist/src/<name>.d.ts` — **never guess a
-signature; open the file.**
+**`@lotics/ui` and its engines are not on npm.** The component kit is installed only inside a
+sandbox session's working tree; an app scaffolded on your machine draws with its own components.
+Where a doc pairs an SDK value with a kit component, that pairing applies in a sandbox session.
+
+This file is the index. The **exact type** of anything is its shipped declaration,
+`dist/<name>.d.ts` for a hook or reader — **never guess a shape; open the file.**
 
 ## The area references
 
 | Doc | Read it for |
 |---|---|
-| [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
-| [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
-| [docs/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate at 10,000 — `useQuery` says so with `truncated`), the ROW type (`RowOf` — the alias's projected columns and nothing else, values `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys AND the `useFieldOptions` map keyed against that same projection (`AppQueryColumns`, `ColumnKeyOf`), cell readers (`row.*` — `row.num` and `row.bool` answer `null` for an EMPTY cell, so none is distinguishable from zero and an unanswered checkbox from a "no" — `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, and `readCreatedAt`/`readUpdatedAt` for the record timestamps every row-level result carries), caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
-| [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract (`field_errors` locates a refusal on the control it belongs to, where `message` can only say it at the dialog's scope), typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write), `useRecording` (the HOST records the member — mic, system sound, screen — and files the transcribed recording through a receiving workflow exactly once; `available` gates the control, `state` follows the recording). |
-| [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + explicit `linked()` descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the `recording` input a workflow declares to receive a recording, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
-| [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments` (**the add-queue, and which lifecycle it keeps**: a composer clears, a record passes `landed` and each entry leaves as the stored pile takes it over), `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted; and a LOOKUP of a files field is one list per linked row, which the reader opens itself), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
-| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions` (keyed by the alias's OWN columns, every key optional), `useViewer`, `useComments` (each comment carries its own resolved `author`, so a thread crossing a role boundary is legible without declaring member access), and the `@lotics/ui` components they feed. |
-| [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
-| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics; a chat mutation refetches your queries through the realtime channel, not a separate poke). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
-| [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
-| [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, **the API address a standalone bundle reads out of its own page** (`<meta name="lotics-api-base">`, declared by whatever serves the app — no address is compiled into the SDK, so one bundle runs on any instance and a page without it refuses rather than guessing), `rpc()`, the design-time mock harness (`fixture` + `?__mock=1` — queries AND workflows, so an AI screen's in-flight/done/error states are reviewable without running or paying for anything; a fixture is rows or a FUNCTION of the call, and only the function form reproduces a per-call `filter`), `openExternal`/`openApp`/`downloadFile`, geofencing, and the publish chain for SDK contributors. |
+| [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/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. |
+| [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
+| [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload` and its `fidelity`, `renameFile` (a new file over the same bytes), `useAttachments`/`useAttachmentPiles`, `readFiles` and presigned URLs (a bearer credential — never logged or persisted), workflow-generated files, naming a zip's entries, the delivery bounds. |
+| [docs/members_and_options.md](./docs/members_and_options.md) | People, select options and comments — `useMembers`, `useFieldOptions`, `useViewer`, `useWorkspaceTimezone`/`useWorkspaceCurrency`, `useAppContext`, the workspace's zone at the root, `useComments`. |
+| [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`, `useFolderPick`. |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming parts, the agent's ask-back), `askAi`, `useAiContext`, and what the member's own chat agent can do with the app while it is open. |
+| [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, why a per-input bound is a tenancy floor rather than an authorization check. |
+| [docs/runtime.md](./docs/runtime.md) | `mount()` and the errors it reports to the host (`reportAppError`), the two transports, the API address a standalone bundle reads out of its own page (`<meta name="lotics-api-base">`), `rpc()`, the mock harness (`fixture` + `?__mock=1`), `openExternal`/`openApp`/`downloadFile`, geofencing, the peer dependencies. |
 
 ## Non-negotiables (each detailed in its doc)
 
@@ -34,33 +35,17 @@ signature; open the file.**
   A client-supplied member id is an IDOR. → [security](./docs/security.md)
 - **Server data is never copied into `useState`** — hooks are the source of truth; derive with
   `useMemo`. → [data_fetching](./docs/data_fetching.md)
-- **A successful write re-reads the screen for you** — do not chase a `useWorkflow` call with
-  `refetch()`. Reach for it only where a write cannot have told you: a poll, a value nothing on
-  this screen wrote, a total you supplied. → [mutations](./docs/mutations.md)
-- **Update writes are diffs** — send only changed fields, and *cleared* is a change: an optional
-  input clears with `null` (never `""`), which `set_skip_null` drops and `set` performs.
-  → [mutations](./docs/mutations.md)
-- **`project` only what you render; filter server-side.** A bare `from_table` over-ships every
-  column, including files. → [queries](./docs/queries.md)
-- **Never hand-roll the serialization contract** — decode cells with the typed readers.
-  → [data_fetching](./docs/data_fetching.md)
-- **Read only the columns the alias projects** — its option sets too, from the alias that CARRIES
-  the column. Anything else is `undefined`, which every reader draws as a blank cell, so the row
-  type and the option map are bounded to the projection. → [data_fetching](./docs/data_fetching.md)
-- **Narrow `__source_record_id` / `__source_table_id` before use** — a grouped query emits neither,
-  so an unchecked read hands a workflow (or an AI record ref) `undefined`.
+- **A write shows from the press, and the SDK does it, not the screen.** `useWorkflow` draws what
+  the workflow's own steps will write on every read before the server answers, takes it back on a
+  refusal, and re-reads the queries over the tables its body names on a success — so no screen
+  patches rows or calls `refetch()` after a write. → [mutations](./docs/mutations.md)
+- **Update writes are diffs** — send only changed fields; an optional input clears with `null`
+  (never `""`). → [mutations](./docs/mutations.md)
+- **`project` only what you render; filter server-side.** → [queries](./docs/queries.md)
+- **Never hand-roll the serialization contract** — decode cells with the typed readers, and read
+  only the columns the alias projects. → [data_fetching](./docs/data_fetching.md)
+- **Narrow `__source_record_id` / `__source_table_id` before use** — a grouped query emits neither.
   → [data_fetching](./docs/data_fetching.md)
 - **A standalone app takes its API address from the page it was served in**, never from a
-  constant — the serving host declares `<meta name="lotics-api-base">`, and a bundle that finds
-  none refuses instead of addressing someone else's instance. Nothing for an app to configure;
-  build against 0.90.2 or later. → [runtime](./docs/runtime.md)
+  constant. → [runtime](./docs/runtime.md)
 - **Errors fail loud** — no swallowed catches, no silent fallbacks.
-
-## Keeping this reference current
-
-These docs are the published contract — agents build apps from `node_modules` and cannot read the
-platform source, so a wrong or missing claim here becomes their bug. **Codify every new hook,
-reader, pattern, or contract change into its OWNING area doc + the index line above in the same
-change that adds it, and bump the package version** (publish CI fires on a version diff; `files`
-ships only on publish). Each fact lives in exactly one doc — link, never duplicate. The
-platform-internal model/IAM rationale stays in the repo's `docs/apps.md`.

package/dist/agent_stream.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Folds the AI-SDK UI-message SSE stream into the `UIMessagePart[]` shape
+ * `@lotics/ui` `AgentRun` renders. `ai` is imported for types only, so no `ai`
+ * runtime enters the app bundle; unknown chunk types are ignored. A structured
+ * agent's `submit_result` input becomes `output`, never a part.
+ */
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+/** An ai-sdk message part — the render model, tool-set-agnostic. */
+export type AgentUIPart = UIMessagePart<UIDataTypes, UITools>;
+/** Mirrors the server's `INTERACTIVE_APP_TOOLS`; a call parks the run as `awaiting_input`. */
+export declare const INTERACTIVE_TOOLS: ReadonlySet<string>;
+export interface AgentRunState {
+    status: "streaming" | "awaiting_input" | "completed" | "error";
+    parts: AgentUIPart[];
+    /** `submit_result`'s input, never the free text — a consumer reading `output.<field>` would crash on a string. */
+    output?: unknown;
+    error?: string;
+}
+export interface SettledAgentRun {
+    status: string;
+    output?: unknown;
+    error_message?: string | null;
+    /** On an `awaiting_input` row: rebuilds the ask for a client that lost the stream. */
+    pending_interactive?: {
+        tool_call_id: string;
+        tool_name: string;
+        input: unknown;
+    } | null;
+}
+/**
+ * Fold a polled row into the stream's state, for a dropped or truncated stream.
+ * The row owns status and structured output; a free-text row's string output
+ * never enters `state.output`.
+ */
+export declare function adoptSettledRun(state: AgentRunState, settled: SettledAgentRun): AgentRunState;
+export type ChoiceOption = {
+    label: string;
+    description: string;
+};
+export type ChoiceQuestion = {
+    question: string;
+    options: ChoiceOption[];
+    allow_custom?: boolean;
+};
+export type AskUserChoiceAnswer = {
+    type: "option";
+    question_index: number;
+    question_number: number;
+    question_text: string;
+    option_index: number;
+    option_letter: string;
+    option_label: string;
+    option_description: string;
+} | {
+    type: "custom";
+    question_index: number;
+    question_number: number;
+    question_text: string;
+    text: string;
+} | {
+    type: "skipped";
+    question_index: number;
+    question_number: number;
+    question_text: string;
+};
+export type AskUserChoiceOutput = {
+    answers: AskUserChoiceAnswer[];
+    skipped_by_user?: boolean;
+};
+export interface PendingChoice {
+    toolCallId: string;
+    questions: ChoiceQuestion[];
+}
+/** The pending `ask_user_choice`, non-null exactly while parked. */
+export declare function pendingInteractiveCall(state: AgentRunState): PendingChoice | null;
+/** `answers` align to `questions` by index (`ClarifyWizard`'s contract); a missing or empty one is skipped. */
+export declare function buildChoiceOutput(questions: ChoiceQuestion[], answers: {
+    value: string;
+    custom: boolean;
+}[]): AskUserChoiceOutput;
+/** Settle the answered part and resume `streaming` for the continuation. */
+export declare function applyInteractiveAnswer(state: AgentRunState, toolCallId: string, output: AskUserChoiceOutput): AgentRunState;
+export declare function initialAgentRunState(): AgentRunState;
+interface Chunk {
+    type?: string;
+    delta?: string;
+    /** `tool-input-delta` argument text, not prose. */
+    inputTextDelta?: string;
+    toolName?: string;
+    toolCallId?: string;
+    input?: unknown;
+    output?: unknown;
+    errorText?: string;
+    finishReason?: string;
+}
+export declare function reduceAgentChunk(state: AgentRunState, chunk: Chunk): AgentRunState;
+/** Complete chunks so far and the partial frame to carry forward; `[DONE]` is dropped. */
+export declare function parseSseChunks(buffer: string): {
+    chunks: Chunk[];
+    rest: string;
+};
+/**
+ * How one run leg ended, discriminated so a caller never races the hook's
+ * uncommitted state. A run failure is data (`failed`); only API misuse and a
+ * refused answer (the run stays parked) reject.
+ */
+export type AgentRunLanding<TOutput> = 
+/** `output` is absent for a free-text agent, whose result is `text`. */
+{
+    kind: "settled";
+    output?: TOutput;
+    text: string;
+}
+/** `pendingChoice` carries the question. */
+ | {
+    kind: "parked";
+}
+/** The error is user-facing. */
+ | {
+    kind: "failed";
+    error: string;
+}
+/** The client stopped listening; the run continues server-side — never a failure. */
+ | {
+    kind: "aborted";
+};
+export declare const ABORTED: AgentRunLanding<never>;
+/** A free-text agent's result. */
+export declare function proseOf(parts: readonly AgentUIPart[]): string;
+export declare function landingOf(state: AgentRunState): AgentRunLanding<unknown>;
+export {};

package/dist/ask_ai.d.ts

@@ -0,0 +1,27 @@
+export interface AskAiArgs {
+    /** Prefilled only; nothing runs until the user sends. */
+    prompt?: string;
+    /** From `readFiles(cell)`; previewed beside the chat. */
+    file_ids?: string[];
+    /** The agent acts on them under the signed-in user's authority. */
+    record_ids?: string[];
+    /** Free-text grounding; the host adds the app's identity. */
+    context?: string;
+}
+/**
+ * Open a fresh chat seeded with files, records and a prompt the user sends
+ * themselves. For judgment that commits back into the app, use `useAgentRun`
+ * — `askAi`'s outcome lands in chat.
+ *
+ * ```tsx
+ * import { askAi } from "@lotics/app-sdk";
+ * await askAi({
+ *   file_ids: [file.id],
+ *   record_ids: [row.id],
+ *   prompt: "Update the header of this invoice to match our letterhead.",
+ * });
+ * ```
+ *
+ * Rejects standalone.
+ */
+export declare function askAi(args: AskAiArgs): Promise<void>;

package/dist/attachments.d.ts

@@ -0,0 +1,58 @@
+import type { ImageFidelity } from "./upload/optimize.js";
+export interface AttachedFile {
+    /** Local; the React key and `remove(id)` handle. */
+    id: string;
+    filename: string;
+    mime_type: string;
+    /** A local object URL, available before upload. */
+    preview_url: string;
+    status: "uploading" | "ready" | "error";
+    /** Set once `ready`. */
+    file_id?: string;
+}
+export interface AttachmentsOptions {
+    /**
+     * The stored ids the destination now holds; matching entries leave the queue
+     * with no gap on screen. Omitted, the queue accumulates until `clear`.
+     */
+    landed?: readonly string[];
+}
+export interface AttachmentsState {
+    /** Shared by every untouched pile, so never written through. */
+    files: readonly AttachedFile[];
+    /** Previews at once, uploads in the background; picking is the app's (`pickFiles`, paste, drop). */
+    add: (files: File[], options?: {
+        fidelity?: ImageFidelity;
+    }) => void;
+    /**
+     * `add`, resolving with every stored id in order — what a write waits on.
+     * Rejects with the first refusal; each entry keeps its own status.
+     */
+    attach: (files: File[], options?: {
+        fidelity?: ImageFidelity;
+    }) => Promise<string[]>;
+    remove: (id: string) => void;
+    clear: () => void;
+    /** Gate Send on it. */
+    uploading: boolean;
+    fileIds: string[];
+}
+export interface AttachmentPilesOptions {
+    /** {@link AttachmentsOptions.landed} by pile; a pile it omits accumulates until cleared. */
+    landed?: Readonly<Record<string, readonly string[]>>;
+}
+export interface AttachmentPiles {
+    /** The pile's queue, empty until something is added to it; its verbs are stable per pile. */
+    of: (pile: string) => AttachmentsState;
+    /** Every pile's queue at once. */
+    clearAll: () => void;
+}
+type Upload = (file: File, options?: {
+    fidelity?: ImageFidelity;
+}) => Promise<{
+    id: string;
+}>;
+/** One queue per pile in one hook, so a caller holding a list of piles never calls a hook in a loop. */
+export declare function useAttachmentPileQueues(upload: Upload, options?: AttachmentPilesOptions): AttachmentPiles;
+export declare function useAttachmentQueue(upload: Upload, options?: AttachmentsOptions): AttachmentsState;
+export {};