@colixsystems/widget-sdk 0.18.0 → 0.21.1

package/dist/contract.cjs

@@ -10,9 +10,9 @@
 
 const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
-    primary: "#ff6b5b",
+    primary: "#3b82f6",
     onPrimary: "#ffffff",
-    secondary: "#475569",
+    secondary: "#10b981",
     onSecondary: "#ffffff",
     surface: "#ffffff",
     onSurface: "#111827",
@@ -70,6 +70,26 @@ const HOOKS = [
     requiredContextSlice: ["user"],
     scopes: null,
   },
+  {
+    name: "useFill",
+    signature: "useFill()",
+    description:
+      "Returns true when the host has sized this widget to fill its layout " +
+      'slot\'s available height — a page-grid tile whose author chose "Fill ' +
+      'tile height", or a widget type that fills by default (containers and ' +
+      "media). When true, a widget that has a meaningful filled form (Image, " +
+      "Chart, Map, Video) should switch from its intrinsic height to a stretch " +
+      'style (flex: 1 / height: "100%"); widgets with no useful filled form ' +
+      "may ignore it. Defaults to false wherever the host has not opted the " +
+      "widget into filling, so calling it is always safe. The SAME value is " +
+      "injected by the web Player and the native export (CLAUDE.md §3), so a " +
+      "widget's fill behaviour is identical on both platforms.",
+    returnShape: {
+      "(returns)": "boolean",
+    },
+    requiredContextSlice: ["fill"],
+    scopes: null,
+  },
   {
     name: "useChildRenderer",
     signature: "useChildRenderer()",
@@ -167,12 +187,12 @@ const HOOKS = [
     name: "useDirectory",
     signature: "useDirectory(query?)",
     returnShape: {
-      users: "Array<{ id, name, role }>",
+      users: "Array<{ id, name, role }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DatastoreError | null",
       refetch: "() => Promise<void>",
     },
-    requiredContextSlice: ["directory.listUsers"],
+    requiredContextSlice: ["directory.users"],
     scopes: ["directory.read:users"],
   },
   {
@@ -206,28 +226,26 @@ const HOOKS = [
     name: "useUsers",
     signature: "useUsers(query?)",
     description:
-      "AppUser administration. Returns { users, loading, error, refetch, invite, " +
-      "deactivate, reactivate, remove }. Reads need users.read:* scope; mutations " +
-      "need users.write:*. The `invite` call accepts { email, name, groupIds? } " +
-      "and returns the resulting AppUserInvite row (the email is sent by the host).",
+      "AppUser administration via the injected directory-client at " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate}. Returns " +
+      "{ users, loading, error, refetch, invite, deactivate, reactivate, remove }. " +
+      "list returns the { data, meta } envelope verbatim — the hook unwraps " +
+      "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
+      "scope; mutations need users.write:*. The `invite` call accepts " +
+      "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
+      "(the email is sent by the host).",
     returnShape: {
-      users: "Array<{ id, name, email?, role, isActive }>",
+      users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
       invite:
-        "({ email, name, groupIds? }) => Promise<Invite>  // rejects with DirectoryError",
+        "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
       deactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       reactivate: "(userId) => Promise<User>  // rejects with DirectoryError",
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
     },
-    requiredContextSlice: [
-      "users.listUsers",
-      "users.invite",
-      "users.deactivate",
-      "users.reactivate",
-      "users.remove",
-    ],
+    requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
   },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
@@ -239,11 +257,14 @@ const HOOKS = [
     name: "useGroups",
     signature: "useGroups(query?)",
     description:
-      "AppUserGroup administration. Returns { groups, loading, error, refetch, " +
-      "create, remove, addMember, removeMember }. Reads need groups.read:*; " +
+      "AppUserGroup administration via the injected directory-client at " +
+      "ctx.directory.groups.{list,create,remove,addMember,removeMember,listMine}. " +
+      "Returns { groups, loading, error, refetch, create, remove, addMember, " +
+      "removeMember }. list returns the { data, meta } envelope verbatim — the " +
+      "hook unwraps res.data; rows are snake_case. Reads need groups.read:*; " +
       "mutations need groups.write:*.",
     returnShape: {
-      groups: "Array<{ id, name, memberCount }>",
+      groups: "Array<{ id, name, member_count }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "DirectoryError | null",
       refetch: "() => Promise<void>",
@@ -255,13 +276,7 @@ const HOOKS = [
       removeMember:
         "(groupId, userId) => Promise<void>  // rejects with DirectoryError",
     },
-    requiredContextSlice: [
-      "groups.listGroups",
-      "groups.create",
-      "groups.remove",
-      "groups.addMember",
-      "groups.removeMember",
-    ],
+    requiredContextSlice: ["directory.groups"],
     scopes: ["groups.read:*"],
   },
   // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
@@ -270,33 +285,33 @@ const HOOKS = [
     name: "useRecordPermissions",
     signature: "useRecordPermissions(tableId, recordId)",
     description:
-      "Manage per-record VirtualPermission grants on a single record. Returns " +
-      "{ permissions, loading, error, grant, revoke, update, refetch } where " +
-      "permissions is Array<{ id, principalType: 'USER' | 'GROUP' | 'PUBLIC', " +
-      "principalId, canRead, canWrite, canDelete, canGrant }>. Mutating " +
-      "requires acl.write:records scope AND canGrant on the target record " +
-      "(REQ-ACL-RELINHERIT-05: APP_USER actors with canGrant are accepted, " +
-      "not only Studio owners). When tableId or recordId is null/empty the " +
-      "hook collapses to an empty no-op result without a network round-trip.",
+      "Manage per-record VirtualPermission grants on a single record via the " +
+      "injected datastore-client at " +
+      "ctx.datastore.records(tableId).permissions(recordId).{list,grant,update,revoke}. " +
+      "Returns { permissions, loading, error, grant, revoke, update, refetch } " +
+      "where permissions is Array<{ id, user_id, group_id, can_read, can_write, " +
+      "can_delete, can_grant }> (snake_case rows verbatim; list() returns the " +
+      "{ data, meta } envelope and the hook unwraps res.data). grant/update " +
+      "bodies are snake_case verbatim ({ user_id | group_id, can_read, " +
+      "can_write, can_delete, can_grant }). Mutating requires acl.write:records " +
+      "scope AND can_grant on the target record (REQ-ACL-RELINHERIT-05: " +
+      "APP_USER actors with can_grant are accepted, not only Studio owners). " +
+      "When tableId or recordId is null/empty the hook collapses to an empty " +
+      "no-op result without a network round-trip.",
     returnShape: {
       permissions:
-        "Array<{ id, principalType: 'USER' | 'GROUP' | 'PUBLIC', principalId, canRead, canWrite, canDelete, canGrant }>",
+        "Array<{ id, user_id, group_id, can_read, can_write, can_delete, can_grant }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
       error: "PermissionError | null",
       grant:
-        "({ principalType, principalId?, canRead?, canWrite?, canDelete?, canGrant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+        "({ user_id?, group_id?, can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
       revoke:
         "(permissionId) => Promise<void>  // rejects with PermissionError",
       update:
-        "(permissionId, { canRead?, canWrite?, canDelete?, canGrant? }) => Promise<RecordPermission>  // rejects with PermissionError",
+        "(permissionId, { can_read?, can_write?, can_delete?, can_grant? }) => Promise<RecordPermission>  // rejects with PermissionError",
       refetch: "() => Promise<void>",
     },
-    requiredContextSlice: [
-      "recordPermissions.list",
-      "recordPermissions.grant",
-      "recordPermissions.revoke",
-      "recordPermissions.update",
-    ],
+    requiredContextSlice: ["datastore.records"],
     scopes: ["acl.write:records"],
   },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
@@ -454,10 +469,40 @@ const CATEGORIES = [
   "DATA",
   "MEDIA",
   "COMMUNICATION",
+  // REQ-USERMGMT-06: app-administration widgets (User Management, …) the
+  // published app embeds for its own member management — its own palette
+  // section, distinct from COMMUNICATION.
+  "ADMINISTRATION",
   "CUSTOM",
 ];
 const PLATFORMS = ["web", "native"];
 
+// REQ-WIDGET-ACTION — server-side actions a widget may declare in its
+// manifest. Each runs in the shared isolated-vm action runner (see backend
+// action-runner.service.js) on a cron schedule or in response to a record
+// CRUD event — NEVER in the rendered app, so they never affect Player ↔
+// export parity. The trigger vocabulary mirrors the backend Action model.
+const ACTION_TRIGGER_TYPES = [
+  "schedule",
+  "record_created",
+  "record_updated",
+  "record_deleted",
+];
+// Globals the action script runs against (the runner's surface) — distinct
+// from the React/SDK widget surface, so the component import/banned-API
+// linter does NOT scan action scripts.
+const ACTION_SCRIPT_GLOBALS = [
+  "datastore",
+  "fetch",
+  "console",
+  "record",
+  "tenantId",
+  "triggerType",
+  "triggerTableId",
+];
+// Mirrors action.service.js SCRIPT_MAX_BYTES.
+const ACTION_SCRIPT_MAX_BYTES = 200 * 1024;
+
 // Reverse-DNS-ish manifest id, e.g. "com.acme.charts.barchart". Two or
 // more labels, lowercase alnum + hyphen, label starts with a letter. The
 // analyzer + the SDK validator both read this from the contract so a
@@ -543,6 +588,24 @@ const MANIFEST_SCHEMA = {
     description:
       "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (must be declared earlier in the array). Tables persist across uninstalls.",
   },
+  actions: {
+    type: "object[]",
+    required: false,
+    description:
+      "Optional. Server-side actions the widget declares. Each runs in the shared isolated-vm action runner (cron- or record-triggered) — NEVER in the rendered app. Operators enable them per tenant from the Properties Panel; the action materialises DISABLED until they bind an integration API key (and, for record_* triggers, a target table) in the Actions admin page. Each entry: { key (stable, unique within the manifest), name, description?, triggerType (one of " +
+      ACTION_TRIGGER_TYPES.join(", ") +
+      "), scheduleCron? (required iff triggerType=='schedule'; node-cron syntax), timeoutMs? (100–300000), scriptSource (≤200 KiB; runs against " +
+      ACTION_SCRIPT_GLOBALS.join(", ") +
+      " — NOT the React surface, so SDK imports/hooks are unavailable) }. Do NOT include triggerTableId or apiKeyId — those are tenant-local and bound after install.",
+    default: [],
+  },
+  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).",
+    default: {},
+  },
 };
 
 const WIDGET_CONTEXT_SHAPE = {
@@ -558,10 +621,24 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { id: "manifest.id", version: "manifest.version" },
   },
+  // 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
+  // page-grid tile set to "Fill tile height", or a default-fill widget type).
+  // Optional: a host that never fills a widget simply omits it and useFill()
+  // returns false, so existing hosts need no change.
+  fill: {
+    description:
+      "Optional host layout hint (boolean). True when the host sized this " +
+      "widget to fill its layout slot's available height (page-grid tile " +
+      "fill). Backs useFill(); defaults to false when absent.",
+    required: false,
+    fields: {},
+  },
   user: {
-    description: "Signed-in user ({ id, email, displayName }).",
+    description:
+      "Signed-in user, host-provided VERBATIM (snake_case: { id, email, display_name, roles, group_ids }). Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", displayName: "string" },
+    fields: { id: "string", email: "string", display_name: "string" },
   },
   workspace: {
     description:
@@ -581,19 +658,30 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   datastore: {
     description:
-      "{ records(table) -> { list(query?), get(id), create(values), update(id, values), delete(id) }, schema(table) -> Promise<{ id, name, columns: [...] }> }. `records` backs the query/record/mutation hooks; `schema` backs useDatastoreSchema() and resolves a table's column structure (no row data).",
+      "Injected @colixsystems/datastore-client instance. " +
+      "{ tables: { list(), get(idOrName) }, schema(tableId) -> Promise<{ id, name, columns: [...] }>, " +
+      "records(tableId) -> { list(query) -> Promise<{ data, meta }>, get(id), create(values), update(id, values), delete(id), aggregate(spec), " +
+      "permissions(recordId) -> { list() -> Promise<{ data, meta }>, grant(body), update(permId, patch), revoke(permId) } } }. " +
+      "`records` backs the query/record/mutation hooks; `records(t).permissions(r)` backs useRecordPermissions(); `schema` backs useDatastoreSchema(). " +
+      "List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case (author column values keep their author-given names).",
     required: true,
-    fields: { records: "function", schema: "function" },
+    fields: { records: "function", schema: "function", tables: "object" },
   },
   directory: {
     description:
-      "Read-only user directory. { listUsers(query?) -> Promise<Array<{ id, name, role }>> }. Backs useDirectory(); for chat people-lists / @-mention pickers / author-id resolution. Requires the directory.read:users scope.",
+      "Injected @colixsystems/directory-client instance. " +
+      "{ me(), users: { list(query?) -> Promise<{ data, meta }>, get(id), invite(body), deactivate(id), reactivate(id) }, " +
+      "groups: { list(query?) -> Promise<{ data, meta }>, create(body), remove(id), addMember(groupId, userId), removeMember(groupId, userId), listMine() }, " +
+      "invites: { list(), revoke(id), resend(id) } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(). List methods return the { data, meta } envelope verbatim (hooks unwrap res.data); rows/bodies are snake_case. Reads gated by directory.read:users / users.read:* / groups.read:*; mutations by users.write:* / groups.write:*.",
     required: true,
-    fields: { listUsers: "function" },
+    fields: { users: "object", groups: "object" },
   },
   files: {
     description:
-      "Read-only asset resolver. { get(fileId) -> Promise<{ id, url, storedFilename, mimeType, sizeBytes, ... }> }. Backs useFile(); resolves an asset id to an absolute URL the widget can drop into an <Image source>. The url field is always an absolute URL composed against the host's API base.",
+      "Injected @colixsystems/files-client instance, FLATTENED so file ops are top-level. " +
+      "{ get(id) -> Promise<{ id, url, ... }>, list(query) -> Promise<{ data, meta }>, upload(formData), folders: { list, create }, shares: { list, create, remove } }. " +
+      "Backs useFile(); the returned file already carries an absolute url the widget can drop into an <Image source>.",
     required: true,
     fields: { get: "function" },
   },
@@ -610,62 +698,17 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   payments: {
     description:
-      "Incoming app-user payments (REQ-BILL-07-WIDGETPAY). { requestPayment({ amountCents, currency?, description, metadata? }) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
+      "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status, checkoutUrl? }>, getPayment(id) -> Promise<payment> }. Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
     required: true,
     fields: { requestPayment: "function", getPayment: "function" },
   },
-  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration facade backing
-  // useUsers(). Reads gated by `users.read:*`; mutations by `users.write:*`.
-  // The host signs an `X-Widget-Scopes` header against JWT_SECRET so an
-  // APP_USER cannot forge scope claims, and the request is additionally
-  // gated by a SystemAcl `users.read` / `users.write` capability grant.
-  users: {
-    description:
-      "AppUser administration. { listUsers(query?) -> Promise<User[]>, invite({ email, name, groupIds? }) -> Promise<Invite>, deactivate(userId) -> Promise<User>, reactivate(userId) -> Promise<User>, remove(userId) -> Promise<void> }. Backs useUsers(); reads require users.read:*, mutations require users.write:*.",
-    required: true,
-    fields: {
-      listUsers: "function",
-      invite: "function",
-      deactivate: "function",
-      reactivate: "function",
-      remove: "function",
-    },
-  },
-  // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
-  // management facade backing useRecordPermissions(). Mirror of
-  // contract.js.
-  recordPermissions: {
-    description:
-      "Per-record VirtualPermission management. " +
-      "{ list(tableId, recordId) -> Promise<RecordPermission[]>, " +
-      "grant(tableId, recordId, body) -> Promise<RecordPermission>, " +
-      "revoke(tableId, recordId, permissionId) -> Promise<void>, " +
-      "update(tableId, recordId, permissionId, body) -> Promise<RecordPermission> }. " +
-      "Backs useRecordPermissions(); requires acl.write:records scope AND " +
-      "canGrant on the target record.",
-    required: true,
-    fields: {
-      list: "function",
-      grant: "function",
-      revoke: "function",
-      update: "function",
-    },
-  },
-  // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration facade
-  // backing useGroups(). Reads gated by `groups.read:*`; mutations by
-  // `groups.write:*`. Same X-Widget-Scopes + SystemAcl gating as users.
-  groups: {
-    description:
-      "AppUserGroup administration. { listGroups(query?) -> Promise<Group[]>, create({ name }) -> Promise<Group>, remove(groupId) -> Promise<void>, addMember(groupId, userId) -> Promise<void>, removeMember(groupId, userId) -> Promise<void> }. Backs useGroups(); reads require groups.read:*, mutations require groups.write:*.",
-    required: true,
-    fields: {
-      listGroups: "function",
-      create: "function",
-      remove: "function",
-      addMember: "function",
-      removeMember: "function",
-    },
-  },
+  // REQ-WSDK-DOMAIN-CLIENTS — the AppUser administration, AppUserGroup
+  // administration, and per-record VirtualPermission facades that used to
+  // live here (`users`, `groups`, `recordPermissions`) were folded into the
+  // injected domain-client instances: useUsers()/useGroups() read
+  // ctx.directory.{users,groups}; useRecordPermissions() reads
+  // ctx.datastore.records(table).permissions(record). See the `directory`
+  // and `datastore` slices above.
   i18n: {
     description: "{ t(key, fallback?), locale }.",
     required: true,
@@ -898,6 +941,20 @@ function deepFreeze(value) {
   return Object.freeze(value);
 }
 
+// REQ-L10N-WIDGET — a widget's manifest `translations` are merged into the
+// tenant dictionary under a per-widget namespace so they never collide with
+// app keys or another widget's keys. The prefix is DERIVED from the widget id
+// (it "follows the widget"), so authors call `t("greeting")` and the host
+// resolves `widget.<id>.greeting`. This is the ONE definition of the key
+// format: the SDK `useI18n` hook (lookup) and the backend seeder (write) both
+// call it, so the wire key and the lookup key can never drift.
+function widgetTranslationPrefix(id) {
+  return `widget.${id}.`;
+}
+function widgetTranslationKey(id, key) {
+  return `widget.${id}.${key}`;
+}
+
 const CONTRACT = deepFreeze({
   // REQ-WSDK-PLATFORM bump:
   //   - `vettedImports` is a new field (rich allowlist with platforms +
@@ -921,19 +978,71 @@ const CONTRACT = deepFreeze({
   // runtime (Form Builder renders inputs by column type). Reads the existing
   // ACL-gated `GET /tables/:id` — structure only, no row data.
   //
-  // 1.8.0: additive — new `useRecordPermissions(tableId, recordId)` hook +
-  // the `recordPermissions` host-context slice it reads + the
-  // `acl.write:records` scope it gates on. Hits the existing REQ-ACL-06
-  // /api/v1/tables/:tableId/records/:recordId/permissions REST surface; the
-  // host normalises the wire shape into a single principalType+principalId
-  // pair widgets branch on. Caller still needs canGrant on the target
-  // record (REQ-ACL-RELINHERIT-05).
-  version: "1.8.0",
+  // 1.8.0: two additive features.
+  //  - REQ-WIDGET-ACTION — manifests may declare an optional `actions` array.
+  //    Each entry is a server-side action (cron- or record-triggered JS) the
+  //    operator enables per tenant; it runs in the existing isolated-vm action
+  //    runner, never in the rendered app. New contract fields
+  //    `actionTriggerTypes`, `actionScriptGlobals`, and `actionScriptMaxBytes`
+  //    let the docs + agent prompt + validator derive the grammar from one
+  //    source. New `ADMINISTRATION` manifest category (REQ-USERMGMT-06).
+  //  - REQ-ACL-06 — new `useRecordPermissions(tableId, recordId)` hook + the
+  //    `recordPermissions` host-context slice it reads + the `acl.write:records`
+  //    scope it gates on. Hits the existing REQ-ACL-06
+  //    /api/v1/tables/:tableId/records/:recordId/permissions REST surface; the
+  //    host normalises the wire shape into a single principalType+principalId
+  //    pair widgets branch on. Caller still needs canGrant on the target
+  //    record (REQ-ACL-RELINHERIT-05).
+  //
+  // 1.9.0: host-contract change (REQ-WSDK-DOMAIN-CLIENTS) — the host now
+  //    injects domain-client INSTANCES on the WidgetContext rather than
+  //    bespoke per-hook facades. ctx.datastore is a @colixsystems/datastore-client
+  //    (records(t).list now returns the { data, meta } envelope verbatim;
+  //    records(t).permissions(r) replaces the deleted ctx.recordPermissions),
+  //    ctx.directory is a @colixsystems/directory-client (users/groups
+  //    namespaces replace the deleted ctx.users / ctx.groups; list returns
+  //    envelopes), ctx.files is a flattened @colixsystems/files-client,
+  //    ctx.payments is a @colixsystems/payments-client. All rows/bodies are
+  //    snake_case. Hooks now unwrap the list envelope (res.data ?? []). The
+  //    SDK stays duck-typed — it imports none of the four data SDKs. Minor
+  //    bump on the contract's pre-1.0 versioning (the breaking channel).
+  //
+  // 1.10.0: additive (REQ-L10N-WIDGET) — manifests may declare an optional
+  //    `translations` map ({ <key>: { en, <locale>? } }, en required). The
+  //    host seeds them into the tenant l10n dictionary under a per-widget
+  //    namespace at install; `useI18n().t(key)` now auto-prefixes the lookup
+  //    with `widget.<ctx.widget.id>.` (then falls back to the raw key, so
+  //    existing widgets and shared app keys keep resolving). New exported
+  //    helpers widgetTranslationPrefix / widgetTranslationKey are the single
+  //    source of the key format, shared by the hook and the backend seeder.
+  //
+  // 1.11.0: additive (REQ-LAY-08) — new useFill() hook + the optional `fill`
+  //    host-context slice it reads. The host sets ctx.fill=true when it has
+  //    sized a widget to fill its layout slot's available height (a page-grid
+  //    tile whose author chose "Fill tile height", or a default-fill widget
+  //    type — containers + media). Widgets that can stretch (Image, Chart,
+  //    Map, Video) switch to flex:1/height:"100%" when useFill() is true; all
+  //    others ignore it. The slice is OPTIONAL (defaults false) so existing
+  //    hosts need no change, and the same value is injected on web and native
+  //    so fill behaviour cannot diverge between the Player and the export.
+  //
+  // 1.11.1: fix — the canonical default `themeTokens.colors` now match the
+  //    product's advertised default brand (primary #3b82f6 blue, secondary
+  //    #10b981 green) instead of the stale coral/slate that no other surface
+  //    used. The Theme Settings tab and Player chrome already defaulted to
+  //    these values, so a tenant that never customised its theme rendered
+  //    widgets in coral until a first save persisted the blue — a divergence
+  //    between the unsaved and saved-defaults render. Aligning the canonical
+  //    tokens removes it (no shape/signature change — default-value fix only).
+  version: "1.11.1",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,
   manifestCategories: CATEGORIES,
   manifestPlatforms: PLATFORMS,
+  actionTriggerTypes: ACTION_TRIGGER_TYPES,
+  actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
+  actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
   themeTokens: DEFAULT_THEME_TOKENS,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
@@ -957,4 +1066,10 @@ function requiredContextKeys() {
   return [...keys];
 }
 
-module.exports = { CONTRACT, isHookAllowed, requiredContextKeys };
+module.exports = {
+  CONTRACT,
+  isHookAllowed,
+  requiredContextKeys,
+  widgetTranslationPrefix,
+  widgetTranslationKey,
+};