@colixsystems/widget-sdk 0.172.0 → 0.174.0

package/README.md

@@ -25,7 +25,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
 | **CORE** | `useWidgetRoute(initial)` | `[state, setState]` | `ctx.widgetRoute` — no scope. Where YOUR WIDGET is, persisted by the host so it survives a reload and travels in a shared link (the `w_<instanceId>` query key on web, the screen's route params natively): the folder a browser has opened, a wizard step, a selected tab, a list's sort and search. `useState` semantics over an object — writes MERGE, `null` clears a key back to its `initial`, and `initial` is read once. Values are scalars or flat arrays of scalars, size- and length-capped; anything else is not stored. NOT history (Back still leaves the page, on both platforms). Degrades to component state on the Studio canvas. |
-| **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. |
+| **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope. The hook IS the emitter: `const emitSlot = useWidgetEvent("slotChosen")`, then `emitSlot(payload)`. Never destructure the result — there is no `emit` member. A sibling's input reads the payload, and a page action the author binds to the event (Run action, Navigate) runs with it — fired from one control, only that control runs it. |
 | **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
@@ -44,7 +44,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **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, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
-| **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, fetching, error, refetch }` — a refetch of the same record keeps `data` while `fetching` | `records(table).get` — `datastore.read:<table>` |
+| **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>` |
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
@@ -73,7 +73,38 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.172.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.174.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.174.0 (contract 1.135.0)
+
+**Show a row's Edit / Delete only to someone allowed to use it: `includeCapabilities`.** A list gated on `useCanWrite(tableId)` offered Edit and Delete on every row, because the table-level answer only says whether the user may *create*. On a table where each user owns the rows they created, that is true for every signed-in user, so the server refused every edit and delete on someone else's row. Ask the read for each row's own answer instead:
+
+```jsx
+const { data: rows, refetch } = useDatastoreQuery(tableId, { limit: 50, includeCapabilities: true });
+const { delete: remove } = useDatastoreMutation(tableId);
+// inside rows.map((row) => …)
+{row._capabilities?.can_delete && (
+  <Pressable onPress={() => remove(row.id).then(refetch)}><Text>Delete</Text></Pressable>
+)}
+```
+
+Every row arrives with `_capabilities: { can_read, can_write, can_delete, can_grant }`, the same answer `update` / `delete` enforce, computed for the whole page in one lookup. `useDatastoreRecord(tableId, recordId, { includeCapabilities: true })` does the same for one record. Without the option, rows are unchanged. The new linter warning `row-action-not-gated` flags a widget that calls `update` or `delete` with no per-row check (`_capabilities`, or `useCanWrite(tableId, { recordId })` on a single-record page).
+
+### What's new in 0.173.1 (contract 1.134.1)
+
+**An event your widget fires can run a page action, from the one control that fires it.** The author (or Mason) can bind Run action or Navigate to any event your manifest declares, and it runs when `useWidgetEvent` fires it. Fire the event from one control and only that control runs the action:
+
+```jsx
+// manifest: events: [{ name: "onBookPressed", payloadSchema: { classId: { type: "string" } } }]
+const emitBook = useWidgetEvent("onBookPressed");
+<Button title="Book" onPress={() => emitBook({ classId })} />
+```
+
+Never declare your own event as `onPress`: an `onPress` binding makes the whole widget one tap target, so a tap anywhere on it runs the action. Documentation only — both hosts already dispatched a named event's binding.
+
+### What's new in 0.173.0 (contract 1.134.0)
+
+**A `datastoreTemplate` RELATION may name any table in the template.** The installer now creates every table before any column, so `targetSuffix` may point at a table declared later in `tables`, and two tables may relate to each other both ways. A suffix no table in the template has is still rejected at publish. No change is needed to an existing template.
 
 ### What's new in 0.172.0 (contract 1.133.0)
 
@@ -2152,7 +2183,7 @@ export default function OpenTasks({ tableId, titleField, statusField }) {
 }
 ```
 
-`useCanWrite` answers "is this table's ACL open to me" — it is a FLOOR, not the whole rule. A widget whose own logic is more specific ("only the assignee may edit this row") still hand-checks that in addition, typically with `options.recordId` passed to a second `useCanWrite` call or a plain `user.id === record[assigneeField]` comparison.
+`useCanWrite(tableId)` answers "may I create a row here". It says nothing about changing an EXISTING row: gate a list's Edit / Delete on each row's `_capabilities` (read with `includeCapabilities: true`, see *What's new in 0.174.0*), and a single-record page on `useCanWrite(tableId, { recordId })` or `useDatastoreRecord(…, { includeCapabilities: true })`. Never call `useCanWrite` with a `recordId` per list row — that is one request per row. Either answer is a FLOOR, not the whole rule: a widget whose own logic is more specific ("only the assignee may edit this row") still hand-checks that in addition (`user.id === record[assigneeField]`).
 
 ## Cross-platform widgets (single-file vs split)
 
@@ -2223,6 +2254,8 @@ Pass `--manifest` to enable `style-field-unread` and the three editability rules
 
 `flex-basis-percent` flags a literal percentage `flexBasis` (sc-7274) — `"100%"`, `"50%"`, or the ternary a responsive cell writes. `flex-basis` sizes the MAIN axis, so in a column parent it asks for the parent's HEIGHT: under an ancestor that makes that height definite (a Grid cell stretches its child on the web Player) the child fills the container and, since a `View` never shrinks, overflows over everything below it. Say full-width with `width: "100%"` — correct in a column AND in a wrap row — and keep a NUMBER for a wrap threshold. A warning, because the percentage is right in a row and a text scan cannot see the parent.
 
+`row-action-not-gated` flags a widget that calls `update` or `delete` from `useDatastoreMutation` without a per-row permission check (sc-9132): no `_capabilities` read and no `useCanWrite(tableId, { recordId })`. The table-level `useCanWrite(tableId)` only answers "may create", so a list gated on it shows Edit / Delete on rows the server will refuse. A warning.
+
 `no-html-in-content` flags an HTML tag inside a **string** (sc-6970) — `"<strong>"`, `"<br>"`, `"<p>…</p>"`. There is no HTML renderer on either host, so the tag reaches the reader as literal text; author formatted text with `<MarkdownInput>` and render it with `<RichText>` instead. Only string and template content is scanned, so your own `<View>` / `<Text>` JSX can never trip it. A warning for a human author, blocking for the AI widget agent.
 
 ## Local dev loop (`appstudio-widget dev`)

package/dist/contract.cjs

@@ -1018,11 +1018,14 @@ const HOOKS = [
   },
   {
     name: "useDatastoreRecord",
-    signature: "useDatastoreRecord(tableId, recordId)",
+    signature: "useDatastoreRecord(tableId, recordId, options)",
+    optionalArgs: ["options"],
     description:
       "Reads one row. Re-reading the same record (refetch, pull-to-refresh) " +
       "keeps it in `data` with loading false while `fetching` is true; a " +
-      "different table or record id resets to loading.",
+      "different table or record id resets to loading. " +
+      "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
+      "for useDatastoreQuery.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1371,7 +1374,12 @@ const HOOKS = [
       "until the first result for the bound table lands; a changed query on " +
       "that table, refetch() and pull-to-refresh keep the rows already in " +
       "`data` with loading false, while `fetching` is true. Binding a " +
-      "different table resets to loading. Show a spinner on `loading` only.",
+      "different table resets to loading. Show a spinner on `loading` only. " +
+      "Pass `includeCapabilities: true` in options to stamp each row with " +
+      "`_capabilities` { can_read, can_write, can_delete, can_grant } — what " +
+      "the signed-in user may do to THAT row, the answer update/delete " +
+      "enforce, computed for the whole page in one lookup. Gate a row's " +
+      "Edit on `row._capabilities?.can_write` and Delete on `can_delete`.",
     returnShape: {
       data: "Record[]",
       loading: "boolean",
@@ -1558,6 +1566,12 @@ const HOOKS = [
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
+    description:
+      "Fires one of the events the manifest declares. The page wires it two " +
+      "ways: a sibling widget's input reads the payload, and an author-bound " +
+      "page action (Run action, Navigate) runs with it. Fire a named event " +
+      "from ONE control to have only that control run the action; an onPress " +
+      "binding instead makes the whole widget the tap target.",
     // sc-4753 — the hook IS the emitter, so its return is declared as a bare
     // callable. Naming an `emit` member here made every derived surface tell
     // authors to destructure a function, which yields undefined at run time.
@@ -1880,7 +1894,8 @@ const HOOKS = [
       "domain-specific write rules: a widget whose rule is more specific than the table ACL (e.g. 'only the assigned user may edit this row') must " +
       "still hand-check that in addition to useCanWrite (user.id === record[assigneeField]). It only answers 'signed in AND permitted' — it does " +
       "NOT distinguish 'not signed in' from 'signed in but forbidden' (both resolve canWrite:false); pair it with useUser() when the UI needs to " +
-      "tell those apart. myPermissions is a newer client method: a host that has not injected it is NOT a hard error — this hook collapses to " +
+      "tell those apart. For a LIST, gate each row's edit/delete on useDatastoreQuery's `includeCapabilities` answer instead — a " +
+      "{ recordId } check per row is one request per row, and the table-level answer only says whether they may CREATE. myPermissions is a newer client method: a host that has not injected it is NOT a hard error — this hook collapses to " +
       "{ canWrite: false, loading: false, error: null, refetch: async () => undefined } rather than throwing. Same collapse when tableId is falsy.",
     returnShape: {
       canWrite: "boolean",
@@ -2633,7 +2648,10 @@ const MANIFEST_SCHEMA = {
       "{ type, label? } — the SAME shape as propertySchema, NOT JSON Schema — " +
       "where type is one of string, number, boolean, object, array. The payload reaches " +
       "any sibling widget on the page whose inputs entry the page author wired " +
-      "to this event.",
+      "to this event. An event can also run a page action the author binds to " +
+      "it (Run action, Navigate): fired from one control with useWidgetEvent, " +
+      "only that control runs the action. Never declare it as onPress, which " +
+      "the host binds as a tap target over the whole widget.",
     default: [],
   },
   inputs: {
@@ -2652,7 +2670,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` (must be declared earlier in the array). 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.",
+      "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.",
   },
   translations: {
     type: "object",
@@ -4661,7 +4679,12 @@ const CONTRACT = deepFreeze({
   // 1.133.0: additive (sc-9002) — `ListHeader` (column labels on `ListRow`'s frame);
   //    a `ListRow`'s lone `View` child spans the row; a selected row's bar
   //    no longer shifts its content. Other rows render as before.
-  version: "1.133.0",
+  // 1.134.1: docs (sc-9122) — an emitted event can run a bound action.
+  // 1.135.0: additive (sc-9132) — `includeCapabilities` on useDatastoreQuery
+  //    options and a new `options` arg on useDatastoreRecord stamp each row
+  //    with `_capabilities`, so a widget shows Edit/Delete only on rows the
+  //    user may change. New linter warning `row-action-not-gated`.
+  version: "1.135.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1018,11 +1018,14 @@ const HOOKS = [
   },
   {
     name: "useDatastoreRecord",
-    signature: "useDatastoreRecord(tableId, recordId)",
+    signature: "useDatastoreRecord(tableId, recordId, options)",
+    optionalArgs: ["options"],
     description:
       "Reads one row. Re-reading the same record (refetch, pull-to-refresh) " +
       "keeps it in `data` with loading false while `fetching` is true; a " +
-      "different table or record id resets to loading.",
+      "different table or record id resets to loading. " +
+      "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
+      "for useDatastoreQuery.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1371,7 +1374,12 @@ const HOOKS = [
       "until the first result for the bound table lands; a changed query on " +
       "that table, refetch() and pull-to-refresh keep the rows already in " +
       "`data` with loading false, while `fetching` is true. Binding a " +
-      "different table resets to loading. Show a spinner on `loading` only.",
+      "different table resets to loading. Show a spinner on `loading` only. " +
+      "Pass `includeCapabilities: true` in options to stamp each row with " +
+      "`_capabilities` { can_read, can_write, can_delete, can_grant } — what " +
+      "the signed-in user may do to THAT row, the answer update/delete " +
+      "enforce, computed for the whole page in one lookup. Gate a row's " +
+      "Edit on `row._capabilities?.can_write` and Delete on `can_delete`.",
     returnShape: {
       data: "Record[]",
       loading: "boolean",
@@ -1558,6 +1566,12 @@ const HOOKS = [
   {
     name: "useWidgetEvent",
     signature: "useWidgetEvent(eventName)",
+    description:
+      "Fires one of the events the manifest declares. The page wires it two " +
+      "ways: a sibling widget's input reads the payload, and an author-bound " +
+      "page action (Run action, Navigate) runs with it. Fire a named event " +
+      "from ONE control to have only that control run the action; an onPress " +
+      "binding instead makes the whole widget the tap target.",
     // sc-4753 — the hook IS the emitter, so its return is declared as a bare
     // callable. Naming an `emit` member here made every derived surface tell
     // authors to destructure a function, which yields undefined at run time.
@@ -1880,7 +1894,8 @@ const HOOKS = [
       "domain-specific write rules: a widget whose rule is more specific than the table ACL (e.g. 'only the assigned user may edit this row') must " +
       "still hand-check that in addition to useCanWrite (user.id === record[assigneeField]). It only answers 'signed in AND permitted' — it does " +
       "NOT distinguish 'not signed in' from 'signed in but forbidden' (both resolve canWrite:false); pair it with useUser() when the UI needs to " +
-      "tell those apart. myPermissions is a newer client method: a host that has not injected it is NOT a hard error — this hook collapses to " +
+      "tell those apart. For a LIST, gate each row's edit/delete on useDatastoreQuery's `includeCapabilities` answer instead — a " +
+      "{ recordId } check per row is one request per row, and the table-level answer only says whether they may CREATE. myPermissions is a newer client method: a host that has not injected it is NOT a hard error — this hook collapses to " +
       "{ canWrite: false, loading: false, error: null, refetch: async () => undefined } rather than throwing. Same collapse when tableId is falsy.",
     returnShape: {
       canWrite: "boolean",
@@ -2629,7 +2644,10 @@ const MANIFEST_SCHEMA = {
       "{ type, label? } — the SAME shape as propertySchema, NOT JSON Schema — " +
       "where type is one of string, number, boolean, object, array. The payload reaches " +
       "any sibling widget on the page whose inputs entry the page author wired " +
-      "to this event.",
+      "to this event. An event can also run a page action the author binds to " +
+      "it (Run action, Navigate): fired from one control with useWidgetEvent, " +
+      "only that control runs the action. Never declare it as onPress, which " +
+      "the host binds as a tap target over the whole widget.",
     default: [],
   },
   inputs: {
@@ -2648,7 +2666,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` (must be declared earlier in the array). 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.",
+      "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.",
   },
   translations: {
     type: "object",
@@ -4657,7 +4675,12 @@ const CONTRACT = deepFreeze({
   // 1.133.0: additive (sc-9002) — `ListHeader` (column labels on `ListRow`'s frame);
   //    a `ListRow`'s lone `View` child spans the row; a selected row's bar
   //    no longer shifts its content. Other rows render as before.
-  version: "1.133.0",
+  // 1.134.1: docs (sc-9122) — an emitted event can run a bound action.
+  // 1.135.0: additive (sc-9132) — `includeCapabilities` on useDatastoreQuery
+  //    options and a new `options` arg on useDatastoreRecord stamp each row
+  //    with `_capabilities`, so a widget shows Edit/Delete only on rows the
+  //    user may change. New linter warning `row-action-not-gated`.
+  version: "1.135.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2185,7 +2185,8 @@ function serializeQuery(query) {
 }
 
 const queryResultKey = (table, queryKey) => JSON.stringify([table, queryKey]);
-const recordResultKey = (table, recordId) => JSON.stringify([table, recordId]);
+const recordResultKey = (table, recordId, includeCapabilities = false) =>
+  JSON.stringify([table, recordId, includeCapabilities]);
 
 /**
  * Stateful datastore query hook. Returns { data, loading, fetching, error,
@@ -2202,6 +2203,10 @@ const recordResultKey = (table, recordId) => JSON.stringify([table, recordId]);
  * re-fetch when [table, JSON.stringify(query)] changes. `refetch` re-runs the
  * same call on demand.
  *
+ * sc-9132 — `query.includeCapabilities: true` stamps each row with
+ * `_capabilities` ({ can_read, can_write, can_delete, can_grant }), computed
+ * for the whole page in one server lookup. Gate a row's Edit / Delete on it.
+ *
  * sc-8595 — stale-while-revalidate. `loading` is true only until the first
  * result for the bound TABLE lands. A changed query on that table, `refetch()`
  * and a page pull-to-refresh keep the rows already in `data` on screen with
@@ -2362,8 +2367,12 @@ export function useDatastoreQuery(table, query) {
  * fetching: false, error: null, refetch } so the widget can render its empty state
  * without throwing. A 404 surfaces as a DatastoreError with
  * `code: "NOT_FOUND"`.
+ *
+ * sc-9132 — pass `{ includeCapabilities: true }` to have the row carry
+ * `_capabilities` ({ can_read, can_write, can_delete, can_grant }): what the
+ * signed-in user may do to THIS record, the same answer update/delete enforce.
  */
-export function useDatastoreRecord(table, recordId) {
+export function useDatastoreRecord(table, recordId, options) {
   const ctx = useWidgetContextOrThrow("useDatastoreRecord");
   if (!ctx.datastore || typeof ctx.datastore.records !== "function") {
     throw new Error(
@@ -2378,11 +2387,14 @@ export function useDatastoreRecord(table, recordId) {
   // Same ref discipline as useDatastoreQuery — `ctx` is a fresh object
   // identity on every host render, so we hold the live inputs in refs
   // to keep `refetch` a stable callback.
+  const includeCapabilities = options?.includeCapabilities === true;
   const tableRef = useRef(table);
   const recordIdRef = useRef(recordId);
+  const includeCapabilitiesRef = useRef(includeCapabilities);
   const recordsRef = useRef(ctx.datastore.records);
   tableRef.current = table;
   recordIdRef.current = recordId;
+  includeCapabilitiesRef.current = includeCapabilities;
   recordsRef.current = ctx.datastore.records;
 
   const runRef = useRef(0);
@@ -2396,11 +2408,13 @@ export function useDatastoreRecord(table, recordId) {
       setSettled(NO_RECORD_RESULT);
       return;
     }
-    const key = recordResultKey(t, id);
+    const key = recordResultKey(t, id, includeCapabilitiesRef.current);
     setInFlight(true);
     try {
       const ns = recordsRef.current(t);
-      const row = await ns.get(id);
+      const row = includeCapabilitiesRef.current
+        ? await ns.get(id, { includeCapabilities: true })
+        : await ns.get(id);
       if (runRef.current !== myRun) return;
       setSettled({ key, data: row || null, error: null, loaded: true });
       setInFlight(false);
@@ -2419,7 +2433,7 @@ export function useDatastoreRecord(table, recordId) {
   useEffect(() => {
     doFetch();
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [table, recordId]);
+  }, [table, recordId, includeCapabilities]);
 
   const refetch = useCallback(async () => {
     await doFetch();
@@ -2428,7 +2442,8 @@ export function useDatastoreRecord(table, recordId) {
   // sc-1179 — auto-subscribe to the page-level refresh tick.
   useRefresh(refetch);
 
-  const currentKey = table && recordId ? recordResultKey(table, recordId) : null;
+  const currentKey =
+    table && recordId ? recordResultKey(table, recordId, includeCapabilities) : null;
   const busy = currentKey !== null && (settled.key !== currentKey || inFlight);
   const hasRecord = currentKey !== null && settled.key === currentKey && settled.loaded;
   return {

package/dist/index.d.ts

@@ -160,9 +160,10 @@ export interface WidgetInputDescriptor {
  *   - At most 24 columns per table. Same reason.
  *
  * RELATION columns reference siblings within the same template via
- * `targetSuffix` — that suffix MUST belong to a table declared earlier
- * in the array. There is intentionally no way to reference a table
- * outside the widget's own template.
+ * `targetSuffix` — that suffix MUST belong to a table in the same array,
+ * declared anywhere in it; tables may relate to each other both ways.
+ * There is intentionally no way to reference a table outside the
+ * widget's own template.
  */
 export interface WidgetDatastoreTemplateColumn {
   name: string;
@@ -821,6 +822,23 @@ export interface Query {
   sort?: Array<{ field: string; dir: "asc" | "desc" }>;
   limit?: number;
   cursor?: string;
+  /**
+   * Stamp each row with `_capabilities` — what the signed-in user may do to
+   * that row. Gate a row's Edit / Delete on it.
+   */
+  includeCapabilities?: boolean;
+}
+
+/**
+ * What the signed-in user may do to one record: the same answer the update /
+ * delete endpoints enforce. Present as `row._capabilities` only when the read
+ * passed `includeCapabilities: true`.
+ */
+export interface RecordCapabilities {
+  can_read: boolean;
+  can_write: boolean;
+  can_delete: boolean;
+  can_grant: boolean;
 }
 
 export interface QueryResult<T> {
@@ -896,6 +914,13 @@ export interface DirectoryResult {
  */
 export function useDirectory(query?: DirectoryQuery): DirectoryResult;
 
+/**
+ * The emitter for an event the manifest declares. A sibling's wired input
+ * reads the payload, and a page action the author binds to the event (Run
+ * action, Navigate) runs with it — fired from one control, only that control
+ * runs it. Never declare an event named `onPress`: that binding makes the
+ * whole widget one tap target.
+ */
 export function useWidgetEvent(name: string): (payload?: unknown) => void;
 
 /**
@@ -1057,6 +1082,7 @@ export function useWidgetStyle(): Record<string, unknown>;
 export function useDatastoreRecord(
   tableId: string | null | undefined,
   recordId: string | null | undefined,
+  options?: { includeCapabilities?: boolean },
 ): {
   data: unknown | null;
   loading: boolean;

package/dist/linter.cjs

@@ -1189,6 +1189,45 @@ function _handRolledWriteGateRules(source) {
   ];
 }
 
+// sc-9132 — soft warning: a row's Edit / Delete shown whatever that row's
+// permissions say. Table-level `useCanWrite(tableId)` only answers "may
+// create", which on a creator-owned table is true for every signed-in user,
+// so every row offered actions the server then refused.
+function _rowActionGatingRules(source) {
+  const code = _stripNonCode(source);
+  const call = _rowMutationCall(code);
+  if (!call) return [];
+  if (/\b_capabilities\b/.test(code)) return [];
+  if (/\buseCanWrite\s*\([^)]*\brecordId\b/.test(code)) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "row-action-not-gated",
+      severity: "warning",
+      label:
+        `edits or deletes rows without checking that row's permission - read ` +
+        `with { includeCapabilities: true } and show Edit/Delete only when ` +
+        `row._capabilities.can_write / can_delete is true.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
+// The useDatastoreMutation() call whose update or delete the widget uses,
+// either as `m.update(` / `m.delete(` or destructured `{ update, delete }`.
+function _rowMutationCall(code) {
+  const hookCall = /(?:\{([^}]*)\}|\b(\w+))\s*=\s*useDatastoreMutation\s*\(/g;
+  for (const match of code.matchAll(hookCall)) {
+    const [, destructured, name] = match;
+    const usesRowVerb = destructured
+      ? /\b(update|delete)\b/.test(destructured)
+      : new RegExp(`\\b${name}\\s*\\.\\s*(update|delete)\\s*\\(`).test(code);
+    if (usesRowVerb) return match;
+  }
+  return null;
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   const code = _stripNonCode(source, { keepStrings: true });
@@ -1839,6 +1878,7 @@ function lintSource(source, options) {
   // sc-5206 — soft warnings steering a widget toward the two new hooks.
   findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
   findings.push(..._handRolledWriteGateRules(source));
+  findings.push(..._rowActionGatingRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -1210,6 +1210,45 @@ function _handRolledWriteGateRules(source) {
   ];
 }
 
+// sc-9132 — soft warning: a row's Edit / Delete shown whatever that row's
+// permissions say. Table-level `useCanWrite(tableId)` only answers "may
+// create", which on a creator-owned table is true for every signed-in user,
+// so every row offered actions the server then refused.
+function _rowActionGatingRules(source) {
+  const code = _stripNonCode(source);
+  const call = _rowMutationCall(code);
+  if (!call) return [];
+  if (/\b_capabilities\b/.test(code)) return [];
+  if (/\buseCanWrite\s*\([^)]*\brecordId\b/.test(code)) return [];
+  const line = code.slice(0, call.index).split(/\r?\n/).length;
+  return [
+    {
+      rule: "row-action-not-gated",
+      severity: "warning",
+      label:
+        `edits or deletes rows without checking that row's permission - read ` +
+        `with { includeCapabilities: true } and show Edit/Delete only when ` +
+        `row._capabilities.can_write / can_delete is true.`,
+      line,
+      snippet: (source.split(/\r?\n/)[line - 1] || "").trim().slice(0, 200),
+    },
+  ];
+}
+
+// The useDatastoreMutation() call whose update or delete the widget uses,
+// either as `m.update(` / `m.delete(` or destructured `{ update, delete }`.
+function _rowMutationCall(code) {
+  const hookCall = /(?:\{([^}]*)\}|\b(\w+))\s*=\s*useDatastoreMutation\s*\(/g;
+  for (const match of code.matchAll(hookCall)) {
+    const [, destructured, name] = match;
+    const usesRowVerb = destructured
+      ? /\b(update|delete)\b/.test(destructured)
+      : new RegExp(`\\b${name}\\s*\\.\\s*(update|delete)\\s*\\(`).test(code);
+    if (usesRowVerb) return match;
+  }
+  return null;
+}
+
 function _imagePercentHeightRules(source) {
   const findings = [];
   // Comments are blanked (string contents kept) so a commented-out example —
@@ -1915,6 +1954,7 @@ export function lintSource(source, options) {
   // sc-5206 — soft warnings steering a widget toward the two new hooks.
   findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
   findings.push(..._handRolledWriteGateRules(source));
+  findings.push(..._rowActionGatingRules(source));
   // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
   // line-by-line scan so banned-identifier findings stay first in the
   // output.

package/package.json

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