@colixsystems/widget-sdk 0.197.0 → 0.198.0

package/README.md

@@ -23,6 +23,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useUser()` | `{ id, email, displayName, photoUrl, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope. `photoUrl` is the user's own profile photo as an absolute URL, or `null`. |
 | **CORE** | `useUserPhoto()` | `{ url, canEdit, upload, remove, uploading, error }` | `ctx.user` + the optional `ctx.account` — no scope. Changes the signed-in user's OWN profile photo. `canEdit` is false when nobody is signed in or the host cannot change it; `upload` / `remove` then reject. |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
+| **CORE** | `useFilePreview(file)` | `{ uri }` | No scope. A temporary address an `<Image>` can show for a file the person picked but has not uploaded yet (a photo in a composer). Native picks use their own uri; on the web the SDK creates and releases an object URL, which widgets may not do themselves. `uri` is null for no file. |
+| **CORE** | `usePageBadge(count)` | `{ supported }` | `ctx.navigation.setBadge` — no scope. Puts `count` on the menu entry or tab of the page the widget is on (a chat's unread messages). The host sums the page's widgets and keeps the last count after the widget leaves the screen, until it reports again; `0` clears this widget's share. `supported` is false where the host draws no page badges (the Builder canvas). |
 | **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. |
@@ -67,6 +69,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **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`. |
+| **NOTIFICATIONS** (`ctx.notifications`) | `useRecordMutes(tableId)` | `{ isMuted, loading, error, refetch }` | `ctx.notifications.mutes` — no scope. Which records of one table the signed-in user has muted, in one request for a whole list; `isMuted(recordId)` turns false when a timed mute lapses, and a `useRecordMute` write shows at once. |
+| **NOTIFICATIONS** (`ctx.notifications`) | `useRecordMute(tableId, recordId)` | `{ muted, mutedUntil, loading, error, mute, unmute, refetch }` | `ctx.notifications.mutes` — no scope. Mutes one record's notifications for the signed-in user, `mute(until)` with an ISO time, a `Date`, or `null` for until unmuted. Needs read access to the record (`RECORD_NOT_FOUND` otherwise). |
 | **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. |
 
 All list calls return the `{ data, meta }` envelope; the read hooks unwrap `res.data` for you. There is no `useWorkspace()` or `useLogger()` hook — read the theme via `useTheme()` and the locale via `useI18n()`; the host logger lives on `ctx.logger` (`{ debug, info, warn, error }`).
@@ -77,7 +81,59 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.197.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.198.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.198.0 (contract 1.158.0)
+
+**`manifest.translations` may declare up to 200 keys (was 100).** A messenger or a form builder outgrows 100 strings once it ships every label its users read. Widening: every manifest that validated before still does.
+
+**`useDirectory({ ids })` resolves names for the people a widget already knows about.** Pass up to 100 user ids — message senders, members of a conversation — and get their `{ id, name, role }` rows without loading the whole roster; pair it with `q` for a server-side people search. Additive.
+
+**Files can be attached to a datastore record and stay private to it.** `useFilestoreUpload({ spaceType: "record", recordId })` attaches the uploaded file to that record, and `useFilestoreFiles({ spaceType: "record", recordId, type })` lists its attachments newest first (`type: "media"` for images and videos, `"document"` for the rest). Exactly the people who may read the record may read its attachments, through the same permission check as the record itself. Uploading needs write on the record, only the uploader may delete an attachment, and removing the record removes its attachments. A record attachment's URL is issued to one viewer and lives about ten minutes, so re-resolve it (`useFilestoreFile(id).refetch()`) when an image fails to load. The new `useFilestoreDelete()` returns `{ remove, removing, error }`: `remove(fileId)` deletes a record attachment permanently (only its uploader may) and moves any other file to the trash. `useFilestoreCopy().copy(fileId, { spaceType: "record", recordId })` attaches a copy of a file to a record, with the same write check as uploading there. `useCamera().pick({ multiple: true })` lets the user choose up to 10 photos from the device library at once and resolves an array of assets; `pick()` alone is unchanged. `<Avatar seed={user.id} />` draws the initials on that person's own colour, the same one the Studio's member lists use, and `avatarColorFor(seed)` returns it.
+
+**A `datastoreTemplate` can make inherited access read-only and stamp author columns on the server.** An `inheritAcl` RELATION column may add `inheritAclReadOnly: true`. Rows then inherit only READ access from the row they point at: members of a conversation read every message in it and may post into it, but change or delete only the messages they created (pair it with `grantCreatorPermissions`). This also holds down a chain, such as a reaction on a message in a conversation. A column may declare `defaultValue`, which is written when a create omits the column. Use `"@currentUser"` on a USER column, `"@now"` on a DATE or DATETIME column, or a literal of the column's own type. FILE, RELATION and USER_GROUP columns take no default, because ids belong to the installing workspace. `defaultLocked: true` on a `"@currentUser"` or `"@now"` default makes the server always stamp it. Any value a client sends for the column is ignored on create and on update, so a `Sender` or `CreatedBy` column is always the real author. `immutable: true` makes a column write-once: a create sets it from the value sent or the default, and any value sent for it on update is ignored, so a message's `Conversation` cannot be moved after it is posted. It is not valid on a MANY_TO_MANY relation, whose links live outside the row. Additive.
+
+**A user can mute one record's notifications.** `useRecordMute(tableId, recordId)` returns `{ muted, mutedUntil, loading, error, mute, unmute, refetch }`. `mute(until)` takes an ISO time or a `Date`, or `null` (or nothing) to mute until `unmute()`. While a mute is active, a server action's `notifications.notifyRecordSubjects` on that record sends the user nothing: no inbox row, no push, no email. `mutedUntil` is the ISO time the mute ends, or `null` when it lasts until unmuted, and `muted` turns false by itself when that time passes. The user must be able to read the record, so a record they cannot read fails with `NotificationError { code: "RECORD_NOT_FOUND" }`, just like one that does not exist. A falsy id returns a stable not-muted result with no request. On a host without `ctx.notifications.mutes` (the Builder canvas preview) the hook reads not muted, and `mute()` / `unmute()` reject with `NOTIFICATIONS_UNAVAILABLE`. No scope is needed, because it only changes the user's own setting. To show mutes in a list, call `useRecordMutes(tableId)` once: `isMuted(recordId)` answers for every row from one request, and a mute made through `useRecordMute` on the same table shows at once. `NotificationError.code` now carries the server's code when it sends one (`INVALID_TITLE`, `RECORD_NOT_FOUND`, …), and a 401 reads `AUTH_REQUIRED`. Additive.
+
+```jsx
+import { useRecordMute, Pressable, Text } from "@colixsystems/widget-sdk";
+
+function MuteToggle({ tableId, conversationId }) {
+  const { muted, mute, unmute } = useRecordMute(tableId, conversationId);
+  return (
+    <Pressable onPress={() => (muted ? unmute() : mute(null)).catch(() => {})}>
+      <Text>{muted ? "Unmute" : "Mute"}</Text>
+    </Pressable>
+  );
+}
+```
+
+**A list can show every muted record at once.** `useRecordMutes(tableId)` returns `{ isMuted, loading, error, refetch }` from one request, so a conversation list marks its muted rows without a read per row. No scope. Additive.
+
+**A widget can put a count on its page's menu entry.** `usePageBadge(count)` returns `{ supported }` and shows `count` on the menu entry or tab of the page the widget is on, on the web Player and in the exported app, through the new optional `ctx.navigation.setBadge`. The host adds up the counts of the page's widgets and keeps the last one after the widget leaves the screen; `0` clears it. No scope. Additive.
+
+**A picked file can be shown before it is uploaded.** `useFilePreview(file)` returns `{ uri }` for an `<Image>`: a native pick's own `uri`, or an object URL the hook releases on the web. No scope. Additive.
+
+**Videos play inline on both hosts.** `<Video source={url} />` plays a file with the platform's own controls and shows its first frame before playback: the browser's `<video>` on the web, expo-video's VideoView in the exported app. `contentFit` is `"contain"` (default) or `"cover"`, `controls` defaults to `true`, `autoPlay` starts it muted, and `onError()` fires when this host cannot play the file, so offer a download instead. A browser plays only the codecs it supports; H.264 MP4 plays everywhere.
+
+```jsx
+import { Video } from "@colixsystems/widget-sdk";
+
+<Video
+  source={file.url}
+  contentFit="cover"
+  style={{ width: 240, height: 180, borderRadius: theme.radii.md, overflow: "hidden" }}
+  onError={() => setPlayable(false)}
+/>
+```
+
+**A widget with pages of its own can answer Android's back button.** `useHardwareBack(handler)` runs `handler` on a back press while the widget's screen is in view; return `true` when it went back a step (closed a thread, left a settings page), `false` to let the app go back, and pass `null` while there is nothing to go back from. The exported app answers only for the screen in view, so a widget kept mounted on another tab never swallows the press. `supported` is `false` on the web Player, where browsers have no hardware back, so keep a visible back control too. No scope. Additive.
+
+**The photo picker chooses several, and videos.** `useCamera().pick({ multiple: true })` resolves an array of up to 10 assets, and `pick({ videos: true })` offers videos beside photos. A video asset has a `video/*` `mimeType` and `durationMs` (`null` for a photo); on iOS it arrives as H.264 so other devices can play it. Additive.
+
+**A person keeps one avatar everywhere.** `<Avatar seed={userId}>` and `avatarColorFor(seed)` give a person the monogram colour the Studio's member lists use, and `initialsFor` now gives a one-word name two letters ("Börje" → "BÖ"), so an `<Avatar>` of a single-name user changes from one letter to two.
+
+**Fixes.** `<Overlay>` opens at once under React StrictMode on the web: react-native-web's `Modal` lost its page container to StrictMode's effect replay, so a sheet stayed invisible until an unrelated re-render; the web binding now uses its own modal layer with the same dialog role, Escape, focus trap and focus return. `useDatastoreMutation` returns one stable object while its methods are unchanged, so a widget can list it as a dependency. `NotificationError.code` carries the server's code when it sends one.
 
 ### What's new in 0.197.0 (contract 1.157.0)
 

package/dist/avatar-color.js

@@ -0,0 +1,35 @@
+// sc-10268 — the ONE person tint, shared by the Studio's member lists and the
+// SDK `<Avatar seed>`, so a person seeded the same way is one colour everywhere.
+
+// Brand-neutral accents, each dark enough for white initials.
+const AVATAR_COLORS = Object.freeze([
+  "#0f766e",
+  "#3f5bd6",
+  "#b0562a",
+  "#7a4bcc",
+  "#b83b5e",
+  "#2f7d4f",
+  "#9333ea",
+  "#0369a1",
+  "#c2410c",
+  "#0e7490",
+]);
+
+/**
+ * A stable colour for a seed (a user id, an email), or null for no seed.
+ *
+ * FNV-1a plus a murmur-style avalanche: a plain `hash * 31 % N` keys the bucket
+ * off the low bits, which barely mix, so most seeds collide on one colour.
+ */
+export function avatarColorFor(seed) {
+  if (typeof seed !== "string" || !seed) return null;
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i += 1) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  h ^= h >>> 13;
+  h = Math.imul(h, 0x5bd1e995);
+  h ^= h >>> 15;
+  return AVATAR_COLORS[(h >>> 0) % AVATAR_COLORS.length];
+}

package/dist/contract.cjs

@@ -1044,6 +1044,51 @@ const HOOKS = [
     requiredContextSlice: ["navigation"],
     scopes: null,
   },
+  {
+    name: "useFilePreview",
+    signature: "useFilePreview(file)",
+    description:
+      "{ uri } an <Image> can show for a file the person picked but has not uploaded yet (a photo waiting in a " +
+      "composer, before it is sent). Native picks carry their own file uri; on the web the SDK makes a temporary " +
+      "address and releases it when the file changes or the component unmounts. uri is null for no file, or a host " +
+      "that cannot preview one. Widgets may not call createObjectURL themselves; this is the sanctioned way. No scope. " +
+      "Identical on web (Player) and the Expo export.",
+    returnShape: {
+      uri: "string | null  // pass as <Image source={{ uri }} />; null when there is nothing to show",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
+  {
+    name: "usePageBadge",
+    signature: "usePageBadge(count)",
+    description:
+      "Puts count on the menu entry or tab of the page this widget is on (a chat's unread messages, open tasks). " +
+      "The host sums every widget on the page and keeps the last count after the widget leaves the screen, until it " +
+      "reports again; 0, or anything not a positive number, clears this widget's share. Returns { supported }: false " +
+      "on a host without page badges (the Builder canvas), where it does nothing. Call it at render with the current " +
+      "count, never in a loop. Backed by ctx.navigation.setBadge. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      supported: "boolean  // false where the host draws no page badges",
+    },
+    requiredContextSlice: ["navigation"],
+    scopes: null,
+  },
+  {
+    name: "useHardwareBack",
+    signature: "useHardwareBack(handler)",
+    description:
+      "Android's back button, for a widget with pages of its own (a thread over a list, a settings page over a thread). " +
+      "handler runs on a back press while the widget's screen is in view: return true when it went back a step, false to " +
+      "let the app go back. Pass null while there is nothing to go back from. Returns { supported }: false on the web " +
+      "Player, where browsers have no hardware back, so always keep a visible back control too. Backed by the optional " +
+      "ctx.navigation.onHardwareBack(listener) → unsubscribe, which the Expo export answers only for the screen in view.",
+    returnShape: {
+      supported: "boolean  // false on the web, which has no hardware back",
+    },
+    requiredContextSlice: ["navigation"],
+    scopes: null,
+  },
   {
     name: "usePageContext",
     signature: "usePageContext()",
@@ -1128,14 +1173,18 @@ const HOOKS = [
   },
   {
     name: "useFilestoreFiles",
-    signature: "useFilestoreFiles({ spaceType, folderId, q, type })",
-    optionalArgs: ["folderId", "q", "type"],
+    signature: "useFilestoreFiles({ spaceType, recordId, folderId, q, type })",
+    optionalArgs: ["recordId", "folderId", "q", "type"],
     description:
-      "Browse the end-user's Filestore files in a project, personal, or public " +
-      "space. The hook resolves owner_id from the host context (tenant for " +
-      "project/public, app user for personal) — the widget only chooses the " +
+      "Browse the end-user's Filestore files in a project, personal, public or " +
+      "record space. The hook resolves owner_id from the host context (tenant " +
+      "for project/public, app user for personal) — the widget only chooses the " +
       "space. A public space is world-readable: its files render even for " +
-      "logged-out Player visitors. Reads ctx.filestore.files.list and unwraps " +
+      "logged-out Player visitors. A record space (`{ spaceType: \"record\", " +
+      "recordId }`) holds one datastore record's attachments, readable by " +
+      "exactly whoever may read that record; it has no folders, lists newest " +
+      "first, and `type: \"media\"` narrows it to images and videos " +
+      "(`\"document\"` to everything else). Reads ctx.filestore.files.list and unwraps " +
       "{ data, meta } to the files array. Every row carries a ready-to-render " +
       "`url` (its absolutized presigned_url, aliased by the filestore client) " +
       "so a gallery renders `files.map(f => f.url)` directly. Every row ALSO " +
@@ -1190,11 +1239,13 @@ const HOOKS = [
   },
   {
     name: "useFilestoreUpload",
-    signature: "useFilestoreUpload({ spaceType, folderId, compress })",
-    optionalArgs: ["folderId", "compress"],
+    signature: "useFilestoreUpload({ spaceType, recordId, folderId, compress })",
+    optionalArgs: ["recordId", "folderId", "compress"],
     description:
       "Upload a file into the end-user's Filestore space. The widget passes " +
-      "the SPACE (`{ spaceType, folderId? }`); the hook resolves owner_id " +
+      "the SPACE (`{ spaceType, folderId? }`, or `{ spaceType: \"record\", " +
+      "recordId }` to attach the file to a datastore record: that needs write " +
+      "on the record, and only the uploader may later delete it); the hook resolves owner_id " +
       "from the host context, builds a multipart FormData with the " +
       "snake_case fields the backend reads verbatim (`space_type`, " +
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
@@ -1318,9 +1369,12 @@ const HOOKS = [
     signature: "useFilestoreCopy()",
     description:
       "Copy a Filestore file into any space and folder the caller may add files " +
-      "to, including ACROSS spaces (project, public, and the signed-in user's " +
-      "personal space). `copy(fileId, { spaceType, folderId?, name? })` names the " +
-      "DESTINATION (spaceType is required); the hook resolves its owner_id from " +
+      "to, including ACROSS spaces (project, public, the signed-in user's " +
+      "personal space, and a datastore record's attachments). " +
+      "`copy(fileId, { spaceType, recordId?, folderId?, name? })` names the " +
+      "DESTINATION (spaceType is required; `{ spaceType: \"record\", recordId }` " +
+      "attaches the copy to that record, which needs write access to it and has " +
+      "no folders); the hook resolves its owner_id from " +
       "the host context and posts through ctx.filestore.files.copy. Resolves to " +
       "the NEW file row (its own id and url) — the source is untouched and the " +
       "bytes are duplicated, so later changes to one never affect the other. A " +
@@ -1332,7 +1386,7 @@ const HOOKS = [
       "STORAGE_QUOTA_EXCEEDED when the destination space is full; 409 " +
       "FILE_PROCESSING while a video is still being processed.",
     returnShape: {
-      copy: "(fileId, { spaceType, folderId?, name? }) => Promise<FilestoreFile>",
+      copy: "(fileId, { spaceType, recordId?, folderId?, name? }) => Promise<FilestoreFile>  // recordId with spaceType \"record\"",
       copying: "boolean",
       error: "Error | null",
       lastCopied: "FilestoreFile | null",
@@ -1340,6 +1394,26 @@ const HOOKS = [
     requiredContextSlice: ["filestore.files"],
     scopes: ["files.write:*"],
   },
+  {
+    name: "useFilestoreDelete",
+    signature: "useFilestoreDelete()",
+    description:
+      "Delete a Filestore file the caller may delete. `remove(fileId)` calls " +
+      "ctx.filestore.files.remove: a record attachment (a file in a record " +
+      "space) is deleted permanently and only its uploader may do it; a file in " +
+      "any other space moves to the trash. Use it when the thing that showed " +
+      "the file is withdrawn, such as an unsent chat message, so the file stops " +
+      "being readable rather than merely hidden. Refusals arrive as " +
+      "`err.status`: 403 when the caller may not delete it, 404 when it is not " +
+      "visible.",
+    returnShape: {
+      remove: "(fileId) => Promise<void>",
+      removing: "boolean",
+      error: "Error | null",
+    },
+    requiredContextSlice: ["filestore.files"],
+    scopes: ["files.write:*"],
+  },
   {
     name: "useFileSignature",
     signature: "useFileSignature(fileId, existingSignatureId)",
@@ -1658,6 +1732,8 @@ const HOOKS = [
     name: "useDirectory",
     signature: "useDirectory(query)",
     optionalArgs: ["query"],
+    description:
+      "Read-only roster of app users. query is { q?, role?, is_active?, group_id?, ids?, limit?, offset? }; ids (1 to 100) resolves the names behind ids a widget already holds.",
     returnShape: {
       users: "Array<{ id, name, role }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
@@ -1745,6 +1821,53 @@ const HOOKS = [
     requiredContextSlice: ["notifications.send"],
     scopes: ["notifications.send:appUser"],
   },
+  // sc-10268 — the signed-in user's mute of one record's notifications.
+  // Reads ctx.notifications.mutes. No scope: it only touches the caller's
+  // own setting, and the server requires their read access to the record.
+  {
+    name: "useRecordMute",
+    signature: "useRecordMute(tableId, recordId)",
+    description:
+      "The signed-in user's mute of the notifications ONE datastore record produces for them (a chat conversation, a " +
+      "thread). mute(until) takes an ISO time or a Date, or null (or nothing) to mute until unmute(). While muted, a " +
+      "server action's notifications.notifyRecordSubjects on that record sends this user nothing: no inbox row, no push, " +
+      "no email. mutedUntil is an ISO string, or null when muted until unmuted; muted turns false by itself once " +
+      "mutedUntil passes. The user must be able to read the record, otherwise every call fails with NotificationError " +
+      "{ code: \"RECORD_NOT_FOUND\" }, exactly as for a missing record. A falsy tableId or recordId returns a stable " +
+      "not-muted result with no network call. On a host that cannot mute (the Builder canvas preview) it reads not " +
+      "muted and mute() / unmute() reject with NOTIFICATIONS_UNAVAILABLE instead of the hook throwing at render. " +
+      "Needs no scope: it only ever changes the caller's own setting. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      muted: "boolean",
+      mutedUntil: "string | null  // ISO time the mute ends; null when muted until unmuted, or not muted",
+      loading: "boolean",
+      error: "NotificationError | null",
+      mute: "(until?: string | Date | null) => Promise<void>  // null or omitted = until unmuted",
+      unmute: "() => Promise<void>",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["notifications.mutes"],
+    scopes: null,
+  },
+  {
+    name: "useRecordMutes",
+    signature: "useRecordMutes(tableId)",
+    description:
+      "Which records of ONE table the signed-in user has muted, read in one request for a whole list (a chat's " +
+      "conversations), never one useRecordMute per row. isMuted(recordId) is true while that record's mute is active " +
+      "and turns false by itself once a timed mute lapses. A mute or unmute made through useRecordMute on the same table " +
+      "shows here at once. A falsy tableId, or a host that cannot mute (the Builder canvas preview), reads nothing " +
+      "muted with no network call. Needs no scope: it only reads the caller's own settings. Identical on web (Player) " +
+      "and the Expo export.",
+    returnShape: {
+      isMuted: "(recordId: string) => boolean",
+      loading: "boolean",
+      error: "NotificationError | null",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["notifications.mutes"],
+    scopes: null,
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
@@ -2298,9 +2421,12 @@ const HOOKS = [
     optionalArgs: ["options"],
     description:
       "Take a photo or choose one from the device library. Returns { asset, loading, error, supported, capture, pick, reset }. " +
+      "pick({ multiple: true }) lets the user choose up to 10 photos at once and resolves an ARRAY of assets (asset then holds that array); " +
+      "pick({ videos: true }) offers videos beside photos — a video asset has a video/* mimeType and durationMs (null for a photo); play it with <Video>. " +
+      "capture() always takes one. " +
       "Capture is IMPERATIVE — call capture() or pick() from a user gesture (a tap); the browser and the mobile OS gate the " +
       "permission prompt on a gesture, so it NEVER opens on mount. Both resolve to a normalised asset " +
-      "{ uri, name, mimeType, width, height, size, file }, or NULL when the user dismisses the picker — dismissal is the " +
+      "{ uri, name, mimeType, width, height, size, durationMs, file }, or NULL when the user dismisses the picker — dismissal is the " +
       "common case and is deliberately NOT an error, so no try/catch is needed on the happy path. They reject with a " +
       "CameraError whose .code is one of PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `asset.file` is already the right " +
       "upload part for the host — a BLOB on both (a File on web, expo-file-system's File on native), because Expo's fetch " +
@@ -2313,13 +2439,13 @@ const HOOKS = [
       "rejects UNSUPPORTED — there is no silent fall back to a file dialog.",
     returnShape: {
       asset:
-        "{ uri, name, mimeType, width, height, size, file } | null",
+        "{ uri, name, mimeType, width, height, size, durationMs, file } | null",
       loading: "boolean",
       error: "CameraError | null",
       supported: "boolean  // false when the host brokers no camera",
       capture:
         "() => Promise<asset | null>  // null if dismissed; rejects with CameraError",
-      pick: "() => Promise<asset | null>  // null if dismissed; rejects with CameraError",
+      pick: "(options?: { multiple?: boolean, videos?: boolean }) => Promise<asset | asset[] | null>  // { multiple: true } resolves an array of up to 10; { videos: true } offers videos too; null if dismissed; rejects with CameraError",
       reset: "() => void  // clear the asset + error and release it",
     },
     requiredContextSlice: [],
@@ -2529,6 +2655,14 @@ const PRIMITIVES = [
     rnComponent: "expo-linear-gradient",
     docsUrl: "https://docs.expo.dev/versions/latest/sdk/linear-gradient/",
   },
+  // sc-10268 — inline video playback with no platform split.
+  {
+    name: "Video",
+    description:
+      "Plays a video file inline with the platform's own controls. `<Video source={url} contentFit=\"cover\" style={{ width: 240, height: 180, borderRadius: theme.radii.md, overflow: \"hidden\" }} />`. `source` is a playable URL (a filestore file's url, or a picked asset's `uri` for a preview); `controls` (default true) shows play/seek/fullscreen; `autoPlay` starts it muted (browsers only autoplay muted video); `contentFit` is \"contain\" (default, letterboxed) or \"cover\"; `onError()` fires when the file cannot be played, so offer a download instead. Before playback it shows the first frame. Size it with `style` (it fills its box). Web uses the browser's <video>; native uses expo-video's VideoView, so the same widget plays on both hosts. A browser plays only the codecs it supports, so H.264 MP4 is the format that plays everywhere.",
+    rnComponent: "expo-video",
+    docsUrl: "https://docs.expo.dev/versions/latest/sdk/video/",
+  },
   // sc-6531 (REQ-AI-AGENT-DESIGN-LIFT) — the hover/press lift affordance. A
   // FUNCTION primitive, not a component: it resolves the interaction tokens per
   // input, so one declaration answers the pointer on web and the press on
@@ -2628,7 +2762,7 @@ const PRIMITIVES = [
   {
     name: "Avatar",
     description:
-      'Themed picture of a person. `<Avatar name={row.owner.label} url={photoUrl} size="sm" />`. THE way to show a PERSON: in a `<ListRow>` leading slot, a profile header, a list of members. It falls back from the picture to the name\'s initials to a person glyph, so the slot is never blank. Never use it for a place, product or topic. Props: `name` (the initials and the accessibility label come from it), `url` (an absolute image URL; resolve a file field to a URL first), `size` ("sm" 32 | "md" 40 | "lg" 56 | "xl" 80, or a number of px), `shape` ("circle" | "rounded"), `accessibilityLabel`, `style`, `testID`.',
+      'Themed picture of a person. `<Avatar name={row.owner.label} url={photoUrl} size="sm" />`. THE way to show a PERSON: in a `<ListRow>` leading slot, a profile header, a list of members. It falls back from the picture to the name\'s initials to a person glyph, so the slot is never blank. Never use it for a place, product or topic. Props: `name` (the initials and the accessibility label come from it), `seed` (a stable id such as the user\'s id: the initials sit on that person\'s own colour, the same one the Studio\'s member lists use, so people in a list tell apart at a glance; `avatarColorFor(seed)` returns it), `url` (an absolute image URL; resolve a file field to a URL first), `size` ("sm" 32 | "md" 40 | "lg" 56 | "xl" 80, or a number of px), `shape` ("circle" | "rounded"), `accessibilityLabel`, `style`, `testID`.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -2917,13 +3051,13 @@ 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.",
+      "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).",
   },
   translations: {
     type: "object",
     required: false,
     description:
-      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤100 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
+      "Optional (REQ-L10N-WIDGET). Translation strings the widget ships. Shape { <key>: { en: string, <locale>?: string, ... } } — `en` is REQUIRED per key. At install the host merges these into the tenant's localization dictionary under a per-widget namespace (`widget.<manifest.id>.<key>`); `useI18n().t(\"<key>\")` resolves the namespaced key automatically, so authors never type the prefix. Non-destructive: an existing admin-edited value is never overwritten, and a language the tenant has not added is never created (values for absent locales are dropped; the widget's `en` seeds the tenant's base language so every key renders). Keys persist across uninstalls; admins prune them from the Translations admin (bulk delete by `widget.<id>.` prefix). Limits: ≤200 keys; each key matches /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/; each value ≤1 KB; the namespaced key must fit the dictionary key cap (128 chars).",
     default: {},
   },
 };
@@ -2991,7 +3125,8 @@ const WIDGET_CONTEXT_SHAPE = {
     },
   },
   navigation: {
-    description: "{ push(path), replace(path), back() }.",
+    description:
+      "{ push(path), replace(path), back() }, and optionally setBadge(count) — the page badge usePageBadge() writes, bound by the host to this widget on its page — and onHardwareBack(listener) → unsubscribe, Android's back button for useHardwareBack(), which the native host answers only for the screen in view.",
     required: true,
     fields: { push: "function", replace: "function", back: "function" },
   },
@@ -3162,9 +3297,9 @@ const WIDGET_CONTEXT_SHAPE = {
   // sc-890 — backs useSendNotification(). Mirror of contract.js.
   notifications: {
     description:
-      "Injected @colixsystems/notifications-client instance (sc-890). { send(body) -> Promise<notification> }. Backs useSendNotification(); requires the notifications.send:appUser scope. The host POSTs the body snake_case verbatim ({ recipient_user_id, title, body, link?, payload? }) to /notifications/send and returns the created notification row; the call is imperative (a send never fires on mount).",
+      "Injected @colixsystems/notifications-client instance (sc-890). { send(body) -> Promise<notification>, mutes: { get, set, clear } }. send backs useSendNotification(); requires the notifications.send:appUser scope. The host POSTs the body snake_case verbatim ({ recipient_user_id, title, body, link?, payload? }) to /notifications/send and returns the created notification row; the call is imperative (a send never fires on mount). mutes backs useRecordMute() and useRecordMutes() (sc-10268): get({ table_id, record_id }) / set({ table_id, record_id, muted_until }) -> { muted, muted_until }, clear({ table_id, record_id }) -> undefined, list({ table_id, limit?, offset? }) -> { data: [{ record_id, muted_until }], meta }. mutes is optional — a host without it (the Builder canvas preview) leaves useRecordMute() reading not muted.",
     required: true,
-    fields: { send: "function" },
+    fields: { send: "function", mutes: "object" },
   },
   // REQ-IDENT (sc-4313) — backs useIdentification(). Mirror of contract.js.
   identification: {
@@ -3475,7 +3610,8 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "media",
     description:
-      "Native video playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <video> element in widget.web.jsx.",
+      "Native video playback (Expo SDK 56; replaces the removed expo-av). Native-only; pair with the browser <video> element in widget.web.jsx. " +
+      "To play a video file on BOTH hosts, prefer the SDK's <Video> primitive — no platform split needed.",
   },
   {
     specifier: "@react-native-community/datetimepicker",
@@ -5108,7 +5244,31 @@ const CONTRACT = deepFreeze({
   //    as before; a malformed `via` is dropped, or voids the gradient under the
   //    new `{ strict: true }` option. New `componentGradientColors` / `componentGradientMidpoint`
   //    read the paint list and the ink basis off a normalised gradient.
-  version: "1.157.0",
+  // 1.158.0: additive (sc-10268) — a datastoreTemplate column may declare
+  //    `inheritAclReadOnly` (with `inheritAcl`), `defaultValue`, and
+  //    `defaultLocked` (with a "@currentUser" / "@now" default), and
+  //    `immutable` (write-once; not on MANY_TO_MANY).
+  //    (sc-10269) `useFilestoreFiles` / `useFilestoreUpload` accept
+  //    `spaceType: "record"` with `recordId`: a record's private attachments.
+  //    New `useFilestoreDelete()` → `{ remove, removing, error }`.
+  //    `useCamera().pick({ multiple: true })` resolves an array of up to 10.
+  //    `<Avatar seed>` + `avatarColorFor(seed)`: a person's own monogram
+  //    colour, shared with the Studio's member lists.
+  //    New `useRecordMute(tableId, recordId)` mutes one record's
+  //    notifications for the signed-in user, through the new
+  //    `ctx.notifications.mutes` ({ get, set, clear }).
+  //    `useFilestoreCopy().copy` takes `{ spaceType: "record", recordId }`.
+  //    `useDirectory({ ids })` resolves the names behind up to 100 user ids.
+  //    `manifest.translations` may declare up to 200 keys (was 100).
+  //    New `useRecordMutes(tableId)` lists the muted records at once;
+  //    `usePageBadge(count)` counts on the page's menu entry through the new
+  //    optional `ctx.navigation.setBadge`; `useFilePreview(file)` shows a
+  //    picked file before upload. New `<Video>` plays a file inline on both
+  //    hosts, and `useCamera().pick({ videos: true })` offers videos, an
+  //    asset carrying `durationMs`. New `useHardwareBack(handler)` walks a
+  //    widget's own pages on Android's back button (optional
+  //    `ctx.navigation.onHardwareBack`; unsupported on the web).
+  version: "1.158.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,