@colixsystems/widget-sdk 0.223.0 → 0.228.0

package/README.md

@@ -84,7 +84,69 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.223.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.228.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.228.0 (contract 1.184.0)
+
+**A widget can ask for the whole screen — manifest `prefersFitToScreen` and `useFitScreen()`.** A page section can be set to "Fit to screen": it runs edge to edge across the app's content area (no page margins, no width cap) and takes the rest of the screen below the sections above it, on every screen size, in the Player and in the exported app. Set `prefersFitToScreen: true` in your manifest when your widget is built for that — it scrolls its own content inside the height it is given and keeps its controls in view, like a messenger, a map or a full-height board. In a fit section the host then gives your widget a box exactly the height left; a widget without the field grows with its content there, and the page scrolls. A maker who drops your widget at the top level of a page then gets the setting turned on for that section (they can switch it off, and it stays off), and the AppStudio app-builder fits the section it plans your widget into. Leave it `false` or omit it otherwise.
+
+When your widget is that section's surface, `useFill()` is `true` and so is the new `useFitScreen()`. Drop your own frame then — border, rounded corners, shadow — so the widget meets the screen's edges cleanly; the host has already removed your outer margin.
+
+```jsx
+import { useFill, useFitScreen, View } from "@colixsystems/widget-sdk";
+
+export default function Board() {
+  const fill = useFill();
+  const edgeToEdge = useFitScreen();
+  return (
+    <View style={[fill ? { flex: 1, minHeight: 0 } : { height: 480 }, !edgeToEdge && { borderWidth: 1, borderRadius: 12 }]}>
+      {/* ... */}
+    </View>
+  );
+}
+```
+
+Additive: existing manifests omit the field and read `false`, and a host that never fits a widget leaves both hooks `false`. A published widget that must also run in an app whose Player is older than 0.228.0 reads the hook off a namespace import and treats a missing one as `false` (`import * as sdk from "@colixsystems/widget-sdk"; const useFitScreen = typeof sdk.useFitScreen === "function" ? sdk.useFitScreen : () => false;`, at module level): a named import of an export the host does not have stops the widget loading.
+
+### What's new in 0.227.0 (contract 1.183.0)
+
+**Columns the server keeps, and rules every client meets.** A `datastoreTemplate` can now say what a widget used to write itself and the server could not check:
+
+- `latestVia: "<relation column on the target that points back>"` on a ONE_TO_ONE / ONE_TO_MANY relation (with `onDelete` left at `SET_NULL`; the relation back must have `inheritAcl: true` and `immutable: true`) keeps it pointing at the newest related row — the newest message of a conversation.
+- `copyOf: { via, column }` keeps a column equal to `column` on the row that latest-row column points at — the last message's text, time and author on the conversation row. Text copied into a STRING column is cut to 140 characters; a copy of an encrypted column must be `encrypted` too, and a copy cannot `inheritAcl`.
+
+Both are written only by the server, in the same write as the related row, so a list reads who wrote last, and when, without trusting whoever wrote the parent row. A client value for them is ignored; read them back.
+
+A table may also declare `constraints`, checked on every write and refused as `CONSTRAINT_VIOLATION`: `unique` (now with `unlessRelated`, waived for rows whose related row has a yes/no column set), `no-overlap`, `related-open` (no row is added, changed or removed while the related row's column is filled — votes on a closed poll) and `related-index` (a whole number that must be a position in the related row's list — a poll option). Additive.
+
+### What's new in 0.226.0 (contract 1.182.0)
+
+**Rank by a column — `useDatastoreAggregate(tableId, { groupBy, order, limit })`.** Group a table by an ordinary column (text, number, yes/no, date or user) and get `groups: [{ group, count, sum }]`, counted on the server over every row the viewer can read, so it stays exact past the 1000-row page a list read returns. A user column's `group` is the user id, so a ranking is one call:
+
+```jsx
+const { groups } = useDatastoreAggregate(props.tableId, {
+  groupBy: "Reporter",
+  order: "count:desc",
+  limit: 10,
+  filter: { Reporter: "nempty:" },
+});
+// groups: [{ group: "<user id>", count: 42, sum: 0 }, …]
+```
+
+`order` is `count`, `sum` or `group`, then `:asc` or `:desc` (ascending when left out; by value when there is no `order`); `limit` is 1–1000. Rows with no value form one `Uncategorized` group. Encrypted, array, file and relation columns cannot be grouped.
+
+### What's new in 0.225.0 (contract 1.181.0)
+
+**Chart a table over time — `useDatastoreAggregate(tableId, spec)`.** Counts rows per UTC day or ISO week (Monday) on the server, over every row the viewer may read, so the series stays exact past the 1000-row page a list read returns. Every bucket of the range comes back, empty ones as `count: 0`, so a chart has no gaps. `groupBy` is `"created_at"` (new rows, the default) or `"updated_at"` (changed rows); any other column is refused with a `VALIDATION` error. `sumColumn` adds up a plain number column per bucket. At most 31 buckets.
+
+```jsx
+const { buckets, loading } = useDatastoreAggregate(props.tableId, { bucket: "week", from: twelveWeeksAgo });
+// buckets: [{ date: "2026-09-28", count: 14, sum: 0 }, …]
+```
+
+### What's new in 0.224.0 (contract 1.180.0)
+
+**A logged-out visitor can attach files to the row they just created.** On a table that lets everyone create rows, the create → `upload(file, { recordId: row.id })` → `update(row.id, { File: stored.id })` flow now works without signing in, for a few minutes after the create. The host carries a grant for that one row from the create to its upload and update, so widget code does not change. The visitor cannot edit the row's other fields, read the file back on a private table, attach more than ten files, or attach to any other row; editing an existing row's files still needs a signed-in user. Additive.
 
 ### What's new in 0.223.0 (contract 1.179.0)
 

package/dist/contract.cjs

@@ -991,6 +991,24 @@ const HOOKS = [
     requiredContextSlice: ["fill"],
     scopes: null,
   },
+  {
+    name: "useFitScreen",
+    signature: "useFitScreen()",
+    description:
+      "Returns true when this widget is the surface of a page section set to " +
+      "\"Fit to screen\": the section runs edge to edge across the app's " +
+      "content area and takes the rest of the screen, so the widget should " +
+      "drop its own frame (border, rounded corners, shadow) and meet the " +
+      "edges cleanly. useFill() is true as well then, and the host has already " +
+      "removed the widget's outer margin. Defaults to false wherever the host " +
+      "has not fitted the widget, so calling it is always safe. The SAME value " +
+      "is injected by the web Player and the native export.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fitScreen"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -1397,7 +1415,8 @@ const HOOKS = [
       "create the row, call upload(file, { recordId: row.id }) — the per-call " +
       "recordId names the row the hook could not know at render — then write " +
       "the returned id into the FILE column with update(). A logged-out " +
-      "visitor cannot upload into a record space. For a file that belongs to " +
+      "visitor may do this only for a row they just created, within a few " +
+      "minutes, and never edits other rows' files. For a file that belongs to " +
       "no row: 'public' for content the app shows to anyone browsing, " +
       "'project' for signed-in workspace users only, 'personal' for a file " +
       "private to the uploading app user.",
@@ -1796,6 +1815,45 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  // sc-10942 — rows per day or week, counted on the server over every row the
+  // viewer may read. Date columns only until column grouping is exact too.
+  {
+    name: "useDatastoreAggregate",
+    signature:
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+    description:
+      "Counts rows on the server over EVERY row the viewer can read, so it is " +
+      "exact past the 1000-row page a list read returns — never group " +
+      "useDatastoreQuery rows by hand. With `sumColumn` it also totals a plain " +
+      "number column. BY DATE (`groupBy` \"created_at\", the default, or " +
+      "\"updated_at\"): a SERIES for a chart, one entry per UTC day or ISO week " +
+      "(Monday) in `buckets`; `bucket` is \"day\" (default) or \"week\"; " +
+      "`from` / `to` are ISO dates (default: the 30 days, or 12 weeks, up to " +
+      "now), at most 31 buckets, empty ones as count 0 so a chart has no gaps. " +
+      "BY A COLUMN (any other `groupBy`: a text, number, yes/no, date or user " +
+      "column): one entry per value in `groups`. A USER column's `group` is the " +
+      "user id (resolve names with useDirectory({ ids })), so `order: \"count:desc\", " +
+      "limit: 10` ranks the ten people with the most rows. `order` is count, sum " +
+      "or group, then :asc or :desc (default: by value); `limit` is 1-1000. Rows " +
+      "with no value form one \"Uncategorized\" group; on a user column, leave " +
+      "them out with a `nempty:` filter. Encrypted, array, file and relation " +
+      "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
+      "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
+      "table until a bound table is known.",
+    returnShape: {
+      buckets:
+        "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
+      groups:
+        "Array<{ group, count, sum }>  // by a column; a USER column's group is the user id",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreSchema",
     signature: "useDatastoreSchema(tableId)",
@@ -3532,6 +3590,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
     default: false,
   },
+  prefersFitToScreen: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -3563,7 +3628,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: 8 tables, 24 columns per 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 8 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, 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` 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.",
+      "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: 8 tables, 24 columns per 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 8 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, 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` 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.",
   },
   translations: {
     type: "object",
@@ -3607,6 +3672,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11348 — optional host hint backing useFitScreen(): the widget is the
+  // surface of a section set to Fit to screen, so it drops its own frame.
+  fitScreen: {
+    description:
+      "Optional host layout hint (boolean). True when this widget is the " +
+      "surface of a page section set to Fit to screen: edge to edge, the rest " +
+      "of the screen. Backs useFitScreen(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -5882,7 +5957,28 @@ const CONTRACT = deepFreeze({
   //    `{ colors, onImage }`: the theme colours as they read over the picture.
   // 1.179.0: additive (sc-11253) — `useNavigation().goToStartPage()` opens
   //    the signed-in user's own start page on both hosts.
-  version: "1.179.0",
+  // 1.180.0: additive (sc-11244) — a logged-out visitor may attach files to
+  //    the row they just created, for a few minutes: the host carries a grant
+  //    from the create to that row's upload and update. Widget code is the
+  //    same create → upload → update flow.
+  // 1.181.0: additive (sc-10942) — `useDatastoreAggregate(tableId, spec)`
+  //    counts rows per day or week on the server (date columns only), through
+  //    `records(t).aggregate`'s new bucket/from/to.
+  // 1.182.0: additive (sc-10737) — `useDatastoreAggregate` groups by an
+  //    ordinary column too, into `groups` ([{ group, count, sum }]), with
+  //    `order` and `limit` for a top N; counted on the server over every
+  //    readable row. A user column groups by user id.
+  // 1.183.0: additive (sc-10766) — a datastoreTemplate column may declare
+  //    `latestVia` (a server-kept pointer to the newest related row) or
+  //    `copyOf: { via, column }` (a server-kept copy read through one), and
+  //    a table may declare `constraints` (`unique` with `unlessRelated`,
+  //    `no-overlap`, `related-open`, `related-index`).
+  // 1.184.0: additive (sc-11348) — OPTIONAL manifest field
+  //    `prefersFitToScreen` (dropping the widget at a page's top level turns
+  //    that section's Fit to screen on), and `useFitScreen()` with its
+  //    optional `fitScreen` host hint: the widget is a fit section's surface,
+  //    so it drops its own frame. Existing manifests and hosts read false.
+  version: "1.184.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -991,6 +991,24 @@ const HOOKS = [
     requiredContextSlice: ["fill"],
     scopes: null,
   },
+  {
+    name: "useFitScreen",
+    signature: "useFitScreen()",
+    description:
+      "Returns true when this widget is the surface of a page section set to " +
+      "\"Fit to screen\": the section runs edge to edge across the app's " +
+      "content area and takes the rest of the screen, so the widget should " +
+      "drop its own frame (border, rounded corners, shadow) and meet the " +
+      "edges cleanly. useFill() is true as well then, and the host has already " +
+      "removed the widget's outer margin. Defaults to false wherever the host " +
+      "has not fitted the widget, so calling it is always safe. The SAME value " +
+      "is injected by the web Player and the native export.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fitScreen"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -1397,7 +1415,8 @@ const HOOKS = [
       "create the row, call upload(file, { recordId: row.id }) — the per-call " +
       "recordId names the row the hook could not know at render — then write " +
       "the returned id into the FILE column with update(). A logged-out " +
-      "visitor cannot upload into a record space. For a file that belongs to " +
+      "visitor may do this only for a row they just created, within a few " +
+      "minutes, and never edits other rows' files. For a file that belongs to " +
       "no row: 'public' for content the app shows to anyone browsing, " +
       "'project' for signed-in workspace users only, 'personal' for a file " +
       "private to the uploading app user.",
@@ -1796,6 +1815,45 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  // sc-10942 — rows per day or week, counted on the server over every row the
+  // viewer may read. Date columns only until column grouping is exact too.
+  {
+    name: "useDatastoreAggregate",
+    signature:
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+    description:
+      "Counts rows on the server over EVERY row the viewer can read, so it is " +
+      "exact past the 1000-row page a list read returns — never group " +
+      "useDatastoreQuery rows by hand. With `sumColumn` it also totals a plain " +
+      "number column. BY DATE (`groupBy` \"created_at\", the default, or " +
+      "\"updated_at\"): a SERIES for a chart, one entry per UTC day or ISO week " +
+      "(Monday) in `buckets`; `bucket` is \"day\" (default) or \"week\"; " +
+      "`from` / `to` are ISO dates (default: the 30 days, or 12 weeks, up to " +
+      "now), at most 31 buckets, empty ones as count 0 so a chart has no gaps. " +
+      "BY A COLUMN (any other `groupBy`: a text, number, yes/no, date or user " +
+      "column): one entry per value in `groups`. A USER column's `group` is the " +
+      "user id (resolve names with useDirectory({ ids })), so `order: \"count:desc\", " +
+      "limit: 10` ranks the ten people with the most rows. `order` is count, sum " +
+      "or group, then :asc or :desc (default: by value); `limit` is 1-1000. Rows " +
+      "with no value form one \"Uncategorized\" group; on a user column, leave " +
+      "them out with a `nempty:` filter. Encrypted, array, file and relation " +
+      "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
+      "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
+      "table until a bound table is known.",
+    returnShape: {
+      buckets:
+        "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
+      groups:
+        "Array<{ group, count, sum }>  // by a column; a USER column's group is the user id",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreSchema",
     signature: "useDatastoreSchema(tableId)",
@@ -3528,6 +3586,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
     default: false,
   },
+  prefersFitToScreen: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -3559,7 +3624,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: 8 tables, 24 columns per 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 8 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, 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` 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.",
+      "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: 8 tables, 24 columns per 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 8 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, 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` 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.",
   },
   translations: {
     type: "object",
@@ -3603,6 +3668,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11348 — optional host hint backing useFitScreen(): the widget is the
+  // surface of a section set to Fit to screen, so it drops its own frame.
+  fitScreen: {
+    description:
+      "Optional host layout hint (boolean). True when this widget is the " +
+      "surface of a page section set to Fit to screen: edge to edge, the rest " +
+      "of the screen. Backs useFitScreen(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -5878,7 +5953,28 @@ const CONTRACT = deepFreeze({
   //    `{ colors, onImage }`: the theme colours as they read over the picture.
   // 1.179.0: additive (sc-11253) — `useNavigation().goToStartPage()` opens
   //    the signed-in user's own start page on both hosts.
-  version: "1.179.0",
+  // 1.180.0: additive (sc-11244) — a logged-out visitor may attach files to
+  //    the row they just created, for a few minutes: the host carries a grant
+  //    from the create to that row's upload and update. Widget code is the
+  //    same create → upload → update flow.
+  // 1.181.0: additive (sc-10942) — `useDatastoreAggregate(tableId, spec)`
+  //    counts rows per day or week on the server (date columns only), through
+  //    `records(t).aggregate`'s new bucket/from/to.
+  // 1.182.0: additive (sc-10737) — `useDatastoreAggregate` groups by an
+  //    ordinary column too, into `groups` ([{ group, count, sum }]), with
+  //    `order` and `limit` for a top N; counted on the server over every
+  //    readable row. A user column groups by user id.
+  // 1.183.0: additive (sc-10766) — a datastoreTemplate column may declare
+  //    `latestVia` (a server-kept pointer to the newest related row) or
+  //    `copyOf: { via, column }` (a server-kept copy read through one), and
+  //    a table may declare `constraints` (`unique` with `unlessRelated`,
+  //    `no-overlap`, `related-open`, `related-index`).
+  // 1.184.0: additive (sc-11348) — OPTIONAL manifest field
+  //    `prefersFitToScreen` (dropping the widget at a page's top level turns
+  //    that section's Fit to screen on), and `useFitScreen()` with its
+  //    optional `fitScreen` host hint: the widget is a fit section's surface,
+  //    so it drops its own frame. Existing manifests and hosts read false.
+  version: "1.184.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -488,6 +488,19 @@ export function useFill() {
   return ctx.fill === true;
 }
 
+/**
+ * Returns `true` when this widget is the surface of a page section set to
+ * "Fit to screen": the section runs edge to edge across the app's content
+ * area and takes the rest of the screen. Drop the widget's own frame then —
+ * border, rounded corners, shadow — so it meets the edges cleanly; `useFill()`
+ * is `true` as well, and the host has already removed the outer margin.
+ * Defaults to `false`, and both hosts inject the same value.
+ */
+export function useFitScreen() {
+  const ctx = useWidgetContextOrThrow("useFitScreen");
+  return ctx.fitScreen === true;
+}
+
 /**
  * Returns the host's child-node renderer:
  *   { renderNode(node) }.
@@ -2706,7 +2719,8 @@ function isRetryableDomainStatus(status) {
   return status >= 500;
 }
 
-function toDatastoreError(err) {
+// Internal: shared with stats-hooks.js, not re-exported by the index.
+export function toDatastoreError(err) {
   // An already-mapped SDK error passes straight through. NOTE: the datastore
   // CLIENT exports its own class of the same name, so a client rejection does
   // NOT match here — it is handled by the envelope read below, which is exactly
@@ -4804,7 +4818,8 @@ export function useFilestoreUpload(options) {
       setUploading(true);
       setError(null);
       try {
-        const created = await filesRef.current.upload(form);
+        // sc-11244: names the row, so a visitor's grant for it can travel.
+        const created = await filesRef.current.upload(form, isRecordSpace ? { recordId: ownerId } : undefined);
         setLastUploaded(created || null);
         setUploading(false);
         return created;

package/dist/index.d.ts

@@ -228,8 +228,59 @@ export interface WidgetDatastoreTemplateColumn {
    * `MANY_TO_MANY` relation, whose links live outside the row.
    */
   immutable?: boolean;
+  /**
+   * ONE_TO_ONE / ONE_TO_MANY RELATION only, with `onDelete` left at
+   * `SET_NULL`: the server keeps this column pointing at the newest row of its
+   * target table whose relation column named here points back at this row.
+   * That relation must have `inheritAcl: true`, so only rows this row's
+   * readers can read are followed, and `immutable: true`, so a row never
+   * moves under another parent. Written only by the server; any value a
+   * client sends is ignored.
+   */
+  latestVia?: string;
+  /**
+   * The server keeps this column equal to `column` on the row the latest-row
+   * column `via` (on this table) points at: the same type, or text into
+   * text, cut to 140 characters in a STRING column. A copy of an encrypted
+   * column must be `encrypted` too, and a copy cannot `inheritAcl`. Written
+   * only by the server, so a list can show who wrote the newest row, and
+   * when, without trusting whoever wrote this one.
+   */
+  copyOf?: { via: string; column: string };
 }
 
+/**
+ * A rule the server checks on every write to the table, for every client. A
+ * refused write is a `CONSTRAINT_VIOLATION`.
+ */
+export type WidgetDatastoreTemplateConstraint =
+  | {
+      /** No two rows share these values; `unlessRelated` waives it for rows
+       *  whose related row has that yes/no column set. */
+      type: "unique";
+      config: {
+        columns: string[];
+        partitionColumns?: string[];
+        unlessRelated?: { relation: string; column: string };
+      };
+    }
+  | {
+      /** No two rows' `startColumn`..`endColumn` intervals overlap. */
+      type: "no-overlap";
+      config: { startColumn: string; endColumn: string; partitionColumns?: string[] };
+    }
+  | {
+      /** No row is added, changed or removed while its related row's
+       *  `closedColumn` is filled (a yes/no column: while it is yes). */
+      type: "related-open";
+      config: { relation: string; closedColumn: string };
+    }
+  | {
+      /** `column` must be a position (0-based) in the related row's list. */
+      type: "related-index";
+      config: { column: string; relation: string; listColumn: string };
+    };
+
 export interface WidgetDatastoreTemplateTable {
   /** Stable identifier within the template; appears in the created table name. */
   suffix: string;
@@ -267,6 +318,8 @@ export interface WidgetDatastoreTemplateTable {
   rows?: Array<
     Record<string, string | number | boolean | string[] | number[] | null>
   >;
+  /** Rules the server checks on every write, by column name. */
+  constraints?: WidgetDatastoreTemplateConstraint[];
 }
 
 /**
@@ -409,6 +462,13 @@ export interface WidgetManifest {
    * while the widget's page is closed so its menu badge stays live.
    */
   badgeCounter?: boolean;
+  /**
+   * Optional (sc-11348, default false). True when the widget owns the rest of
+   * the screen (a messenger, a map): dropping it at the top level of a page
+   * turns that section's "Fit to screen" on. Honour `useFill()` and
+   * `useFitScreen()` with it.
+   */
+  prefersFitToScreen?: boolean;
 }
 
 /**
@@ -733,6 +793,12 @@ export interface WidgetContext<TProps = unknown> {
    * Absent / `false` everywhere the host has not opted the widget into filling.
    */
   fill?: boolean;
+  /**
+   * sc-11348 — optional host hint backing `useFitScreen()`: `true` when this
+   * widget is the surface of a section set to Fit to screen (edge to edge,
+   * the rest of the screen). Absent / `false` everywhere else.
+   */
+  fitScreen?: boolean;
   /** Active end-user identity from the host-built context (camelCase, not a wire payload). `id` is null when anonymous. */
   user: {
     id: string | null;
@@ -1048,6 +1114,65 @@ export function useDatastoreFigure(
   options?: FigureOptions,
 ): FigureResult;
 
+export interface AggregateBucketSpec {
+  /** Bucket a system date column: `created_at` (default) or `updated_at`. */
+  groupBy?: "created_at" | "updated_at";
+  /** UTC days or ISO weeks (Monday); `day` by default. */
+  bucket?: "day" | "week";
+  /** ISO 8601. Defaults to 30 days (or 12 weeks) before `to`. */
+  from?: string;
+  /** ISO 8601. Defaults to now. At most 31 buckets in the range. */
+  to?: string;
+  /** A plain number column to add up per bucket. */
+  sumColumn?: string;
+  filter?: FigureOptions["filter"];
+}
+
+export interface AggregateGroupSpec {
+  /** A text, number, yes/no, date or user column. */
+  groupBy: string;
+  /** A plain number column to add up per group. */
+  sumColumn?: string;
+  filter?: FigureOptions["filter"];
+  /** Default: by value. `count:desc` with a `limit` ranks the biggest groups. */
+  order?: "count:desc" | "count:asc" | "sum:desc" | "sum:asc" | "group:asc" | "group:desc";
+  /** 1–1000. */
+  limit?: number;
+}
+
+export interface AggregateBucket {
+  /** The bucket's start date, `YYYY-MM-DD`. */
+  date: string;
+  count: number;
+  /** 0 unless `sumColumn` was given. */
+  sum: number;
+}
+
+export interface AggregateGroup {
+  /** The value; a user column's user id; "Uncategorized" for rows with none. */
+  group: string;
+  count: number;
+  /** 0 unless `sumColumn` was given. */
+  sum: number;
+}
+
+export interface AggregateResult {
+  /** By date: every bucket of the range, empty ones as `count: 0`. */
+  buckets: AggregateBucket[];
+  /** By a column: one entry per value. */
+  groups: AggregateGroup[];
+  loading: boolean;
+  fetching: boolean;
+  error: Error | null;
+  refetch(): Promise<void>;
+}
+
+/** Rows per day, week or column value over every row the viewer can read, counted on the server. */
+export function useDatastoreAggregate(
+  table: string | null | undefined,
+  spec?: AggregateBucketSpec | AggregateGroupSpec,
+): AggregateResult;
+
 export interface UserStatsQuery {
   days?: 7 | 30 | 90;
   /** A `useGroups()` row id: narrows user and invite figures to that group. */
@@ -1492,6 +1617,15 @@ export interface DatastoreSchemaColumn {
   display_column_id?: string | null;
   /** True when this column is the table's display/identification column. */
   is_identification?: boolean;
+  /**
+   * Set on a relation the server keeps at the newest related row; the id of
+   * the related table's relation back. Clients cannot write such a column.
+   */
+  latest_via_column_id?: string | null;
+  /** Set on a copy the server keeps: the latest-row column it reads through. */
+  copy_via_column_id?: string | null;
+  /** Set on a copy the server keeps: the related table's column it copies. */
+  copy_of_column_id?: string | null;
 }
 
 export interface DatastoreSchema {
@@ -2018,6 +2152,14 @@ export function useAnonymousAccount(): AnonymousAccountApi;
  */
 export function useFill(): boolean;
 
+/**
+ * sc-11348 — returns `true` when this widget is the surface of a page section
+ * set to "Fit to screen": it runs edge to edge and takes the rest of the
+ * screen, so drop your own frame (border, rounded corners, shadow).
+ * `useFill()` is `true` too. Defaults to `false`; the same on web and native.
+ */
+export function useFitScreen(): boolean;
+
 /**
  * The host-provided navigation surface. `goTo(pageId, params?)` navigates
  * to an internal app page; `goBack()` pops the stack. `goToStartPage()`

package/dist/index.js

@@ -80,6 +80,7 @@ export {
   useUserPhoto,
   useAnonymousAccount,
   useFill,
+  useFitScreen,
   useNavigation,
   useRouteParams,
   usePageBadge,
@@ -125,6 +126,7 @@ export {
 } from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
 export {
+  useDatastoreAggregate,
   useUserStats,
   useUserActivity,
   useActiveUsers,

package/dist/index.native.js

@@ -80,6 +80,7 @@ export {
   useUserPhoto,
   useAnonymousAccount,
   useFill,
+  useFitScreen,
   useNavigation,
   useRouteParams,
   usePageBadge,
@@ -123,6 +124,7 @@ export {
 } from "./audio.js";
 export { useDatastoreFigure } from "./datastore-figure.js";
 export {
+  useDatastoreAggregate,
   useUserStats,
   useUserActivity,
   useActiveUsers,

package/dist/manifest.cjs

@@ -331,6 +331,12 @@ function validateManifest(m) {
     "manifest.badgeCounter must be a boolean when present",
   );
 
+  pushIf(
+    errors,
+    manifest.prefersFitToScreen === undefined || typeof manifest.prefersFitToScreen === "boolean",
+    "manifest.prefersFitToScreen must be a boolean when present",
+  );
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/dist/manifest.js

@@ -377,6 +377,12 @@ function validateManifest(m) {
     "manifest.badgeCounter must be a boolean when present",
   );
 
+  pushIf(
+    errors,
+    manifest.prefersFitToScreen === undefined || typeof manifest.prefersFitToScreen === "boolean",
+    "manifest.prefersFitToScreen must be a boolean when present",
+  );
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/dist/stats-hooks.js

@@ -1,8 +1,16 @@
-// sc-10691 — read-only hooks for an app's user totals and user activity. Each
-// is one keyed read, stale-while-revalidate like useDatastoreQuery, and each
-// re-runs on the page's pull-to-refresh.
+// sc-10691 — read-only aggregate hooks: record counts per day, week or column
+// value, and an app's user totals. Both are one keyed read, stale-while-revalidate like
+// useDatastoreQuery, and both re-run on the page's pull-to-refresh.
 import { useCallback, useEffect, useRef, useState } from "react";
-import { toDirectoryError, useRefresh, useWidgetContextOrThrow } from "./hooks.js";
+import {
+  toDatastoreError,
+  toDirectoryError,
+  useRefresh,
+  useWidgetContextOrThrow,
+} from "./hooks.js";
+
+// The system date columns bucket by day or week; any other column groups by value.
+const DATE_GROUP_FIELDS = new Set(["created_at", "updated_at"]);
 
 const EMPTY = { identity: null, key: null, data: null, error: null };
 
@@ -66,6 +74,54 @@ function useKeyedRead(read, identity, key, mapError) {
   };
 }
 
+/**
+ * Counts (and optionally sums) a table's rows on the server, over every row
+ * the viewer may read — not just one page. `spec`: `{ groupBy, sumColumn?,
+ * filter? }` plus, by date (`groupBy` "created_at" | "updated_at"), `bucket?:
+ * "day" | "week", from?, to?`, or, by a column, `order?` ("count:desc",
+ * "count:asc", "sum:desc", "sum:asc", "group:asc", "group:desc") and `limit?`
+ * (1–1000). Returns `{ buckets, groups, loading, fetching, error, refetch }`:
+ * by date, `buckets` is `[{ date, count, sum }]` with every bucket of the range
+ * present (empty ones as 0); by a column, `groups` is `[{ group, count, sum }]`,
+ * a user column's `group` being the user id and rows with no value one
+ * "Uncategorized" group. A falsy `table` settles to nothing.
+ */
+export function useDatastoreAggregate(table, spec) {
+  const ctx = useWidgetContextOrThrow("useDatastoreAggregate");
+  if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
+    throw new Error("useDatastoreAggregate: host did not inject a datastore client");
+  }
+  const { groupBy = "created_at", bucket, from, to, sumColumn, filter, order, limit } = spec || {};
+  const byDate = DATE_GROUP_FIELDS.has(groupBy);
+  const key = table
+    ? serialize(byDate ? [groupBy, bucket, from, to, sumColumn, filter] : [groupBy, sumColumn, filter, order, limit])
+    : null;
+  const records = ctx.datastore.records;
+
+  const result = useKeyedRead(
+    async () => {
+      const rows = await records(table).aggregate(
+        byDate
+          ? { groupBy, bucket, from, to, sumField: sumColumn, filter }
+          : { groupBy, sumField: sumColumn, filter, order, limit },
+      );
+      return Array.isArray(rows) ? rows : [];
+    },
+    // The mode is part of the identity: switching it must not show the other's rows.
+    table ? `${table}|${byDate ? "date" : "column"}` : null,
+    key,
+    toDatastoreError,
+  );
+
+  const { data, ...state } = result;
+  const rows = data || [];
+  return {
+    ...state,
+    buckets: byDate ? rows.map((row) => ({ date: row.group, count: row.count, sum: row.sum })) : [],
+    groups: byDate ? [] : rows.map((row) => ({ group: row.group, count: row.count, sum: row.sum })),
+  };
+}
+
 /**
  * The app's user totals for its own admins — never a list of people.
  * `query`: `{ days?: 7 | 30 | 90, group_id? }`. Returns `{ stats, loading,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.223.0",
+  "version": "0.228.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

@@ -991,6 +991,24 @@ const HOOKS = [
     requiredContextSlice: ["fill"],
     scopes: null,
   },
+  {
+    name: "useFitScreen",
+    signature: "useFitScreen()",
+    description:
+      "Returns true when this widget is the surface of a page section set to " +
+      "\"Fit to screen\": the section runs edge to edge across the app's " +
+      "content area and takes the rest of the screen, so the widget should " +
+      "drop its own frame (border, rounded corners, shadow) and meet the " +
+      "edges cleanly. useFill() is true as well then, and the host has already " +
+      "removed the widget's outer margin. Defaults to false wherever the host " +
+      "has not fitted the widget, so calling it is always safe. The SAME value " +
+      "is injected by the web Player and the native export.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fitScreen"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -1397,7 +1415,8 @@ const HOOKS = [
       "create the row, call upload(file, { recordId: row.id }) — the per-call " +
       "recordId names the row the hook could not know at render — then write " +
       "the returned id into the FILE column with update(). A logged-out " +
-      "visitor cannot upload into a record space. For a file that belongs to " +
+      "visitor may do this only for a row they just created, within a few " +
+      "minutes, and never edits other rows' files. For a file that belongs to " +
       "no row: 'public' for content the app shows to anyone browsing, " +
       "'project' for signed-in workspace users only, 'personal' for a file " +
       "private to the uploading app user.",
@@ -1796,6 +1815,45 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["datastore.read:*"],
   },
+  // sc-10942 — rows per day or week, counted on the server over every row the
+  // viewer may read. Date columns only until column grouping is exact too.
+  {
+    name: "useDatastoreAggregate",
+    signature:
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+    description:
+      "Counts rows on the server over EVERY row the viewer can read, so it is " +
+      "exact past the 1000-row page a list read returns — never group " +
+      "useDatastoreQuery rows by hand. With `sumColumn` it also totals a plain " +
+      "number column. BY DATE (`groupBy` \"created_at\", the default, or " +
+      "\"updated_at\"): a SERIES for a chart, one entry per UTC day or ISO week " +
+      "(Monday) in `buckets`; `bucket` is \"day\" (default) or \"week\"; " +
+      "`from` / `to` are ISO dates (default: the 30 days, or 12 weeks, up to " +
+      "now), at most 31 buckets, empty ones as count 0 so a chart has no gaps. " +
+      "BY A COLUMN (any other `groupBy`: a text, number, yes/no, date or user " +
+      "column): one entry per value in `groups`. A USER column's `group` is the " +
+      "user id (resolve names with useDirectory({ ids })), so `order: \"count:desc\", " +
+      "limit: 10` ranks the ten people with the most rows. `order` is count, sum " +
+      "or group, then :asc or :desc (default: by value); `limit` is 1-1000. Rows " +
+      "with no value form one \"Uncategorized\" group; on a user column, leave " +
+      "them out with a `nempty:` filter. Encrypted, array, file and relation " +
+      "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
+      "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
+      "table until a bound table is known.",
+    returnShape: {
+      buckets:
+        "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
+      groups:
+        "Array<{ group, count, sum }>  // by a column; a USER column's group is the user id",
+      loading: "boolean",
+      fetching: "boolean",
+      error: "DatastoreError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:*"],
+  },
   {
     name: "useDatastoreSchema",
     signature: "useDatastoreSchema(tableId)",
@@ -3528,6 +3586,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
     default: false,
   },
+  prefersFitToScreen: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when the widget is built to own the rest of the screen: it scrolls its own content and keeps its controls in view, like a messenger, a map or a full-height board. Dropping the widget at the top level of a page in the Builder turns that section's \"Fit to screen\" setting on (the maker can switch it off, and it stays off), and the app-builder fits the section it plans the widget into. A fit section runs edge to edge across the content area and takes the rest of the screen; the widget learns it through useFill() and useFitScreen(), and the host gives it a box exactly the height left, which it scrolls inside (a widget without the field grows with its content there, and the page scrolls). Set it only for a widget that honours useFill() and scrolls inside the height it is given; leave it false (or omit) for everything else.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -3559,7 +3624,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: 8 tables, 24 columns per 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 8 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, 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` 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.",
+      "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: 8 tables, 24 columns per 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 8 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, 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` 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.",
   },
   translations: {
     type: "object",
@@ -3603,6 +3668,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: {},
   },
+  // sc-11348 — optional host hint backing useFitScreen(): the widget is the
+  // surface of a section set to Fit to screen, so it drops its own frame.
+  fitScreen: {
+    description:
+      "Optional host layout hint (boolean). True when this widget is the " +
+      "surface of a page section set to Fit to screen: edge to edge, the rest " +
+      "of the screen. Backs useFitScreen(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
     description:
       "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. email is null for an account created without one. Not a data-client.",
@@ -5878,7 +5953,28 @@ const CONTRACT = deepFreeze({
   //    `{ colors, onImage }`: the theme colours as they read over the picture.
   // 1.179.0: additive (sc-11253) — `useNavigation().goToStartPage()` opens
   //    the signed-in user's own start page on both hosts.
-  version: "1.179.0",
+  // 1.180.0: additive (sc-11244) — a logged-out visitor may attach files to
+  //    the row they just created, for a few minutes: the host carries a grant
+  //    from the create to that row's upload and update. Widget code is the
+  //    same create → upload → update flow.
+  // 1.181.0: additive (sc-10942) — `useDatastoreAggregate(tableId, spec)`
+  //    counts rows per day or week on the server (date columns only), through
+  //    `records(t).aggregate`'s new bucket/from/to.
+  // 1.182.0: additive (sc-10737) — `useDatastoreAggregate` groups by an
+  //    ordinary column too, into `groups` ([{ group, count, sum }]), with
+  //    `order` and `limit` for a top N; counted on the server over every
+  //    readable row. A user column groups by user id.
+  // 1.183.0: additive (sc-10766) — a datastoreTemplate column may declare
+  //    `latestVia` (a server-kept pointer to the newest related row) or
+  //    `copyOf: { via, column }` (a server-kept copy read through one), and
+  //    a table may declare `constraints` (`unique` with `unlessRelated`,
+  //    `no-overlap`, `related-open`, `related-index`).
+  // 1.184.0: additive (sc-11348) — OPTIONAL manifest field
+  //    `prefersFitToScreen` (dropping the widget at a page's top level turns
+  //    that section's Fit to screen on), and `useFitScreen()` with its
+  //    optional `fitScreen` host hint: the widget is a fit section's surface,
+  //    so it drops its own frame. Existing manifests and hosts read false.
+  version: "1.184.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,