@colixsystems/widget-sdk 0.197.0 → 0.198.0

package/dist/web-modal.js

@@ -0,0 +1,139 @@
+// The web `<Overlay>`'s modal layer: a body-level portal that owns its
+// container in a layout effect.
+//
+// react-native-web's `Modal` creates its container during render and removes it
+// in an effect cleanup. React StrictMode's mount → cleanup → mount detaches that
+// container, so the overlay rendered into an off-page node until some unrelated
+// re-render rebuilt it, and its Escape and focus handling never re-armed.
+//
+// Implements only the `Modal` props `<Overlay>` passes: `visible`,
+// `onRequestClose` and `children`; it is never animated.
+
+import React from "react";
+import { createPortal } from "react-dom";
+
+const FOCUSABLE =
+  'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+const layerStyle = {
+  position: "fixed",
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+  zIndex: 9999,
+  display: "flex",
+  flexDirection: "column",
+  outline: "none",
+};
+
+// Open layers, innermost last: only the top one handles Escape and Tab.
+const openLayers = [];
+
+function tabStops(dialog) {
+  return Array.from(dialog.querySelectorAll(FOCUSABLE)).filter(
+    (node) => node.getAttribute("aria-hidden") !== "true",
+  );
+}
+
+/**
+ * @param {{visible?: boolean, onRequestClose?: () => void, children?: any}} props
+ */
+export function WebModal({ visible = true, onRequestClose, children }) {
+  const [container, setContainer] = React.useState(null);
+  const dialogRef = React.useRef(null);
+  const onCloseRef = React.useRef(onRequestClose);
+  onCloseRef.current = onRequestClose;
+  // Taken before the dialog mounts, so a child that focuses itself on mount
+  // cannot become the place focus returns to.
+  const returnFocusRef = React.useRef(null);
+
+  React.useLayoutEffect(() => {
+    if (!visible) return undefined;
+    returnFocusRef.current = document.activeElement;
+    const node = document.createElement("div");
+    document.body.appendChild(node);
+    setContainer(node);
+    return () => {
+      node.remove();
+      setContainer(null);
+    };
+  }, [visible]);
+
+  React.useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!container || !dialog) return undefined;
+    const layer = {};
+    openLayers.push(layer);
+    const isTop = () => openLayers[openLayers.length - 1] === layer;
+    const returnFocusTo = returnFocusRef.current;
+    if (!dialog.contains(document.activeElement)) {
+      dialog.focus({ preventScroll: true });
+    }
+
+    // keyup, as react-native-web's Modal did, so the keydown that opened a
+    // nested overlay cannot also close it.
+    const onKeyUp = (event) => {
+      if (event.key !== "Escape" || !isTop()) return;
+      event.stopPropagation();
+      if (typeof onCloseRef.current === "function") onCloseRef.current();
+    };
+    const onKeyDown = (event) => {
+      if (event.key !== "Tab" || !isTop()) return;
+      const stops = tabStops(dialog);
+      if (!stops.length) {
+        event.preventDefault();
+        return;
+      }
+      const first = stops[0];
+      const last = stops[stops.length - 1];
+      const current = document.activeElement;
+      const outside = !dialog.contains(current) || current === dialog;
+      if (event.shiftKey && (outside || current === first)) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && (outside || current === last)) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    const onFocusIn = (event) => {
+      if (isTop() && !dialog.contains(event.target)) {
+        dialog.focus({ preventScroll: true });
+      }
+    };
+    document.addEventListener("keyup", onKeyUp);
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("focusin", onFocusIn);
+    return () => {
+      document.removeEventListener("keyup", onKeyUp);
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("focusin", onFocusIn);
+      const index = openLayers.indexOf(layer);
+      if (index !== -1) openLayers.splice(index, 1);
+      if (
+        returnFocusTo &&
+        typeof returnFocusTo.focus === "function" &&
+        returnFocusTo.isConnected
+      ) {
+        returnFocusTo.focus({ preventScroll: true });
+      }
+    };
+  }, [container]);
+
+  if (!visible || !container) return null;
+  return createPortal(
+    React.createElement(
+      "div",
+      {
+        ref: dialogRef,
+        role: "dialog",
+        "aria-modal": "true",
+        tabIndex: -1,
+        style: layerStyle,
+      },
+      children,
+    ),
+    container,
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.197.0",
+  "version": "0.198.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -62,6 +62,7 @@
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-native": "*",
+    "react-dom": ">=18.0.0",
     "react-native-web": ">=0.19.0"
   },
   "peerDependenciesMeta": {
@@ -73,6 +74,9 @@
     },
     "react-native-web": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "optionalDependencies": {

package/src/contract.js

@@ -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,
   },
@@ -2913,13 +3047,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: {},
   },
 };
@@ -2987,7 +3121,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" },
   },
@@ -3158,9 +3293,9 @@ const WIDGET_CONTEXT_SHAPE = {
   // sc-890 — backs useSendNotification(). Mirror of contract.cjs.
   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.cjs.
   identification: {
@@ -3471,7 +3606,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",
@@ -5104,7 +5240,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,