@lotics/app-sdk 0.72.0 → 0.73.0

package/docs/queries.md

@@ -121,7 +121,8 @@ Delivery-layer enrichment (applied to the response, per request):
 
 - **`files` cells** — each entry gains a presigned `url` + `thumbnail_url` (24 h TTL) and
   `size` (bytes) + `created_at`, resolved from the file object at read. Presigning is
-  server-bounded (§10). Public apps hand out direct presigned URLs — anonymous-fetchable,
+  server-bounded (§10) — and it is per ENTRY, which is why a list that renders one thumbnail
+  should project the column with `limit` (§3) rather than the whole array. Public apps hand out direct presigned URLs — anonymous-fetchable,
   time-boxed. (App workflow-execute responses presign returned files the same way, so their
   URLs also work for anonymous public-app viewers — see [files.md](./files.md).)
 - **`select_member` cells** — bare member-id arrays become
@@ -199,6 +200,20 @@ indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank
   (§4), never a relabel. An uncastable combination is rejected at deploy.
 - **Project only what you render.** A bare `from_table` ships every column — including `files`
   cells with storage keys — to the client (over-exposure + the presign ceiling at scale).
+- **A files column takes `limit` — bound it when the surface renders a THUMBNAIL, not the
+  collection.** `{ "type": "files", "output": "photo", "source": "fld_…", "limit": 1 }` returns
+  the first entry per cell, in stored order, cut in SQL so the rest is never read or signed.
+  Without it the cell yields the whole array and the response pays to resolve every entry it
+  will never show: a register over containers averaging 33 gate photos each resolved ~832 files
+  to display 25 thumbnails, within 2.4× of the response-wide presign ceiling (§10) that would
+  reject the query outright. The bound is per CELL and caps at `FILES_PROJECTION_MAX_LIMIT`
+  (10) — a row wanting more than a handful is asking for the collection, which belongs to the
+  record surface that opens it. It is a different axis from the query's own `limit`, which
+  counts ROWS; `limit` on any non-`files` column — or on a computed source, which has no cell
+  to bound — is rejected at deploy rather than ignored. **On a UNION, set it on every arm.**
+  Arms align by column name and type, and `limit` is neither, so an arm that omits it still
+  yields whole cells — the query stays correct and silently costs what the bound was there to
+  avoid.
 
 ### `filter` — predicate over derived columns
 

package/package.json

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