@colixsystems/widget-sdk 0.173.1 → 0.175.0

package/README.md

@@ -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. |
@@ -60,7 +60,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
-| **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: folderId) | `{ exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.exportPdf` — `files.write:*`. `exportToPdf(html, { fileName?, folderId? })` renders the HTML to a PDF server-side and saves it as a file (`application/pdf`); same server-side renderer on web + native. |
+| **FILESTORE** (`ctx.filestore`) | `usePdfExport({ spaceType, folderId })` (optional: spaceType, folderId) | `{ openPdf, opening, canOpenPdf, exportToPdf, exporting, error, lastExported }` | `ctx.filestore.files.renderPdf` + `ctx.device.pdfViewer`, `ctx.filestore.files.exportPdf` — `files.write:*`. `openPdf(html, { fileName? })` renders the HTML to a PDF server-side and OPENS it (web: PDF tab; native: print / share sheet) without saving. `exportToPdf(html, { fileName?, folderId? })` renders it and saves it as a file (`application/pdf`). Same server-side renderer on web + native. |
 | **PAYMENTS** (`ctx.payments`) | `usePayments()` | `{ requestPayment, getPayment }` | `ctx.payments.*` — `payments.charge:appUser`. Rejects with `PaymentError { code, message, retryable }`; when `retryable` is `false` show `message` and drop the retry. Charges are accepted ONLY in the currency the workspace sells in — omit `currency` and the platform applies it (a disagreeing literal is a publish-blocking `payment-currency` finding). |
 | **NOTIFICATIONS** (`ctx.notifications`) | `useSendNotification()` | `{ send, sending, error }` | `ctx.notifications.send` — `notifications.send:appUser`. `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace; call from an event handler (never render); rejects with `NotificationError`. |
 | **IDENTIFICATION** (`ctx.identification`) | `useIdentification({ provider, purpose, pollIntervalMs })` (optional: every key, and the whole argument) | `{ available, status, qr, autoStartToken, message, identity, identificationId, start, refresh, cancel, reset, … }` | `ctx.identification.*` — no scope (the visitor is deliberately NOT signed in). Gate the UI on `available`; `start()` opens the order and the hook polls to completion. `identity` carries `personal_number_masked` + a stable `subject_hash` — never a raw personal number. |
@@ -73,7 +73,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.173.1` — 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.175.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.175.0 (contract 1.136.0)
+
+**Open a PDF for the user to view, print or share, without saving it (sc-9135).** `usePdfExport()` gains `openPdf(html, { fileName? })`, `opening` and `canOpenPdf`. The HTML is rendered server-side by the same headless-Chromium pipeline as `exportToPdf`, and the host opens the result: a new browser tab with the PDF viewer on the web Player, and the OS print and share sheet in the native export (`expo-print`). Nothing is stored, so a widget that only opens PDFs calls `usePdfExport()` with no arguments. Call `openPdf` directly from the press handler, because the web host opens its tab inside that press and a tab opened after an `await` is refused by the popup blocker. `canOpenPdf` is false on a host with no PDF viewer, where `openPdf` rejects with `err.code` `UNSUPPORTED`. The wire errors arrive on `err.status`: 401 not signed in, 413 over the size cap, 429 too many renders, 503 renderer busy. The HTML runs no scripts and loads only `https:` / `data:` images and `https:` fonts. On native, closing the print sheet resolves `openPdf` like closing the web tab does. Needs `@colixsystems/filestore-client@0.11.0` (`files.renderPdf`). The host slice is the new `device.pdfViewer`.
+
+**Breaking for authors: `createObjectURL` is now a banned API** (lint rule `no-createobjecturl`). Widgets used it to open a hand-built plain-text blob as a stand-in "print version": it only works in a browser, and on the web it opens widget-built bytes on the host's origin. A widget version that calls it fails lint at submission; versions already published keep running. Open a generated document with `openPdf`, upload a file with `useFilestoreUpload`, and preview a picked photo from the `uri` `useCamera` returns.
+
+### 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)
 
@@ -2168,7 +2189,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)
 
@@ -2239,6 +2260,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",
@@ -1176,9 +1179,22 @@ const HOOKS = [
   {
     name: "usePdfExport",
     signature: "usePdfExport({ spaceType, folderId })",
-    optionalArgs: ["folderId"],
-    description:
-      "Render an HTML string to a PDF server-side and SAVE it as a file in " +
+    optionalArgs: ["spaceType", "folderId"],
+    description:
+      "Render an HTML string to a PDF server-side, then either OPEN it or SAVE " +
+      "it. `openPdf(html, { fileName? })` is THE way to give the user a PDF " +
+      "to view, print, download or share: it renders the HTML and opens the " +
+      "result — the browser's PDF viewer in a new tab on the web Player, the " +
+      "OS print / share sheet in the native export — and SAVES NOTHING, so " +
+      "a widget that only opens PDFs calls `usePdfExport()` with no " +
+      "arguments (`spaceType` names where exportToPdf saves). Call " +
+      "it straight from the press handler (the web tab opens before the " +
+      "render so popup blockers allow it). It resolves once the document is " +
+      "handed to the viewer and rejects with `err.code` UNSUPPORTED when the " +
+      "host has no PDF viewer (check `canOpenPdf`), or the wire error " +
+      "(`err.status` 401 not signed in, 413 over the size cap, 429 too many " +
+      "renders, 503 renderer busy — try again). The rest of this entry is " +
+      "the SAVE path. `exportToPdf` renders and SAVES it as a file in " +
       "the end-user's Filestore space. The widget passes the SPACE " +
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
@@ -1191,6 +1207,9 @@ const HOOKS = [
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
       "Player and the native export, so no browser-only PDF library is used.",
     returnShape: {
+      openPdf: "(html, { fileName? }) => Promise<void>",
+      opening: "boolean",
+      canOpenPdf: "boolean",
       exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
       exporting: "boolean",
       error: "Error | null",
@@ -1371,7 +1390,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",
@@ -1886,7 +1910,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",
@@ -2949,10 +2974,14 @@ const WIDGET_CONTEXT_SHAPE = {
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
-      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor() and useBarcodeScanner(). The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas and BarcodeDetector; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator and expo-camera. " +
+      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
+      "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
+      "cache and hands them to the OS print sheet. " +
       "imageEditor.edit applies resize / crop / rotate / flip in order and rejects with an ImageEditorError " +
       "(.code UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | INTERNAL). " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
@@ -2980,6 +3009,7 @@ const WIDGET_CONTEXT_SHAPE = {
       camera: "object",
       imageEditor: "object",
       barcode: "object",
+      pdfViewer: "object",
     },
   },
 };
@@ -3044,6 +3074,11 @@ const BANNED_APIS = [
     reason: "Dynamic import bypasses the loader's allowlist.",
   },
   { identifier: "globalThis", reason: "Host environment escape." },
+  {
+    identifier: "createObjectURL",
+    reason:
+      "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -4671,7 +4706,17 @@ const CONTRACT = deepFreeze({
   //    a `ListRow`'s lone `View` child spans the row; a selected row's bar
   //    no longer shifts its content. Other rows render as before.
   // 1.134.1: docs (sc-9122) — an emitted event can run a bound action.
-  version: "1.134.1",
+  // 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`.
+  // 1.136.0: additive (sc-9135) — `usePdfExport()` gains `openPdf(html,
+  //    { fileName? })`, `opening` and `canOpenPdf`: render server-side and
+  //    OPEN the PDF (web: browser viewer tab; native: expo-print sheet)
+  //    without saving it, through the new `device.pdfViewer` host slice. And
+  //    `createObjectURL` joins `bannedApis`: widgets reached for it to fake a
+  //    "print version" as a plain-text blob that never worked on native.
+  version: "1.136.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",
@@ -1176,9 +1179,22 @@ const HOOKS = [
   {
     name: "usePdfExport",
     signature: "usePdfExport({ spaceType, folderId })",
-    optionalArgs: ["folderId"],
-    description:
-      "Render an HTML string to a PDF server-side and SAVE it as a file in " +
+    optionalArgs: ["spaceType", "folderId"],
+    description:
+      "Render an HTML string to a PDF server-side, then either OPEN it or SAVE " +
+      "it. `openPdf(html, { fileName? })` is THE way to give the user a PDF " +
+      "to view, print, download or share: it renders the HTML and opens the " +
+      "result — the browser's PDF viewer in a new tab on the web Player, the " +
+      "OS print / share sheet in the native export — and SAVES NOTHING, so " +
+      "a widget that only opens PDFs calls `usePdfExport()` with no " +
+      "arguments (`spaceType` names where exportToPdf saves). Call " +
+      "it straight from the press handler (the web tab opens before the " +
+      "render so popup blockers allow it). It resolves once the document is " +
+      "handed to the viewer and rejects with `err.code` UNSUPPORTED when the " +
+      "host has no PDF viewer (check `canOpenPdf`), or the wire error " +
+      "(`err.status` 401 not signed in, 413 over the size cap, 429 too many " +
+      "renders, 503 renderer busy — try again). The rest of this entry is " +
+      "the SAVE path. `exportToPdf` renders and SAVES it as a file in " +
       "the end-user's Filestore space. The widget passes the SPACE " +
       "(`{ spaceType, folderId? }`); the hook resolves owner_id from the host " +
       "context and POSTs JSON through ctx.filestore.files.exportPdf. " +
@@ -1191,6 +1207,9 @@ const HOOKS = [
       "service (headless Chromium) — the SAME server-side pipeline on the web " +
       "Player and the native export, so no browser-only PDF library is used.",
     returnShape: {
+      openPdf: "(html, { fileName? }) => Promise<void>",
+      opening: "boolean",
+      canOpenPdf: "boolean",
       exportToPdf: "(html, { fileName?, folderId? }) => Promise<FilestoreFile>",
       exporting: "boolean",
       error: "Error | null",
@@ -1371,7 +1390,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",
@@ -1886,7 +1910,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",
@@ -2945,10 +2970,14 @@ const WIDGET_CONTEXT_SHAPE = {
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> }, " +
       "imageEditor: { isSupported() -> boolean, edit(uri, actions, options?) -> Promise<asset> }, " +
-      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> } }. " +
-      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor() and useBarcodeScanner(). The web Player brokers them via " +
-      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas and BarcodeDetector; the Expo export via " +
-      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator and expo-camera. " +
+      "barcode: { isSupported() -> boolean, scan(options?) -> Promise<{ value, format } | null> }, " +
+      "pdfViewer: { isSupported() -> boolean, open({ fileName, load: () => Promise<ArrayBuffer> }) -> Promise<void> } }. " +
+      "Backs useGeolocation(), useSpeechToText(), useCamera(), useImageEditor(), useBarcodeScanner() and usePdfExport().openPdf. The web Player brokers them via " +
+      "navigator.geolocation, window.SpeechRecognition, a getUserMedia camera preview, a host-side canvas, BarcodeDetector and a new browser tab; the Expo export via " +
+      "expo-location, expo-speech-recognition, expo-image-picker, expo-image-manipulator, expo-camera and expo-print. " +
+      "pdfViewer.open must be CALLED synchronously from the user's press: the web broker opens its tab before awaiting `load` " +
+      "(the server render), which is what keeps a popup blocker from refusing it; the Expo export writes the bytes to the " +
+      "cache and hands them to the OS print sheet. " +
       "imageEditor.edit applies resize / crop / rotate / flip in order and rejects with an ImageEditorError " +
       "(.code UNSUPPORTED | INVALID_ACTION | DECODE_FAILED | ENCODE_FAILED | INTERNAL). " +
       "getCurrentPosition rejects with a GeolocationError (.code PERMISSION_DENIED | UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL). " +
@@ -2976,6 +3005,7 @@ const WIDGET_CONTEXT_SHAPE = {
       camera: "object",
       imageEditor: "object",
       barcode: "object",
+      pdfViewer: "object",
     },
   },
 };
@@ -3040,6 +3070,11 @@ const BANNED_APIS = [
     reason: "Dynamic import bypasses the loader's allowlist.",
   },
   { identifier: "globalThis", reason: "Host environment escape." },
+  {
+    identifier: "createObjectURL",
+    reason:
+      "Web-only and opens widget-built bytes on the host origin; open a PDF with usePdfExport().openPdf.",
+  },
 ];
 
 // REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
@@ -4667,7 +4702,17 @@ const CONTRACT = deepFreeze({
   //    a `ListRow`'s lone `View` child spans the row; a selected row's bar
   //    no longer shifts its content. Other rows render as before.
   // 1.134.1: docs (sc-9122) — an emitted event can run a bound action.
-  version: "1.134.1",
+  // 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`.
+  // 1.136.0: additive (sc-9135) — `usePdfExport()` gains `openPdf(html,
+  //    { fileName? })`, `opening` and `canOpenPdf`: render server-side and
+  //    OPEN the PDF (web: browser viewer tab; native: expo-print sheet)
+  //    without saving it, through the new `device.pdfViewer` host slice. And
+  //    `createObjectURL` joins `bannedApis`: widgets reached for it to fake a
+  //    "print version" as a plain-text blob that never worked on native.
+  version: "1.136.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 {
@@ -4134,9 +4149,18 @@ export function useFilestoreUpload(options) {
 }
 
 /**
- * sc-2314 — render an HTML string to a PDF server-side and SAVE it into the
- * end-user's Filestore space. Returns `{ exportToPdf, exporting, error,
- * lastExported }`. The widget passes the SPACE (`{ spaceType, folderId? }`);
+ * sc-2314 / sc-9135 — render an HTML string to a PDF server-side, then OPEN it
+ * or SAVE it. Returns `{ openPdf, opening, canOpenPdf, exportToPdf, exporting,
+ * error, lastExported }`.
+ *
+ * `openPdf(html, { fileName? })` renders without saving and hands the bytes to
+ * the host's `device.pdfViewer`: a browser PDF tab on web, the OS print sheet
+ * on native. It is how a widget offers "print / view / download as PDF".
+ * `canOpenPdf` is false on a host with no viewer, where openPdf rejects with
+ * `err.code` UNSUPPORTED.
+ *
+ * `exportToPdf` SAVES into the end-user's Filestore space. The widget passes
+ * the SPACE (`{ spaceType, folderId? }`);
  * the hook resolves `owner_id` the same way the upload hook does (tenant for
  * PROJECT, app user for PERSONAL) and posts JSON to
  * `ctx.filestore.files.exportPdf`.
@@ -4174,6 +4198,45 @@ export function usePdfExport(options) {
 
   const filesRef = useRef(ctx.filestore.files);
   filesRef.current = ctx.filestore.files;
+  const viewerRef = useRef(ctx.device && ctx.device.pdfViewer);
+  viewerRef.current = ctx.device && ctx.device.pdfViewer;
+  const [opening, setOpening] = useState(false);
+  const openingCountRef = useRef(0);
+
+  const canOpenPdf =
+    _canOpenPdf(viewerRef.current) &&
+    typeof ctx.filestore.files.renderPdf === "function";
+
+  // Deliberately no `await` before viewer.open: the web broker must open its
+  // tab inside the press that called us, or a popup blocker refuses it.
+  const openPdf = useCallback(async (html, overrides) => {
+    if (typeof html !== "string" || html.trim().length === 0) {
+      throw new Error("usePdfExport: html is required");
+    }
+    const viewer = viewerRef.current;
+    const files = filesRef.current;
+    if (!_canOpenPdf(viewer) || typeof files.renderPdf !== "function") {
+      const err = new Error("This app cannot open PDFs here.");
+      err.code = "UNSUPPORTED";
+      setError(err);
+      throw err;
+    }
+    setError(null);
+    openingCountRef.current += 1;
+    setOpening(true);
+    try {
+      await viewer.open({
+        fileName: _pdfFileName(overrides && overrides.fileName),
+        load: () => files.renderPdf({ html }),
+      });
+    } catch (err) {
+      setError(err);
+      throw err;
+    } finally {
+      openingCountRef.current -= 1;
+      if (openingCountRef.current === 0) setOpening(false);
+    }
+  }, []);
 
   const exportToPdf = useCallback(
     async (html, overrides) => {
@@ -4213,7 +4276,36 @@ export function usePdfExport(options) {
     [ownerId, defaultFolderId, spaceType],
   );
 
-  return { exportToPdf, exporting, error, lastExported };
+  return {
+    openPdf,
+    opening,
+    canOpenPdf,
+    exportToPdf,
+    exporting,
+    error,
+    lastExported,
+  };
+}
+
+function _canOpenPdf(viewer) {
+  return Boolean(
+    viewer &&
+      typeof viewer.open === "function" &&
+      (typeof viewer.isSupported !== "function" || viewer.isSupported()),
+  );
+}
+
+// The name the viewer offers when the user saves or shares the document.
+function _pdfFileName(fileName) {
+  const base =
+    typeof fileName === "string" && fileName.trim()
+      ? Array.from(fileName.trim(), (ch) =>
+          ch < " " || ch === "/" || ch === "\\" ? "_" : ch,
+        )
+          .join("")
+          .slice(0, 120)
+      : "document";
+  return /\.pdf$/i.test(base) ? base : `${base}.pdf`;
 }
 
 /**

package/dist/index.d.ts

@@ -822,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> {
@@ -1065,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.173.1",
+  "version": "0.175.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",