@colixsystems/widget-sdk 0.197.0 → 0.199.0

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()",
@@ -1126,16 +1171,34 @@ const HOOKS = [
     requiredContextSlice: ["assets.list"],
     scopes: null,
   },
+  {
+    name: "useBundledAsset",
+    signature: "useBundledAsset(fileName)",
+    description:
+      "Returns the URL of an image or sound file the widget package ships in " +
+      "its assets/ directory, or null when the package has no file with that " +
+      "name. Only an uploaded package can bundle files; a widget written in " +
+      "the Studio has none.",
+    returnShape: {
+      "(returns)": "string | null",
+    },
+    requiredContextSlice: ["widget.assets"],
+    scopes: null,
+  },
   {
     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 +1253,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 +1383,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 +1400,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 +1408,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 +1746,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 +1835,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 +2435,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 +2453,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 +2669,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 +2776,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,
   },
@@ -2750,6 +2898,19 @@ const ACTION_SCRIPT_GLOBALS = [
 // Mirrors action.service.js SCRIPT_MAX_BYTES.
 const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
 
+// The one package size limit; the backend derives its upload caps from it.
+const PACKAGE_MAX_BYTES = 12 * 1024 * 1024;
+
+const BUNDLED_ASSETS = {
+  directory: "assets",
+  maxFiles: 50,
+  maxNameLength: 64,
+  types: {
+    image: { extensions: ["png", "jpg", "jpeg", "gif", "webp"] },
+    audio: { extensions: ["mp3", "m4a", "wav"] },
+  },
+};
+
 /**
  * sc-4915 — the trigger set a manifest action declares, canonically ordered.
  *
@@ -2913,13 +3074,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: {},
   },
 };
@@ -2933,9 +3094,15 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   widget: {
     description:
-      "Identity of the currently rendered widget instance ({ id, version }).",
+      "Identity of the currently rendered widget instance ({ id, version }) " +
+      "and the files its package bundles.",
     required: true,
-    fields: { id: "manifest.id", version: "manifest.version" },
+    fields: {
+      id: "manifest.id",
+      version: "manifest.version",
+      assets:
+        "{ [fileName]: string } — bundled file name → absolute URL; {} when the package bundles nothing",
+    },
   },
   // REQ-LAY-08 — optional host layout hint backing useFill(). True when the
   // host sized this widget to fill its layout slot's available height (a
@@ -2987,7 +3154,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 +3326,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 +3639,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 +5273,35 @@ 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).
+  // 1.159.0: additive (sc-10721) — a package may ship images and sounds in a
+  //    flat `assets/` directory (`bundledAssets`, within `packageMaxBytes`).
+  //    New `useBundledAsset(fileName)` resolves one through the new
+  //    `widget.assets` map; linter rule `bundled-asset-missing` (error).
+  version: "1.159.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5114,6 +5311,8 @@ const CONTRACT = deepFreeze({
   actionTriggerTypes: ACTION_TRIGGER_TYPES,
   actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
   actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
+  packageMaxBytes: PACKAGE_MAX_BYTES,
+  bundledAssets: BUNDLED_ASSETS,
   themeTokens: DEFAULT_THEME_TOKENS,
   themeColorTokens: THEME_COLOR_TOKENS,
   themeComponents: THEME_COMPONENTS,