@lotics/app-sdk 0.97.0 → 0.98.1

package/AGENTS.md

@@ -19,7 +19,7 @@ signature; open the file.**
 | [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). |
 | [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 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), 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/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. |

package/dist/src/row.d.ts

@@ -116,6 +116,15 @@ export interface AppFile {
  * an unservable file. Pass one to `toDisplayFile` from `@lotics/ui/file_thumbnail`
  * for FileThumbnail/Gallery — the kit owns that conversion, so don't re-declare
  * it per app.
+ *
+ * A LOOKUP OF A FILES FIELD ARRIVES ONE LEVEL DEEPER, exactly as a lookup of a
+ * link field does (see {@link readLinks}) — the cell holds one entry per linked
+ * record and each entry is THAT record's whole files cell, an array — so read
+ * entry-by-entry it decoded to nothing while the pictures were plainly there,
+ * and every mark drawn off a looked-up photograph fell back to its glyph. The
+ * nesting is flattened here, at the boundary that owns the serialization, rather
+ * than at each caller: one level, in the order the rows link, and a file two
+ * linked rows both carry is one file, so ids repeat at most once.
  */
 export declare function readFiles(v: unknown): AppFile[];
 /**

package/dist/src/row.js

@@ -162,32 +162,46 @@ export function readLinks(v) {
  * an unservable file. Pass one to `toDisplayFile` from `@lotics/ui/file_thumbnail`
  * for FileThumbnail/Gallery — the kit owns that conversion, so don't re-declare
  * it per app.
+ *
+ * A LOOKUP OF A FILES FIELD ARRIVES ONE LEVEL DEEPER, exactly as a lookup of a
+ * link field does (see {@link readLinks}) — the cell holds one entry per linked
+ * record and each entry is THAT record's whole files cell, an array — so read
+ * entry-by-entry it decoded to nothing while the pictures were plainly there,
+ * and every mark drawn off a looked-up photograph fell back to its glyph. The
+ * nesting is flattened here, at the boundary that owns the serialization, rather
+ * than at each caller: one level, in the order the rows link, and a file two
+ * linked rows both carry is one file, so ids repeat at most once.
  */
 export function readFiles(v) {
     if (!Array.isArray(v))
         return [];
     const out = [];
-    for (const f of v) {
-        if (!f || typeof f !== "object")
-            continue;
-        const id = f.id;
-        const url = f.url;
-        if (typeof id !== "string" || !id || typeof url !== "string" || !url)
-            continue;
-        const filename = f.filename;
-        const mime = f.mime_type;
-        const thumb = f.thumbnail_url;
-        const size = f.size;
-        const created_at = f.created_at;
-        out.push({
-            id,
-            filename: typeof filename === "string" ? filename : "",
-            mime_type: typeof mime === "string" ? mime : "",
-            url,
-            thumbnail_url: typeof thumb === "string" ? thumb : undefined,
-            size: typeof size === "number" ? size : undefined,
-            created_at: typeof created_at === "string" ? created_at : undefined,
-        });
+    const seen = new Set();
+    for (const entry of v) {
+        const held = Array.isArray(entry) ? entry : [entry];
+        for (const f of held) {
+            if (!f || typeof f !== "object")
+                continue;
+            const id = f.id;
+            const url = f.url;
+            if (typeof id !== "string" || !id || typeof url !== "string" || !url || seen.has(id))
+                continue;
+            seen.add(id);
+            const filename = f.filename;
+            const mime = f.mime_type;
+            const thumb = f.thumbnail_url;
+            const size = f.size;
+            const created_at = f.created_at;
+            out.push({
+                id,
+                filename: typeof filename === "string" ? filename : "",
+                mime_type: typeof mime === "string" ? mime : "",
+                url,
+                thumbnail_url: typeof thumb === "string" ? thumb : undefined,
+                size: typeof size === "number" ? size : undefined,
+                created_at: typeof created_at === "string" ? created_at : undefined,
+            });
+        }
     }
     return out;
 }

package/docs/data_fetching.md

@@ -442,7 +442,7 @@ the server's answer is the only check — the rule the filter keys follow too.
 | `readLinks(cell)` | link cell → `{ id, display }[]` | ALL linked records (`[]` when empty), a LOOKUP of a link field included |
 | `readSelect(cell)` | select cell → `ResolvedOption[]` | all selected options as `{ key, label }` (`[]` when empty) |
 | `readMembers(cell)` | member cell → `ResolvedMember[]` | `{ id, name, email?, image?, groups? }[]` (`[]` when empty) |
-| `readFiles(cell)` | files cell → `AppFile[]` | attached files with presigned URLs (`[]` when empty) |
+| `readFiles(cell)` | files cell → `AppFile[]` | attached files with presigned URLs (`[]` when empty), a LOOKUP of a files field included |
 | `readLocked(rowObj)` | the whole **row** → `boolean` | the record's lock state from `__source_locked` |
 | `readCreatedAt(rowObj)` | the whole **row** → `Date \| null` | when the record was created, from `__created_at` |
 | `readUpdatedAt(rowObj)` | the whole **row** → `Date \| null` | when the record was last updated, from `__updated_at` |
@@ -498,8 +498,11 @@ anonymous public-app visitors; re-querying refreshes the TTL naturally. Entries
 presign (no `url`) are skipped, so you never render an unservable file. `size` (bytes) and
 `created_at` (ISO upload timestamp) are resolved at serving time; `size` is absent for older files
 not yet backfilled — render it only when present, and surface both as dedicated sortable columns
-over the raw values (a formatted "8.4 MB" string sorts wrong). Previewing and uploading files:
-[./files.md](./files.md).
+over the raw values (a formatted "8.4 MB" string sorts wrong). **A LOOKUP of a files field arrives
+one level deeper**, exactly as a looked-up link does — one entry per linked record, each entry that
+record's whole files cell — and `readFiles` opens it, in link order and with a file two linked rows
+both carry named once, so a looked-up picture needs no unwrapping of its own. Previewing and
+uploading files: [./files.md](./files.md).
 
 **Warning — the presign ceiling:** signing file URLs is per-entry server work, so a response is
 capped at **2,000 file entries** (server default). A query over the cap **fails** with an error

package/docs/files.md

@@ -241,6 +241,13 @@ Decode with `readFiles(cell)` → `AppFile[]` (`dist/src/row.d.ts`):
 `readFiles` skips entries the server didn't presign (no `url`), so you never render an unservable
 file. It is pure and never throws.
 
+- **A LOOKUP of a files field is one list per linked row.** The cell holds one entry per linked
+  record and each entry is that record's whole files cell, so the value arrives one level deeper
+  than a stored column's — exactly as a looked-up link does. `readFiles` opens that level itself,
+  in link order, naming a file two linked rows both carry once, so a picture read through a link
+  needs no unwrapping at the call site. Read entry-by-entry it decodes to nothing, which is a mark
+  falling back to its glyph while the bytes are plainly there.
+
 - **Thumbnails are optimistic.** `thumbnail_url` is emitted for every image without checking that
   the variant exists; a not-yet-generated variant 404s on fetch. `@lotics/ui`'s `FileThumbnail`
   falls back to `url` on image error — a hand-rolled `<img src={thumbnail_url}>` must do the same.

package/docs/members_and_options.md

@@ -265,7 +265,7 @@ client-side up front, and re-checked server-side.
 - **The author is always the real signed-in member** — correct attribution, enforced server-side.
   **Warning:** under "View as", comments still author as the real member (the admin), not the
   view-as target — unlike `useViewer` and `is_current_member` scoping, which follow the target.
-- **Edit and delete are author-only**, checked server-side against the viewer. `CommentThread`'s
+- **Edit and delete are author-only**, checked server-side against the viewer. `EntryList`'s
   `currentMemberId` prop drives the matching affordance client-side.
 
 ### Reading & writing
@@ -286,13 +286,13 @@ renders the panel. State: `{ comments, loading, error, available, createComment,
 updateComment, deleteComment, refetch }`.
 
 - `comments` — newest first on the wire (server order). Pass the array as-is to `@lotics/ui`'s
-  `CommentThread`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
+  `EntryList`, which re-sorts oldest-first for display. Each `AppComment`: `{ id, record_id,
   table_id, member_id, author, content, files, workspace_id, created_at, updated_at }`. Attachments
   (`AppCommentFile`) carry `id` / `filename` / `mime_type` — a file's identity is its `id`, and
   the server re-reads every attachment from storage by that id, so nothing else you hold about a
   file can affect what is stored. The `url` / `thumbnail_url` / `preview_url` fields exist on the type
   but the server does not populate them today — render attachments by name and type (what
-  `CommentThread`'s default file row does), never by counting on a fetchable URL.
+  `EntryList`'s default file row does), never by counting on a fetchable URL.
 - `createComment({ content, file_ids? })` — posts as the viewing member. `file_ids` come from
   `useFileUpload` / `useAttachments` (see [files](./files.md)). A comment must have content or at
   least one file (empty input is a client no-op; the server enforces the same rule). Content max
@@ -308,7 +308,7 @@ updateComment, deleteComment, refetch }`.
   app by someone the record references nowhere. So a thread that crosses a role boundary is legible without the app declaring member
   access it does not otherwise need, and a per-viewer app never widens its reach for a display
   string. `name` is `null` when the id no longer resolves in the org (a removed member) — render a
-  fallback (`CommentThread` has an `unknownMember` label for exactly this). The one comment with no
+  fallback (`EntryList` has an `unknownMember` label for exactly this). The one comment with no
   `author` is the optimistic row `createComment` renders locally: the SDK knows the viewer's id and
   not their name, and it will not invent one. The server's row replaces it when the refetch lands.
 - **Freshness:** SWR-cached, revalidates on focus/reconnect, so another viewer's comment appears on
@@ -336,7 +336,7 @@ directly (full props: `node_modules/@lotics/ui/AGENTS.md` and its `docs/`):
 | A select value (stored or picker option) | `Status` | A `useFieldOptions` option, or `byKey(readSelect(cell)[0]?.key)`; accepts a single option, an array (multi → one badge each), or null (renders nothing). Missing/unknown color → neutral. |
 | A person, inline | `MemberChip` | `name` / `image` from a roster or a cell — both carry it; no image → initials |
 | A member picker | `MemberSelect` | `members={useMembers().members}` — renders each option as a `MemberChip`; `MEMBER_UNASSIGNED` marks its optional "unassigned" option |
-| A comment thread | `CommentThread` + `CommentComposer` | `useComments` state; `resolveMember` reads each comment's own `author` (`{ name, image }`) — no roster needed |
+| A comment thread | `EntryList` + `CommentComposer` | `useComments` state; `resolveMember` reads each comment's own `author` (`{ name, image }`) — no roster needed |
 
 The SDK never imports `@lotics/ui` — the app owns the (thin) data→UI adapter in each row above.
 

package/package.json

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