@colixsystems/widget-sdk 0.281.0 → 0.284.0

package/README.md

@@ -51,6 +51,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, total, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching`; `total` is the envelope's `meta.total` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*`. `options` is `{ filter, filterMode, q, sort, limit, offset, includeCapabilities, live }`, applied on the server: see *Querying records*. `live: true` re-reads when anyone else changes the table: see *Live lists*. |
+| **DATASTORE** | `usePagedDatastoreQuery(table, { pageSize, ...query })` | `{ data, total, hasMore, loadingMore, error, loadMore, retry, … }` | A growing list, a page at a time: see *Querying records*. |
 | **DATASTORE** | `useDatastoreFigure(table, { aggregate, column, filter })` (optional: options) | `{ value, text, truncated, loading, fetching, error, refetch }` | `records(table).list` (a count reads the envelope total; a sum or average up to 1000 rows) — `datastore.read:*`. One count / sum / average for a `<Stat>`, computed exactly as the built-in Stat widget does. |
 | **DATASTORE** | `useDatastoreRecord(table, id, options)` (optional: options) | `{ data, loading, fetching, error, refetch }` — a refetch of the same record keeps `data` while `fetching`; `{ includeCapabilities: true }` adds `data._capabilities` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -88,7 +89,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.281.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.284.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.284.0 (contract 1.233.0)
+
+**A conversation can go when its last member leaves.** A `datastoreTemplate` table may declare `deleteWhenLastMemberLeaves: true`. Use it on a table whose rows people join and leave through per-record grants, such as conversations. When a signed-in member gives up their own grant and that leaves the row with none, and no table-wide grant lets anyone read the row, the row is deleted for good, together with every row a `CASCADE` relation ties to it (its messages, reactions and read states, including ones deleted earlier). A row that never had a grant, such as a seeded sample row, is never deleted this way, and a revoke made in the Studio never deletes anything. Each deletion is recorded in the table's history. An upgrade that declares it turns it on for the table already installed. The platform is rolling this out gradually, so a left row may stay in place for now.
+
+### What's new in 0.283.0 (contract 1.232.0)
+
+**`usePagedDatastoreQuery(tableId, { pageSize, sort, filter, … })` — a list of records a page at a time.** A custom list read `useDatastoreQuery` with no `limit`, so it showed one server page and nothing said the rest existed. The new hook reads the first `pageSize` rows (default 25, 1-500), and `loadMore()` appends the next page by offset, so a tap reads one page instead of the whole list again. It returns `{ data, total, hasMore, loading, fetching, loadingMore, error, loadMore, retry, refetch }`: show a Load more `<Button busy={loadingMore}>` while `hasMore`. A failed page sets `error` and keeps the rows shown, and `retry()` fetches it again. A changed sort, filter, search or page size starts from the first page. A write, `live`, `refetch()` or pull-to-refresh re-reads every page shown. `PAGE_SIZE_PROPERTY` is the standard "Rows per page" property, the one the stock Data List shows: declare `pageSize: PAGE_SIZE_PROPERTY` in your `propertySchema` and pass the prop to the hook. The stock Data List now pages through this hook.
 
 ### What's new in 0.281.0 (contract 1.230.0)
 
@@ -3699,44 +3708,39 @@ export default function OpenTasks({ tableId, titleField, statusField }) {
 
 The filter operators are `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains` (a case-insensitive substring), `empty` and `nempty` (no value). On a list column (`STRING_ARRAY`, `INT_ARRAY`), `eq` keeps the rows whose list holds the value exactly, `empty` / `nempty` test whether it holds any, and every other operator is refused. In the array form a condition may carry `valueMode`: `"currentUser"` or `"currentUserGroup"` with `eq` or `neq` matches the signed-in user (or their groups) on a USER or USER_GROUP column, and `"relativeDate"` with an ordering operator reads `value` as "that many days ago".
 
-The result's `total` is how many rows match in all, not just this page: show "12 of 312" and page with `offset`. For a count, a sum or an average, use `useDatastoreFigure(tableId, { aggregate, column, filter })` instead of reading rows.
+The result's `total` is how many rows match in all, not just this page. **A list that grows reads its rows with `usePagedDatastoreQuery(tableId, { pageSize, ...query })`**, which takes the same options bar `limit` / `offset`, sets those itself, and appends the next page on `loadMore()`. Declare `pageSize: PAGE_SIZE_PROPERTY` in the `propertySchema` so the maker sets the rows per page. For a count, a sum or an average, use `useDatastoreFigure(tableId, { aggregate, column, filter })` instead of reading rows.
 
 **Narrow on the server, never over a fetched batch.** A widget that fetches `limit: 1000` and then filters or searches the rows in JavaScript only ever sees the first 1000; once the table grows past that, it misses rows without saying so. Send the search box's text as `q`, a chip's condition as `filter`, and page with `offset`. The checker warns about the batch pattern.
 
 ```js
 import { useEffect, useState } from "react";
-import { Pressable, Text, TextInput, View, useDatastoreQuery, useStableQuery } from "@colixsystems/widget-sdk";
-
-const PAGE = 50;
+import { Button, Pressable, Text, TextInput, View, usePagedDatastoreQuery, useStableQuery } from "@colixsystems/widget-sdk";
 
-export default function ContactList({ tableId }) {
+// manifest.propertySchema: { tableId: { type: "tableRef", … }, pageSize: PAGE_SIZE_PROPERTY }
+export default function ContactList({ tableId, pageSize }) {
   const [draft, setDraft] = useState("");
   const [search, setSearch] = useState("");
   const [status, setStatus] = useState("");
-  const [page, setPage] = useState(0);
   useEffect(() => {
-    const wait = setTimeout(() => { setSearch(draft.trim()); setPage(0); }, 250);
+    const wait = setTimeout(() => setSearch(draft.trim()), 250);
     return () => clearTimeout(wait);
   }, [draft]);
+  // A new search or status starts again from the first page.
   const query = useStableQuery(() => ({
     q: search,
     filter: status ? { status: `eq:${status}` } : undefined,
     sort: { field: "last_contacted", dir: "desc" },
-    limit: PAGE,
-    offset: page * PAGE,
+    pageSize,
   }));
-  const { data, total, loading, error } = useDatastoreQuery(tableId, query);
-  const pick = (next) => { setStatus(next); setPage(0); };
+  const { data, total, loading, error, hasMore, loadingMore, loadMore, retry } = usePagedDatastoreQuery(tableId, query);
   return (
     <View>
       <TextInput value={draft} onChangeText={setDraft} placeholder="Search" />
-      <Pressable onPress={() => pick(status === "Won" ? "" : "Won")}><Text>Won</Text></Pressable>
-      {error ? <Text>{error.message}</Text> : null}
+      <Pressable onPress={() => setStatus(status === "Won" ? "" : "Won")}><Text>Won</Text></Pressable>
       {loading ? <Text>Loading…</Text> : data.map((row) => <Text key={row.id}>{row.name}</Text>)}
+      {error ? <Button variant="ghost" title="Retry" onPress={retry} /> : null}
       <Text>{total ?? 0} contacts</Text>
-      {(page + 1) * PAGE < (total ?? 0) ? (
-        <Pressable onPress={() => setPage(page + 1)}><Text>Next page</Text></Pressable>
-      ) : null}
+      {hasMore ? <Button variant="ghost" title="Load more" busy={loadingMore} onPress={loadMore} /> : null}
     </View>
   );
 }

package/dist/contract.cjs

@@ -422,6 +422,16 @@ const BASIC_STYLE_SCHEMA = Object.freeze({
   }),
 });
 
+// sc-14120 — the "Rows per page" property a paged list declares, the same one
+// the stock Data List shows. usePagedDatastoreQuery clamps to its bounds.
+const PAGE_SIZE_PROPERTY = Object.freeze({
+  type: "number",
+  label: "Rows per page",
+  description: "How many records to load at first; a Load more control fetches the next batch.",
+  default: 25,
+  validation: Object.freeze({ min: 1, max: 500 }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1992,6 +2002,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "usePagedDatastoreQuery",
+    signature: "usePagedDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
+    description:
+      "Reads a table's rows a page at a time, for any list of records that " +
+      "can grow. Built on useDatastoreQuery: `options` takes the same `sort`, " +
+      "`filter`, `filterMode`, `q`, `includeCapabilities` and `live`, plus " +
+      "`pageSize` (default 25, clamped to 1-500; never pass `limit` or " +
+      "`offset`). The first `pageSize` rows load at once; `loadMore()` appends " +
+      "the next page after the rows in `data`, so each tap reads one page, not " +
+      "the whole list again. `hasMore` is false once every row the query " +
+      "matches (`total`) is loaded. `loadingMore` is true while a page is " +
+      "fetched: show the Load more button busy on it, and hide the button when " +
+      "`hasMore` is false. A failed page sets `error` and keeps the rows " +
+      "already shown; `retry()` fetches it again. A changed sort, filter, " +
+      "search or pageSize starts again from the first page. A write to the " +
+      "table, `live`, refetch() and pull-to-refresh re-read every page shown. " +
+      "Take the size from the maker's \"Rows per page\" property: declare " +
+      "the standard `pageSize` entry (CONTRACT.pageSizeProperty, exported as " +
+      "PAGE_SIZE_PROPERTY) in the propertySchema and pass the `pageSize` prop.",
+    returnShape: {
+      data: "Record[]",
+      total: "number | null",
+      hasMore: "boolean",
+      loading: "boolean",
+      fetching: "boolean",
+      loadingMore: "boolean",
+      error: "DatastoreError | null",
+      loadMore: "() => void",
+      retry: "() => void",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreFigure",
     signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
@@ -4105,7 +4151,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -6667,7 +6713,13 @@ const CONTRACT = deepFreeze({
   // 1.230.0: additive (sc-15164) — each access plan carries
   //    `purchase_available`; a store build buys a plan the workspace sells
   //    in-app through the store, and web purchases grant RevenueCat entitlements.
-  version: "1.230.0",
+  // 1.232.0: additive (sc-14120) — `usePagedDatastoreQuery` (a list read a
+  //    page at a time, with loadMore / hasMore / retry) and
+  //    `pageSizeProperty`, exported as `PAGE_SIZE_PROPERTY`: the standard
+  //    "Rows per page" property.
+  // 1.233.0: additive (sc-8115) — a `datastoreTemplate` table may declare
+  //    `deleteWhenLastMemberLeaves: true`.
+  version: "1.233.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6693,6 +6745,7 @@ const CONTRACT = deepFreeze({
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   basicStyleSchema: BASIC_STYLE_SCHEMA,
+  pageSizeProperty: PAGE_SIZE_PROPERTY,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/contract.js

@@ -418,6 +418,16 @@ const BASIC_STYLE_SCHEMA = Object.freeze({
   }),
 });
 
+// sc-14120 — the "Rows per page" property a paged list declares, the same one
+// the stock Data List shows. usePagedDatastoreQuery clamps to its bounds.
+const PAGE_SIZE_PROPERTY = Object.freeze({
+  type: "number",
+  label: "Rows per page",
+  description: "How many records to load at first; a Load more control fetches the next batch.",
+  default: 25,
+  validation: Object.freeze({ min: 1, max: 500 }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1988,6 +1998,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "usePagedDatastoreQuery",
+    signature: "usePagedDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
+    description:
+      "Reads a table's rows a page at a time, for any list of records that " +
+      "can grow. Built on useDatastoreQuery: `options` takes the same `sort`, " +
+      "`filter`, `filterMode`, `q`, `includeCapabilities` and `live`, plus " +
+      "`pageSize` (default 25, clamped to 1-500; never pass `limit` or " +
+      "`offset`). The first `pageSize` rows load at once; `loadMore()` appends " +
+      "the next page after the rows in `data`, so each tap reads one page, not " +
+      "the whole list again. `hasMore` is false once every row the query " +
+      "matches (`total`) is loaded. `loadingMore` is true while a page is " +
+      "fetched: show the Load more button busy on it, and hide the button when " +
+      "`hasMore` is false. A failed page sets `error` and keeps the rows " +
+      "already shown; `retry()` fetches it again. A changed sort, filter, " +
+      "search or pageSize starts again from the first page. A write to the " +
+      "table, `live`, refetch() and pull-to-refresh re-read every page shown. " +
+      "Take the size from the maker's \"Rows per page\" property: declare " +
+      "the standard `pageSize` entry (CONTRACT.pageSizeProperty, exported as " +
+      "PAGE_SIZE_PROPERTY) in the propertySchema and pass the `pageSize` prop.",
+    returnShape: {
+      data: "Record[]",
+      total: "number | null",
+      hasMore: "boolean",
+      loading: "boolean",
+      fetching: "boolean",
+      loadingMore: "boolean",
+      error: "DatastoreError | null",
+      loadMore: "() => void",
+      retry: "() => void",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreFigure",
     signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
@@ -4101,7 +4147,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -6663,7 +6709,13 @@ const CONTRACT = deepFreeze({
   // 1.230.0: additive (sc-15164) — each access plan carries
   //    `purchase_available`; a store build buys a plan the workspace sells
   //    in-app through the store, and web purchases grant RevenueCat entitlements.
-  version: "1.230.0",
+  // 1.232.0: additive (sc-14120) — `usePagedDatastoreQuery` (a list read a
+  //    page at a time, with loadMore / hasMore / retry) and
+  //    `pageSizeProperty`, exported as `PAGE_SIZE_PROPERTY`: the standard
+  //    "Rows per page" property.
+  // 1.233.0: additive (sc-8115) — a `datastoreTemplate` table may declare
+  //    `deleteWhenLastMemberLeaves: true`.
+  version: "1.233.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6689,6 +6741,7 @@ const CONTRACT = deepFreeze({
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   basicStyleSchema: BASIC_STYLE_SCHEMA,
+  pageSizeProperty: PAGE_SIZE_PROPERTY,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.

package/dist/index.d.ts

@@ -305,6 +305,14 @@ export interface WidgetDatastoreTemplateTable {
    * upgrade that declares it turns it on for the existing table.
    */
   presence?: boolean;
+  /**
+   * When true, a row is deleted for good, with every row a CASCADE relation
+   * ties to it, once a signed-in member giving up their own grant leaves it
+   * with none and no table-wide grant lets anyone read it. A row that never had a grant and a
+   * revoke made in the Studio never delete. An upgrade that declares it turns
+   * it on for the existing table.
+   */
+  deleteWhenLastMemberLeaves?: boolean;
   /**
    * REQ-TEMPLATES-ACL: optional table-level public grant. Omitted means
    * the table starts purely per-record (record-level grants are the only
@@ -1160,6 +1168,48 @@ export function useDatastoreQuery<T = unknown>(
   query?: Query,
 ): QueryResult<T>;
 
+export interface PagedQueryOptions extends Omit<Query, "limit" | "offset"> {
+  /** Rows per page: default 25, clamped to 1-500. Pass the `pageSize` prop. */
+  pageSize?: number;
+}
+
+export interface PagedQueryResult<T> {
+  /** Every row loaded so far, first page first. */
+  data: T[];
+  /** How many rows the query matches in all; null until known. */
+  total: number | null;
+  /** False once every matching row is loaded. Hide Load more on it. */
+  hasMore: boolean;
+  /** True only until the first page lands. */
+  loading: boolean;
+  /** True while any page, or a re-read of them, is in flight. */
+  fetching: boolean;
+  /** True while `loadMore()` fetches the next page. */
+  loadingMore: boolean;
+  /** A failed page; the rows already loaded stay in `data`. */
+  error: Error | null;
+  /** Appends the next page. Does nothing when `hasMore` is false. */
+  loadMore(): void;
+  /** Fetches the failed page again (or re-reads the list). */
+  retry(): void;
+  refetch(): Promise<void>;
+}
+
+/**
+ * A table's rows a page at a time: the first `pageSize` at once, the next on
+ * each `loadMore()`. A changed sort, filter or page size starts again.
+ */
+export function usePagedDatastoreQuery<T = unknown>(
+  table: string | null | undefined,
+  options?: PagedQueryOptions,
+): PagedQueryResult<T>;
+
+/**
+ * The standard "Rows per page" property (number, default 25, 1-500), the one
+ * the stock Data List shows. Declare it as `pageSize` in a list's propertySchema.
+ */
+export const PAGE_SIZE_PROPERTY: Readonly<WidgetPropertyDef>;
+
 export interface FigureOptions {
   /** Default `"count"`. `"sum"` and `"average"` read the number `column`. */
   aggregate?: "count" | "sum" | "average";

package/dist/index.js

@@ -136,6 +136,7 @@ export {
 // sc-15163 — native-only in-app purchase; the web Player brokers none.
 export { usePurchases, PurchasesError } from "./purchases.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export { usePagedDatastoreQuery, PAGE_SIZE_PROPERTY } from "./paged-query.js";
 export {
   useDatastoreAggregate,
   useUserStats,

package/dist/index.native.js

@@ -134,6 +134,7 @@ export {
 // sc-15163 — native-only in-app purchase; the web Player brokers none.
 export { usePurchases, PurchasesError } from "./purchases.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
+export { usePagedDatastoreQuery, PAGE_SIZE_PROPERTY } from "./paged-query.js";
 export {
   useDatastoreAggregate,
   useUserStats,

package/dist/paged-query.js

@@ -0,0 +1,193 @@
+// sc-14120 — a list of records read a page at a time, shared by the stock Data
+// List and custom widgets on both hosts. The first page is useDatastoreQuery's,
+// so it keeps that hook's stale-while-revalidate, write re-reads, `live` and
+// pull-to-refresh; the pages after it are appended by offset. Platform-free,
+// so the web and native entries export this one module.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { CONTRACT } from "./contract.js";
+import { toDatastoreError, useDatastoreQuery, useWidgetContextOrThrow } from "./hooks.js";
+
+export const PAGE_SIZE_PROPERTY = CONTRACT.pageSizeProperty;
+
+// REQ-QUERY-02: the server returns at most this many rows per request.
+const MAX_ROWS_PER_READ = 1000;
+
+const NO_PAGES = Object.freeze({ key: null, rows: Object.freeze([]), pages: 0, total: null });
+
+/** A `pageSize` prop as the page size read: whole, within the property's bounds. */
+export function normalisePageSize(value) {
+  const { min, max } = PAGE_SIZE_PROPERTY.validation;
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n) || n < min) return PAGE_SIZE_PROPERTY.default;
+  return Math.min(n, max);
+}
+
+function windowKey(table, pageSize, query) {
+  try {
+    return JSON.stringify([table, pageSize, query]);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/** Rows `[offset, offset + count)`, in requests the server's row cap allows. */
+async function readRange(ns, query, offset, count) {
+  const reads = [];
+  for (let start = 0; start < count; start += MAX_ROWS_PER_READ) {
+    const limit = Math.min(MAX_ROWS_PER_READ, count - start);
+    reads.push(ns.list({ ...query, limit, offset: offset + start }));
+  }
+  const answers = await Promise.all(reads);
+  const rows = [];
+  let total = null;
+  for (const res of answers) {
+    if (res && Array.isArray(res.data)) rows.push(...res.data);
+    if (res && res.meta && Number.isFinite(res.meta.total)) total = res.meta.total;
+  }
+  return { rows, total };
+}
+
+// A row that moved into the next page between two reads shows once.
+function withoutRepeats(first, more) {
+  if (more.length === 0) return first;
+  const seen = new Set();
+  const out = [];
+  for (const row of [...first, ...more]) {
+    const id = row && row.id;
+    if (id !== undefined && id !== null) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+    }
+    out.push(row);
+  }
+  return out;
+}
+
+/**
+ * A table's rows, `pageSize` at a time, with `loadMore()` appending the next
+ * page. See the usePagedDatastoreQuery CONTRACT entry.
+ */
+export function usePagedDatastoreQuery(table, options) {
+  const ctx = useWidgetContextOrThrow("usePagedDatastoreQuery");
+  // `limit` and `offset` are the hook's to set, so a caller's are dropped.
+  // eslint-disable-next-line no-unused-vars
+  const { pageSize: requestedPageSize, limit, offset, ...query } = options || {};
+  const pageSize = normalisePageSize(requestedPageSize);
+  const boundTable = table || null;
+  const first = useDatastoreQuery(boundTable, { ...query, limit: pageSize });
+
+  const key = boundTable ? windowKey(boundTable, pageSize, query) : null;
+  const [more, setMore] = useState(NO_PAGES);
+  // The page read in flight or failed: { key, seq, pages, appending, error }.
+  const [op, setOp] = useState(null);
+  // A new query drops the old one's pages and reads before they can return.
+  const [windowOf, setWindowOf] = useState(key);
+  if (windowOf !== key) {
+    setWindowOf(key);
+    setMore(NO_PAGES);
+    setOp(null);
+  }
+
+  // Live inputs held in refs so loadMore / retry stay stable callbacks.
+  const live = useRef({});
+  live.current = {
+    key,
+    table: boundTable,
+    pageSize,
+    query,
+    records: ctx.datastore && ctx.datastore.records,
+    firstFetching: first.fetching,
+    more: more.key === key ? more : NO_PAGES,
+    op: op && op.key === key ? op : null,
+  };
+  const seqRef = useRef(0);
+  useEffect(() => {
+    seqRef.current += 1;
+  }, [key]);
+
+  // Reads pages 1..`pages` after the first one; `appending` reads only the last.
+  const readPages = useCallback(async (pages, appending) => {
+    const { key: k, table: t, pageSize: size, query: q, records, more: m } = live.current;
+    if (!k || !records) return;
+    const seq = ++seqRef.current;
+    setOp({ key: k, seq, pages, appending, error: null });
+    const from = appending ? pages : 1;
+    try {
+      const { rows, total } = await readRange(records(t), q, from * size, (pages - from + 1) * size);
+      if (seqRef.current !== seq || live.current.key !== k) return;
+      setMore({ key: k, rows: appending ? [...m.rows, ...rows] : rows, pages, total });
+      setOp(null);
+    } catch (err) {
+      if (seqRef.current !== seq || live.current.key !== k) return;
+      setOp({ key: k, seq, pages, appending, error: toDatastoreError(err) });
+    }
+  }, []);
+
+  const current = live.current.more;
+  const pending = live.current.op;
+  const total = first.total !== null ? first.total : current.total;
+  const loaded = current.pages === 0 ? first.data.length : pageSize + current.rows.length;
+  const lastPageFull = current.pages === 0 ? first.data.length >= pageSize : current.rows.length >= current.pages * pageSize;
+  const hasMore = Boolean(key) && !first.loading && !first.error && (total !== null ? loaded < total : lastPageFull);
+  live.current.hasMore = hasMore;
+
+  const loadMore = useCallback(() => {
+    const { key: k, more: m, op: o, hasMore: canLoad, firstFetching } = live.current;
+    if (!canLoad) return;
+    if (m.pages === 0 && firstFetching && !o) {
+      // The first page may still be the previous query's: wait for it.
+      setOp({ key: k, seq: ++seqRef.current, pages: 1, appending: true, queued: true, error: null });
+      return;
+    }
+    if (o && !o.error) {
+      // A page is already on its way; a re-read in flight takes one page more.
+      if (!o.appending) readPages(o.pages + 1, false);
+      return;
+    }
+    readPages(m.pages + 1, true);
+  }, [readPages]);
+
+  // A re-read of the first page (a write, `live`, refetch, pull-to-refresh)
+  // re-reads the pages after it, so the whole list shown stays current.
+  const firstRows = useRef(first.data);
+  useEffect(() => {
+    if (firstRows.current === first.data) return;
+    firstRows.current = first.data;
+    const { more: m, op: o } = live.current;
+    if (o && o.queued && m.pages === 0) {
+      readPages(1, true);
+      return;
+    }
+    const pages = Math.max(m.pages, o && !o.error ? o.pages : 0);
+    if (pages > 0) readPages(pages, false);
+  }, [first.data, readPages]);
+
+  const refetch = first.refetch;
+  const firstFailed = Boolean(first.error);
+  const firstFailedRef = useRef(firstFailed);
+  firstFailedRef.current = firstFailed;
+  const retry = useCallback(() => {
+    const o = live.current.op;
+    if (o && o.error) readPages(o.pages, o.appending);
+    if (firstFailedRef.current || !(o && o.error)) refetch();
+  }, [readPages, refetch]);
+
+  const data = useMemo(
+    () => withoutRepeats(first.data, current.rows),
+    [first.data, current.rows],
+  );
+  const waiting = Boolean(pending && !pending.error && !(pending.queued && firstFailed));
+  const loadingMore = waiting && pending.appending;
+  return {
+    data,
+    total,
+    hasMore,
+    loading: first.loading,
+    fetching: first.fetching || waiting,
+    loadingMore,
+    error: first.error || (pending && pending.error) || null,
+    loadMore,
+    retry,
+    refetch,
+  };
+}

package/dist/source-mask.cjs

@@ -28,8 +28,10 @@ function stripNonCode(
   source,
   { keepStrings = false, keepTemplates = keepStrings } = {},
 ) {
-  let out = "";
   const n = source.length;
+  // Code units, not `out += ch`: a per-character rope costs superlinear GC.
+  const out = new Uint16Array(n);
+  let written = 0;
   let mode = "code"; // code | line | block | sq | dq | tmpl
   // Brace depth, plus a stack of the depths at which an enclosing template
   // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
@@ -37,10 +39,10 @@ function stripNonCode(
   let braceDepth = 0;
   const tmplStack = [];
   const keep = (ch) => {
-    out += ch;
+    out[written++] = ch.charCodeAt(0);
   };
   const blank = (ch) => {
-    out += ch === "\n" || ch === "\r" ? ch : " ";
+    out[written++] = ch === "\n" || ch === "\r" ? ch.charCodeAt(0) : SPACE;
   };
   // String / template CONTENT: blanked for the banned-identifier scan
   // (prose must not trip `no-window`), kept for the host-API-URL scan,
@@ -162,7 +164,19 @@ function stripNonCode(
       }
     }
   }
-  return out;
+  return decodeCodeUnits(out.subarray(0, written));
+}
+
+const SPACE = 0x20;
+// fromCharCode spreads its arguments, so decode in stack-safe chunks.
+const DECODE_CHUNK = 8192;
+
+function decodeCodeUnits(units) {
+  const parts = [];
+  for (let at = 0; at < units.length; at += DECODE_CHUNK) {
+    parts.push(String.fromCharCode.apply(null, units.subarray(at, at + DECODE_CHUNK)));
+  }
+  return parts.join("");
 }
 module.exports = {
   stripNonCode,

package/dist/source-mask.js

@@ -24,8 +24,10 @@ export function stripNonCode(
   source,
   { keepStrings = false, keepTemplates = keepStrings } = {},
 ) {
-  let out = "";
   const n = source.length;
+  // Code units, not `out += ch`: a per-character rope costs superlinear GC.
+  const out = new Uint16Array(n);
+  let written = 0;
   let mode = "code"; // code | line | block | sq | dq | tmpl
   // Brace depth, plus a stack of the depths at which an enclosing template
   // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
@@ -33,10 +35,10 @@ export function stripNonCode(
   let braceDepth = 0;
   const tmplStack = [];
   const keep = (ch) => {
-    out += ch;
+    out[written++] = ch.charCodeAt(0);
   };
   const blank = (ch) => {
-    out += ch === "\n" || ch === "\r" ? ch : " ";
+    out[written++] = ch === "\n" || ch === "\r" ? ch.charCodeAt(0) : SPACE;
   };
   // String / template CONTENT: blanked for the banned-identifier scan
   // (prose must not trip `no-window`), kept for the host-API-URL scan,
@@ -158,5 +160,17 @@ export function stripNonCode(
       }
     }
   }
-  return out;
+  return decodeCodeUnits(out.subarray(0, written));
+}
+
+const SPACE = 0x20;
+// fromCharCode spreads its arguments, so decode in stack-safe chunks.
+const DECODE_CHUNK = 8192;
+
+function decodeCodeUnits(units) {
+  const parts = [];
+  for (let at = 0; at < units.length; at += DECODE_CHUNK) {
+    parts.push(String.fromCharCode.apply(null, units.subarray(at, at + DECODE_CHUNK)));
+  }
+  return parts.join("");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.281.0",
+  "version": "0.284.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -418,6 +418,16 @@ const BASIC_STYLE_SCHEMA = Object.freeze({
   }),
 });
 
+// sc-14120 — the "Rows per page" property a paged list declares, the same one
+// the stock Data List shows. usePagedDatastoreQuery clamps to its bounds.
+const PAGE_SIZE_PROPERTY = Object.freeze({
+  type: "number",
+  label: "Rows per page",
+  description: "How many records to load at first; a Load more control fetches the next batch.",
+  default: 25,
+  validation: Object.freeze({ min: 1, max: 500 }),
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -1988,6 +1998,42 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  {
+    name: "usePagedDatastoreQuery",
+    signature: "usePagedDatastoreQuery(tableId, options)",
+    optionalArgs: ["options"],
+    description:
+      "Reads a table's rows a page at a time, for any list of records that " +
+      "can grow. Built on useDatastoreQuery: `options` takes the same `sort`, " +
+      "`filter`, `filterMode`, `q`, `includeCapabilities` and `live`, plus " +
+      "`pageSize` (default 25, clamped to 1-500; never pass `limit` or " +
+      "`offset`). The first `pageSize` rows load at once; `loadMore()` appends " +
+      "the next page after the rows in `data`, so each tap reads one page, not " +
+      "the whole list again. `hasMore` is false once every row the query " +
+      "matches (`total`) is loaded. `loadingMore` is true while a page is " +
+      "fetched: show the Load more button busy on it, and hide the button when " +
+      "`hasMore` is false. A failed page sets `error` and keeps the rows " +
+      "already shown; `retry()` fetches it again. A changed sort, filter, " +
+      "search or pageSize starts again from the first page. A write to the " +
+      "table, `live`, refetch() and pull-to-refresh re-read every page shown. " +
+      "Take the size from the maker's \"Rows per page\" property: declare " +
+      "the standard `pageSize` entry (CONTRACT.pageSizeProperty, exported as " +
+      "PAGE_SIZE_PROPERTY) in the propertySchema and pass the `pageSize` prop.",
+    returnShape: {
+      data: "Record[]",
+      total: "number | null",
+      hasMore: "boolean",
+      loading: "boolean",
+      fetching: "boolean",
+      loadingMore: "boolean",
+      error: "DatastoreError | null",
+      loadMore: "() => void",
+      retry: "() => void",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreFigure",
     signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
@@ -4101,7 +4147,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 100 tables, 200 columns per table, 100 sample rows per table and 20000 sample cells across the whole template (each row counts the keys it sets, and at least one, summed over every table). RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 32 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, `@uuid` on UUID (a new random id per row), or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` / `@uuid` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table. A table whose rows people join and leave through per-record grants (conversations) may declare `deleteWhenLastMemberLeaves: true`: when a signed-in member giving up their own grant leaves a row with no grant and no table-wide grant lets anyone read it, the row and every row a CASCADE relation ties to it (including rows deleted earlier) are deleted for good. A row that never had a grant (a seeded sample row) is never deleted this way, and a revoke made in the Studio never deletes. An upgrade that declares it turns it on for the existing table. A ONE_TO_ONE / ONE_TO_MANY RELATION may declare `latestVia: \"<relation column on its target that points back>\"` (onDelete left at SET_NULL; that relation must have inheritAcl and be immutable): the server keeps it at the newest row of the target table that points back at this row. A column may declare `copyOf: { via, column }`: the server keeps it equal to `column` on the row the latest-row column `via` points at (same type, or text into text, cut to 140 characters in a STRING column; a copy of an encrypted column must be encrypted, and a copy cannot inheritAcl). Both are written only by the server, in the same write as the related row; a client value is ignored. A table may declare `constraints`, checked on every write for every client and refused as CONSTRAINT_VIOLATION: `unique` ({ columns, partitionColumns?, unlessRelated?: { relation, column } } — waived for rows whose related row has that yes/no column set), `no-overlap` ({ startColumn, endColumn, partitionColumns? }), `related-open` ({ relation, closedColumn } — no row is added, changed or removed while the related row's column is filled) and `related-index` ({ column, relation, listColumn } — the number must be a position in the related row's list). An upgrade adds a declared constraint to an existing table without judging the rows already in it.",
   },
   translations: {
     type: "object",
@@ -6663,7 +6709,13 @@ const CONTRACT = deepFreeze({
   // 1.230.0: additive (sc-15164) — each access plan carries
   //    `purchase_available`; a store build buys a plan the workspace sells
   //    in-app through the store, and web purchases grant RevenueCat entitlements.
-  version: "1.230.0",
+  // 1.232.0: additive (sc-14120) — `usePagedDatastoreQuery` (a list read a
+  //    page at a time, with loadMore / hasMore / retry) and
+  //    `pageSizeProperty`, exported as `PAGE_SIZE_PROPERTY`: the standard
+  //    "Rows per page" property.
+  // 1.233.0: additive (sc-8115) — a `datastoreTemplate` table may declare
+  //    `deleteWhenLastMemberLeaves: true`.
+  version: "1.233.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6689,6 +6741,7 @@ const CONTRACT = deepFreeze({
   themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   basicStyleSchema: BASIC_STYLE_SCHEMA,
+  pageSizeProperty: PAGE_SIZE_PROPERTY,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   // sc-10829 — the hook a `badgeCounter: true` entry exports by name.