@colixsystems/widget-sdk 0.80.0 → 0.82.0

package/README.md

@@ -24,6 +24,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
+| **CORE** | `useWidgetInput(inputName)` | the published payload, or `undefined` | `ctx.inputs` — no scope. Reads a value ANOTHER widget on the same page published with `useWidgetEvent`. Declare the input in `manifest.inputs`; the page author wires it to one sibling's declared event. The channel retains the last payload, so a widget that mounts later still reads it. `undefined` while unwired or before the first publish — always render a sensible default. Page-scoped and ephemeral: use `useRouteParams()` for state that must survive navigation, the datastore for state that must persist. |
 | **CORE** | `useChildRenderer()` | `{ renderNode(node) }` | `ctx.renderer` — no scope (prefer the `WidgetTree` component) |
 | **CORE** | `useFill()` | `boolean` | `ctx.fill` — no scope. `true` when the host sized this widget to fill its page-grid tile's reserved height (containers + media fill by default; the author can override per tile). Media-style widgets switch to a `flex: 1` / `height: "100%"` layout; others ignore it. Defaults `false`. |
 | **CORE** | `useContainerWidth()` | `[width, onLayout]` | No context slice, no scope. Measures the width the widget's OWN box has, so it can lay itself out for the space it is in rather than for the screen. Spread the handler onto your outermost primitive. Use it for any widget with a wide form and a narrow one (a table, a toolbar, a row of tiles) — never switch on the device or window width, because a widget in a one-of-three grid cell on desktop has phone-width room and a widget filling a phone page does not. Width is 0 until the first layout: render the WIDE form then. One implementation covers web (react-native-web) and the native export. |
@@ -61,6 +62,14 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `v0.77.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.82.0 (contract 1.57.0)
+
+**Server-action scripts can notify a record's permission subjects (REQ-ACTION-NOTIFY-SUBJECTS, sc-4586).** `await notifications.notifyRecordSubjects(tableId, recordId, { title, body, link, emit_email, emit_push, exclude_user_id })` resolves to `{ recipients }` and notifies every app user whose per-record grant lets them **read** that record. This addresses the one audience the other two primitives cannot name: when membership *is* the ACL, there is no recipient column to read. The Chat widget is the case in point — a channel's participants ARE that channel record's grants, so neither a `recipient_expr` (which resolves only a fixed id or a single user/group reference column) nor a `notifyUser` loop over a column that does not exist can reach them. Subject kinds follow REQ-ACL-09: a `user` grant notifies its user, a `group` grant expands through its memberships, and the two synthetic kinds (`authenticated`, `everyone`) are skipped because they address the whole workspace rather than a membership. Recipients are **deduplicated**, so someone reachable through both a direct grant and a granted group is notified once, and `exclude_user_id` drops one — pass the author so nobody is notified of their own write. Dispatch goes through the same `notifyUser` path as before, so the always-written inbox row, the preference-gated email + push mirrors, the link sanitiser and the title/body caps are inherited unchanged, and written rows count toward the same per-run cap of 500. The tenant is bound host-side and the table/record pair is verified against it, so a foreign or missing id resolves to `{ recipients: 0 }` rather than distinguishing "absent" from "not yours". **The script never receives the member list — only the count.** `CONTRACT.version` → `1.57.0`. Additive; no widget hook, primitive, manifest field, or token changed shape.
+
+### 0.82.0 also carries (contract 1.56.0)
+
+**Server-action scripts gain a `notifications` global (REQ-ACTION-NOTIFY, sc-4514).** A `scriptSource` action can now send a real notification to a recipient it resolves at run time: `await notifications.notifyUser(userId, { title, body, link, emit_email, emit_push })` and `await notifications.notifyGroup(groupId, opts)`. Options are **snake_case**, matching every other shape a script sees. `notifyUser` resolves to the created notification row (or `null` when the recipient was skipped); `notifyGroup` resolves to `{ recipients }`. This is a directness change rather than a new capability: an action could already notify indirectly by writing into a table carrying an enabled `NotificationRule`, but that costs a throwaway table, a per-table rule, a recipient expressible only as a fixed id or one reference column — and it fails silently, since with no rule attached the row just lands and the run still reports success. `POST /notifications/send` is no alternative (it needs an app-user JWT an action cannot hold). The direct call removes the intermediary and makes a non-delivery throw. Both methods delegate to the platform's one notification dispatch path, so the inbox row is always written, the email + push mirrors respect the recipient's channel preferences, and the push ping never carries the title or body. The tenant is bound host-side: a recipient in another workspace, a soft-deleted group, or a deactivated user is a silent skip, never a cross-tenant write. A blank `title`, a non-string `body`, or exceeding the per-run cap of 500 written notifications throws a catchable Error. New entry in `CONTRACT.actionScriptGlobals`; `CONTRACT.version` → `1.56.0`. Additive — no widget hook, primitive, manifest field, or token changed shape.
+
 ### What's new in 0.78.0
 
 **New `useIdentification()` hook — identify a visitor who is NOT signed in (REQ-IDENT, sc-4313).** A new IDENTIFICATION hook reading a newly-injected `ctx.identification` slice (the new `@colixsystems/identification-client`, constructed by both the web Player and the native Expo export). Returns `{ available, availabilityLoading, status, qr, autoStartToken, message, identity, identificationId, loading, error, start, refresh, cancel, reset }`.
@@ -619,7 +628,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 
 - `defineWidget({ manifest, component })` — validates the manifest and produces a widget module the host can register.
 - `validateManifest(m)` / `validatePropertySchema(s)` / `validateProps(schema, props)` — shape validation; no third-party deps.
-- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case).
+- `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreSchema`, `useDatastoreMutation`, `useDirectory`, `useUsers`, `useGroups`, `useRecordPermissions`, `useAsset`, `useWidgetEvent`, `useWidgetInput`, `usePayments`, `useSendNotification`, `useTheme`, `useI18n`, `useUser`, `useNavigation`, `useRouteParams`, `usePageContext`, `useChildRenderer`, `useClipboard`, `useToast` — hooks that read from the host-provided `WidgetContext` (or, for `useClipboard`, the platform clipboard API directly). `useDirectory(query?)` returns `{ users, loading, error, refetch }` (each user `{ id, name, role }`) and requires the `directory.read:users` scope. `useUsers(query?)` returns `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }` and requires `users.read:*` (mutations also need `users.write:*`); rejections are a `DirectoryError`. `useGroups(query?)` returns `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` and requires `groups.read:*` (mutations also need `groups.write:*`). `usePayments()` returns `{ requestPayment, getPayment }` and requires the `payments.charge:appUser` scope; `requestPayment(...)` rejects with a `PaymentError`. `useSendNotification()` returns `{ send, sending, error }` and requires the `notifications.send:appUser` scope; `send({ recipient_user_id, title, body, link?, payload? })` notifies one app user in the same workspace (cross-workspace `recipient_user_id` is rejected), must be called from an event handler rather than render, and rejects with a `NotificationError`. `useUser()` returns the active end-user identity `{ id, email, displayName, roles, groupIds }` (camelCase — the host-built context object, not a wire payload; `id` is `null` for anonymous / preview). `useNavigation()` returns `{ goTo, goBack, push, replace, back, currentRoute }` for internal page navigation — for external URLs use the `Linking` primitive (`Linking.openURL(url)`). `useRouteParams()` returns the current route's params object (`currentRoute.params`) — the flat master→detail accessor; read a param off it (e.g. `recordId`), never call it. `useDatastoreRecord(tableId, recordId)` returns `{ data, loading, error, refetch }` for a single record (data is one row or null). `useDatastoreSchema(tableId)` returns `{ schema, loading, error, refetch }` where `schema` is `{ id, name, columns: [{ id, name, data_type, required, relation_type, target_table_id, is_identification }] }` (structure only, no row data; snake_case verbatim) — use it to resolve a stored `columnId` to its column type at runtime; requires the `datastore.read:<table>` scope. `useAsset(fileId)` returns `{ url, file, loading, error, refetch }` — the `url` is an absolute URL composed against the host's API base. `useChildRenderer()` returns `{ renderNode(node) }` — container widgets call it to render arbitrary child page-tree nodes (prefer the `WidgetTree` component for the common case). `useWidgetInput(inputName)` returns the latest payload a sibling widget published on the event the page author wired to this widget's declared `inputs` entry (`undefined` when unwired or not yet published).
 - `WidgetTree({ node })` — component that renders an author-authored child node through the host's renderer; used by Tabs / Card / custom containers to host arbitrary child widgets.
 - `Text`, `View`, `Pressable`, `Image`, `ScrollView`, `TextInput`, `FlatList`, `SectionList`, `ActivityIndicator`, `Switch`, `StyleSheet`, `Linking`, `Icon`, `DateTimePicker` — re-exported from `react-native` (the RN primitives) or implemented in the SDK (`Icon` wraps `lucide-react-native`; `DateTimePicker` wraps `@react-native-community/datetimepicker` on native and renders `<input type="date|time|datetime-local">` directly on web because the RN library has no react-native-web mapping). The web build aliases `react-native` to `react-native-web` so the RN-re-exported primitives render in the browser without any per-platform code; the exported Expo app's Metro bundler resolves the real `react-native` library. `Linking` is a static API (`Linking.openURL(url)`) — use it for external URLs, and use `useNavigation().goTo(pageId)` for internal page navigation. See https://reactnative.dev/docs/ for per-component props.
 - `WidgetContextProvider` — React context provider that the host (Studio, Player, exported app) wraps widgets with.

package/dist/contract.cjs

@@ -226,6 +226,17 @@ const THEME_COMPONENTS = Object.freeze({
   }),
 });
 
+// sc-4505 — the value types a widget event payload field may declare. Narrower
+// than propertySchema VALID_TYPES on purpose: a payload is DATA that crosses to
+// the native export, so it is the JSON-serializable set, not the editor set.
+const PAYLOAD_VALUE_TYPES = Object.freeze([
+  "string",
+  "number",
+  "boolean",
+  "object",
+  "array",
+]);
+
 const HOOKS = [
   {
     name: "useTheme",
@@ -775,6 +786,18 @@ const HOOKS = [
     requiredContextSlice: ["events.emit"],
     scopes: null,
   },
+  {
+    name: "useWidgetInput",
+    signature: "useWidgetInput(inputName)",
+    returnShape: {
+      value:
+        "The latest payload published on the sibling event this input is " +
+        "wired to, or undefined until the producer has published. The hook " +
+        "returns the value itself, not a wrapper.",
+    },
+    requiredContextSlice: ["inputs.subscribe"],
+    scopes: null,
+  },
   {
     name: "usePayments",
     signature: "usePayments()",
@@ -1246,6 +1269,7 @@ const ACTION_SCRIPT_GLOBALS = [
   "secrets",
   "fetch",
   "connectors",
+  "notifications",
   "console",
   "record",
   "tenantId",
@@ -1352,7 +1376,25 @@ const MANIFEST_SCHEMA = {
   events: {
     type: "object[]",
     required: true,
-    description: "Declared events. Each entry { name, payloadSchema? }.",
+    description:
+      "Declared events the widget publishes. Each entry { name, description?, " +
+      "payloadSchema? }. payloadSchema is a FLAT map of payload field name to " +
+      "{ type, label? } — the SAME shape as propertySchema, NOT JSON Schema — " +
+      "where type is one of string, number, boolean, object, array. The payload reaches " +
+      "any sibling widget on the page whose inputs entry the page author wired " +
+      "to this event.",
+    default: [],
+  },
+  inputs: {
+    type: "object[]",
+    required: false,
+    description:
+      "Optional. Values this widget CONSUMES from a sibling widget on the same " +
+      "page. Each entry { name, description?, schema? }; schema is the same flat " +
+      "{ field: { type, label? } } map as events[].payloadSchema. The page author " +
+      "wires each input to ONE sibling widget event; the widget reads the latest " +
+      "published payload with useWidgetInput(name). An unwired input reads " +
+      "undefined, so a widget must always render a sensible default.",
     default: [],
   },
   datastoreTemplate: {
@@ -1520,6 +1562,18 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { emit: "function" },
   },
+  inputs: {
+    description:
+      "{ get(name), subscribe(name, handler) } — the page-scoped input wiring " +
+      "ALREADY RESOLVED for this widget instance, so widget code never sees node " +
+      "ids. get() returns the retained value (undefined when unwired); " +
+      "subscribe() returns an unsubscribe function. The host MUST keep this " +
+      "slice referentially STABLE for a given set of author bindings — " +
+      "useWidgetInput depends on the reference to decide when to resubscribe. " +
+      "Backs useWidgetInput().",
+    required: true,
+    fields: { get: "function", subscribe: "function" },
+  },
   payments: {
     description:
       "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment> }; wire is snake_case (amount_cents, return_path). Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
@@ -2453,7 +2507,24 @@ const CONTRACT = deepFreeze({
   //    already measured its own box with onLayout; this promotes that one
   //    pattern to the SDK so custom and marketplace widgets get it too,
   //    instead of each rolling its own.
-  version: "1.54.0",
+  // 1.55.0: additive (sc-4505) — `useWidgetInput(inputName)` + the
+  //    `PAYLOAD_VALUE_TYPES` a widget event payload field may declare, so
+  //    widgets on one page relate through declared inputs.
+  // 1.56.0: additive (sc-4514) — `notifications` joins
+  //    `actionScriptGlobals`. `notifications.notifyUser(id, opts)` /
+  //    `notifyGroup(id, opts)` delegate to the one notification dispatch path.
+  //    Directness, not a new capability: an action could already notify by
+  //    writing into a table carrying a NotificationRule, but that needs a
+  //    throwaway table plus a per-table rule and fails SILENTLY when no rule
+  //    is attached — the row lands and the run still reports success.
+  // 1.57.0: additive (sc-4586) — `notifications.notifyRecordSubjects(tableId,
+  //    recordId, opts)`, resolving to { recipients }. Notifies whoever a
+  //    record's per-record grants let read it, which is the only way to address
+  //    membership-by-ACL: a Chat channel's participants ARE its grants, so no
+  //    `recipient_expr` shape and no recipient column can name them. The member
+  //    list stays host-side — a script receives a count, never the ids — and
+  //    `exclude_user_id` keeps an author off their own message.
+  version: "1.57.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2474,6 +2545,7 @@ const CONTRACT = deepFreeze({
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
+  payloadValueTypes: PAYLOAD_VALUE_TYPES,
   translationApiHosts: TRANSLATION_API_HOSTS,
 });
 

package/dist/contract.js

@@ -226,6 +226,17 @@ const THEME_COMPONENTS = Object.freeze({
   }),
 });
 
+// sc-4505 — the value types a widget event payload field may declare. Narrower
+// than propertySchema VALID_TYPES on purpose: a payload is DATA that crosses to
+// the native export, so it is the JSON-serializable set, not the editor set.
+const PAYLOAD_VALUE_TYPES = Object.freeze([
+  "string",
+  "number",
+  "boolean",
+  "object",
+  "array",
+]);
+
 const HOOKS = [
   {
     name: "useTheme",
@@ -775,6 +786,18 @@ const HOOKS = [
     requiredContextSlice: ["events.emit"],
     scopes: null,
   },
+  {
+    name: "useWidgetInput",
+    signature: "useWidgetInput(inputName)",
+    returnShape: {
+      value:
+        "The latest payload published on the sibling event this input is " +
+        "wired to, or undefined until the producer has published. The hook " +
+        "returns the value itself, not a wrapper.",
+    },
+    requiredContextSlice: ["inputs.subscribe"],
+    scopes: null,
+  },
   {
     name: "usePayments",
     signature: "usePayments()",
@@ -1246,6 +1269,7 @@ const ACTION_SCRIPT_GLOBALS = [
   "secrets",
   "fetch",
   "connectors",
+  "notifications",
   "console",
   "record",
   "tenantId",
@@ -1352,7 +1376,25 @@ const MANIFEST_SCHEMA = {
   events: {
     type: "object[]",
     required: true,
-    description: "Declared events. Each entry { name, payloadSchema? }.",
+    description:
+      "Declared events the widget publishes. Each entry { name, description?, " +
+      "payloadSchema? }. payloadSchema is a FLAT map of payload field name to " +
+      "{ type, label? } — the SAME shape as propertySchema, NOT JSON Schema — " +
+      "where type is one of string, number, boolean, object, array. The payload reaches " +
+      "any sibling widget on the page whose inputs entry the page author wired " +
+      "to this event.",
+    default: [],
+  },
+  inputs: {
+    type: "object[]",
+    required: false,
+    description:
+      "Optional. Values this widget CONSUMES from a sibling widget on the same " +
+      "page. Each entry { name, description?, schema? }; schema is the same flat " +
+      "{ field: { type, label? } } map as events[].payloadSchema. The page author " +
+      "wires each input to ONE sibling widget event; the widget reads the latest " +
+      "published payload with useWidgetInput(name). An unwired input reads " +
+      "undefined, so a widget must always render a sensible default.",
     default: [],
   },
   datastoreTemplate: {
@@ -1520,6 +1562,18 @@ const WIDGET_CONTEXT_SHAPE = {
     required: true,
     fields: { emit: "function" },
   },
+  inputs: {
+    description:
+      "{ get(name), subscribe(name, handler) } — the page-scoped input wiring " +
+      "ALREADY RESOLVED for this widget instance, so widget code never sees node " +
+      "ids. get() returns the retained value (undefined when unwired); " +
+      "subscribe() returns an unsubscribe function. The host MUST keep this " +
+      "slice referentially STABLE for a given set of author bindings — " +
+      "useWidgetInput depends on the reference to decide when to resubscribe. " +
+      "Backs useWidgetInput().",
+    required: true,
+    fields: { get: "function", subscribe: "function" },
+  },
   payments: {
     description:
       "Injected @colixsystems/payments-client instance (REQ-BILL-07-WIDGETPAY). { requestPayment(body) -> Promise<{ id, status }>, getPayment(id) -> Promise<payment> }; wire is snake_case (amount_cents, return_path). Backs usePayments(); requires the payments.charge:appUser scope. The host opens hosted Checkout itself — same-tab on web, in-app browser on native (or auto-confirms under the mock provider); the charge settles to the workspace owner.",
@@ -2453,7 +2507,24 @@ const CONTRACT = deepFreeze({
   //    already measured its own box with onLayout; this promotes that one
   //    pattern to the SDK so custom and marketplace widgets get it too,
   //    instead of each rolling its own.
-  version: "1.54.0",
+  // 1.55.0: additive (sc-4505) — `useWidgetInput(inputName)` + the
+  //    `PAYLOAD_VALUE_TYPES` a widget event payload field may declare, so
+  //    widgets on one page relate through declared inputs.
+  // 1.56.0: additive (sc-4514) — `notifications` joins
+  //    `actionScriptGlobals`. `notifications.notifyUser(id, opts)` /
+  //    `notifyGroup(id, opts)` delegate to the one notification dispatch path.
+  //    Directness, not a new capability: an action could already notify by
+  //    writing into a table carrying a NotificationRule, but that needs a
+  //    throwaway table plus a per-table rule and fails SILENTLY when no rule
+  //    is attached — the row lands and the run still reports success.
+  // 1.57.0: additive (sc-4586) — `notifications.notifyRecordSubjects(tableId,
+  //    recordId, opts)`, resolving to { recipients }. Notifies whoever a
+  //    record's per-record grants let read it, which is the only way to address
+  //    membership-by-ACL: a Chat channel's participants ARE its grants, so no
+  //    `recipient_expr` shape and no recipient column can name them. The member
+  //    list stays host-side — a script receives a count, never the ids — and
+  //    `exclude_user_id` keeps an author off their own message.
+  version: "1.57.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2474,6 +2545,7 @@ const CONTRACT = deepFreeze({
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,
   hostApiUrlPatterns: HOST_API_URL_PATTERNS,
+  payloadValueTypes: PAYLOAD_VALUE_TYPES,
   translationApiHosts: TRANSLATION_API_HOSTS,
 });
 

package/dist/hooks.js

@@ -80,6 +80,55 @@ export function useWidgetEvent(name) {
   return useCallback((payload) => ctx.events.emit(name, payload), [ctx, name]);
 }
 
+/**
+ * sc-4505 — read a value published by ANOTHER widget on the same page.
+ *
+ * The page author wires this widget's manifest-declared `inputs` entry to one
+ * sibling widget's declared event, so widget code names only its OWN input and
+ * never learns which widget feeds it:
+ *
+ *   const period = useWidgetInput("period");   // { month: "2027-02" } | undefined
+ *
+ * The channel RETAINS the last published payload, so a widget that mounts after
+ * the producer published (a tab switch, a lazily rendered section) still reads
+ * it. An input the author has not wired — and one whose producer has not
+ * published yet — reads `undefined`, so a widget must always render a sensible
+ * default rather than an empty state.
+ *
+ * The value is page-scoped and ephemeral: it is gone once the page unmounts.
+ * For state that must survive navigation read `useRouteParams()`; for state
+ * that must persist, write it to the datastore.
+ */
+export function useWidgetInput(inputName) {
+  const ctx = useWidgetContextOrThrow("useWidgetInput");
+  // The host keeps `ctx.inputs` referentially stable for a given set of author
+  // bindings (CONTRACT.widgetContextShape.inputs), so depending on it here
+  // resubscribes when — and only when — the wiring actually changes.
+  const inputs = ctx.inputs;
+  const [value, setValue] = useState(() => readInput(inputs, inputName));
+
+  useEffect(() => {
+    if (!inputs || typeof inputs.subscribe !== "function") {
+      setValue(undefined);
+      return undefined;
+    }
+    // The producer may have published between the initial render and this
+    // effect, so re-read rather than waiting for the next publish.
+    setValue(readInput(inputs, inputName));
+    // `() => next` so a payload that is itself a function can never be
+    // mistaken for a React state updater.
+    return inputs.subscribe(inputName, (next) => setValue(() => next));
+  }, [inputs, inputName]);
+
+  return value;
+}
+
+function readInput(inputs, inputName) {
+  return inputs && typeof inputs.get === "function"
+    ? inputs.get(inputName)
+    : undefined;
+}
+
 /**
  * Returns the host-provided theme tokens. The host guarantees every field
  * documented in CONTRACT.themeTokens is present (defaults merged with

package/dist/index.d.ts

@@ -124,6 +124,17 @@ export interface WidgetEventDescriptor {
   payloadSchema?: WidgetPropertySchema;
 }
 
+/**
+ * A value the widget CONSUMES from a sibling widget on the same page. The page
+ * author wires each input to one sibling event; the widget reads the latest
+ * published payload with `useWidgetInput(name)`.
+ */
+export interface WidgetInputDescriptor {
+  name: string;
+  description?: string;
+  schema?: WidgetPropertySchema;
+}
+
 /**
  * Optional datastore template a widget can ship in its manifest. When the
  * tenant installs the widget, every declared table is created in their
@@ -249,6 +260,11 @@ export interface WidgetManifest {
    */
   styleSchema?: WidgetPropertySchema;
   events: WidgetEventDescriptor[];
+  /**
+   * Optional (sc-4505). Values this widget reads from a sibling widget on the
+   * same page, wired by the page author. Read each with `useWidgetInput(name)`.
+   */
+  inputs?: WidgetInputDescriptor[];
   /**
    * Optional datastore template seeded into the tenant's workspace when
    * the widget is installed. The author wires the resulting tables into
@@ -703,6 +719,13 @@ export function useDirectory(query?: DirectoryQuery): DirectoryResult;
 
 export function useWidgetEvent(name: string): (payload?: unknown) => void;
 
+/**
+ * Reads the latest payload published on the sibling event this widget input is
+ * wired to. `undefined` until the producer publishes, and for an unwired input
+ * — so always render a sensible default. Page-scoped and ephemeral.
+ */
+export function useWidgetInput(inputName: string): unknown;
+
 /**
  * Arguments for `usePayments().requestPayment(...)`. snake_case VERBATIM —
  * this is the wire contract (REQ-GEN-09). `amount_cents` is the charge in the

package/dist/index.js

@@ -36,6 +36,7 @@ export {
   useRecordPermissions,
   useDatastoreSubscription,
   useWidgetEvent,
+  useWidgetInput,
   usePayments,
   useSendNotification,
   useTheme,

package/dist/index.native.js

@@ -36,6 +36,7 @@ export {
   useRecordPermissions,
   useDatastoreSubscription,
   useWidgetEvent,
+  useWidgetInput,
   usePayments,
   useSendNotification,
   useTheme,

package/dist/manifest.cjs

@@ -4,6 +4,35 @@
 // re-exports the same functions defined here so there is exactly one
 // implementation.
 
+const { CONTRACT } = require("./contract.cjs");
+
+const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
+
+// sc-4505 — a payload / input field map: { <field>: { type, label? } }. This is
+// the FLAT propertySchema-style shape index.d.ts already types, NOT JSON Schema.
+// `type` is restricted to the JSON-serializable set because a payload crosses
+// to the exported Expo app (CLAUDE.md §8).
+function validatePayloadFieldMap(schema, label, errors) {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+    errors.push(`${label} must be an object mapping field name to { type }`);
+    return;
+  }
+  for (const [field, def] of Object.entries(schema)) {
+    if (def === null || typeof def !== "object" || Array.isArray(def)) {
+      errors.push(`${label}.${field} must be an object`);
+      continue;
+    }
+    if (!PAYLOAD_VALUE_TYPES.includes(def.type)) {
+      errors.push(
+        `${label}.${field}.type must be one of ${PAYLOAD_VALUE_TYPES.join(", ")}`,
+      );
+    }
+    if (def.label !== undefined && typeof def.label !== "string") {
+      errors.push(`${label}.${field}.label must be a string when present`);
+    }
+  }
+}
+
 const VALID_CATEGORIES = new Set([
   "input", "display", "layout", "data", "media", "communication", "administration", "custom",
   "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "ADMINISTRATION", "CUSTOM",
@@ -275,6 +304,52 @@ function validateManifest(m) {
       }
       if (!isNonEmptyString(e.name)) {
         errors.push("manifest.events[].name must be a non-empty string");
+        continue;
+      }
+      if (e.description !== undefined && !isNonEmptyString(e.description)) {
+        errors.push(
+          `manifest.events[${e.name}].description must be a non-empty string when present`,
+        );
+      }
+      if (e.payloadSchema !== undefined) {
+        validatePayloadFieldMap(
+          e.payloadSchema,
+          `manifest.events[${e.name}].payloadSchema`,
+          errors,
+        );
+      }
+    }
+  }
+
+  // sc-4505 — `inputs` is optional (additive). Declares the values this widget
+  // CONSUMES from a sibling widget event, wired by the page author.
+  if (manifest.inputs !== undefined) {
+    if (!Array.isArray(manifest.inputs)) {
+      errors.push("manifest.inputs must be an array (use [] for none)");
+    } else {
+      const seenInputs = new Set();
+      for (const i of manifest.inputs) {
+        if (i === null || typeof i !== "object" || Array.isArray(i)) {
+          errors.push("manifest.inputs entries must be objects");
+          break;
+        }
+        if (!isNonEmptyString(i.name)) {
+          errors.push("manifest.inputs[].name must be a non-empty string");
+          continue;
+        }
+        // A duplicate name would make the author-facing wiring ambiguous.
+        if (seenInputs.has(i.name)) {
+          errors.push(`manifest.inputs[].name "${i.name}" is declared twice`);
+        }
+        seenInputs.add(i.name);
+        if (i.description !== undefined && !isNonEmptyString(i.description)) {
+          errors.push(
+            `manifest.inputs[${i.name}].description must be a non-empty string when present`,
+          );
+        }
+        if (i.schema !== undefined) {
+          validatePayloadFieldMap(i.schema, `manifest.inputs[${i.name}].schema`, errors);
+        }
       }
     }
   }

package/dist/manifest.js

@@ -4,6 +4,35 @@
 // re-exports the same functions defined here so there is exactly one
 // implementation.
 
+import { CONTRACT } from "./contract.js";
+
+const PAYLOAD_VALUE_TYPES = CONTRACT.payloadValueTypes;
+
+// sc-4505 — a payload / input field map: { <field>: { type, label? } }. This is
+// the FLAT propertySchema-style shape index.d.ts already types, NOT JSON Schema.
+// `type` is restricted to the JSON-serializable set because a payload crosses
+// to the exported Expo app (CLAUDE.md §8).
+function validatePayloadFieldMap(schema, label, errors) {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+    errors.push(`${label} must be an object mapping field name to { type }`);
+    return;
+  }
+  for (const [field, def] of Object.entries(schema)) {
+    if (def === null || typeof def !== "object" || Array.isArray(def)) {
+      errors.push(`${label}.${field} must be an object`);
+      continue;
+    }
+    if (!PAYLOAD_VALUE_TYPES.includes(def.type)) {
+      errors.push(
+        `${label}.${field}.type must be one of ${PAYLOAD_VALUE_TYPES.join(", ")}`,
+      );
+    }
+    if (def.label !== undefined && typeof def.label !== "string") {
+      errors.push(`${label}.${field}.label must be a string when present`);
+    }
+  }
+}
+
 const VALID_CATEGORIES = new Set([
   "input", "display", "layout", "data", "media", "communication", "administration", "custom",
   "INPUT", "DISPLAY", "LAYOUT", "DATA", "MEDIA", "COMMUNICATION", "ADMINISTRATION", "CUSTOM",
@@ -275,6 +304,52 @@ function validateManifest(m) {
       }
       if (!isNonEmptyString(e.name)) {
         errors.push("manifest.events[].name must be a non-empty string");
+        continue;
+      }
+      if (e.description !== undefined && !isNonEmptyString(e.description)) {
+        errors.push(
+          `manifest.events[${e.name}].description must be a non-empty string when present`,
+        );
+      }
+      if (e.payloadSchema !== undefined) {
+        validatePayloadFieldMap(
+          e.payloadSchema,
+          `manifest.events[${e.name}].payloadSchema`,
+          errors,
+        );
+      }
+    }
+  }
+
+  // sc-4505 — `inputs` is optional (additive). Declares the values this widget
+  // CONSUMES from a sibling widget event, wired by the page author.
+  if (manifest.inputs !== undefined) {
+    if (!Array.isArray(manifest.inputs)) {
+      errors.push("manifest.inputs must be an array (use [] for none)");
+    } else {
+      const seenInputs = new Set();
+      for (const i of manifest.inputs) {
+        if (i === null || typeof i !== "object" || Array.isArray(i)) {
+          errors.push("manifest.inputs entries must be objects");
+          break;
+        }
+        if (!isNonEmptyString(i.name)) {
+          errors.push("manifest.inputs[].name must be a non-empty string");
+          continue;
+        }
+        // A duplicate name would make the author-facing wiring ambiguous.
+        if (seenInputs.has(i.name)) {
+          errors.push(`manifest.inputs[].name "${i.name}" is declared twice`);
+        }
+        seenInputs.add(i.name);
+        if (i.description !== undefined && !isNonEmptyString(i.description)) {
+          errors.push(
+            `manifest.inputs[${i.name}].description must be a non-empty string when present`,
+          );
+        }
+        if (i.schema !== undefined) {
+          validatePayloadFieldMap(i.schema, `manifest.inputs[${i.name}].schema`, errors);
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.80.0",
+  "version": "0.82.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",