@colixsystems/widget-sdk 0.23.0 → 0.25.0

package/README.md

@@ -18,6 +18,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
 | **CORE** | `useTheme()` | `{ colors, spacing, radii, typography }` | `ctx.workspace.theme` — no scope |
+| **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, display_name, roles, group_ids }` | `ctx.user` (snake_case verbatim; `id` null when anonymous) — no scope |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
 | **CORE** | `useWidgetEvent(name)` | `(payload?) => void` | `ctx.events.emit` — no scope |
@@ -45,7 +46,27 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.23.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.25.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.25.0
+
+**Per-widget styling via `styleSchema` (REQ-THEME-13).**
+
+- **New optional `manifest.styleSchema` field.** Same shape and types as `propertySchema` (`color`, `number`, `select`, `boolean`, …) — it declares the styling options the widget exposes. Example:
+  ```js
+  styleSchema: {
+    cardBackground: { type: "color", label: "Card background" },
+    cardRadius:     { type: "number", label: "Corner radius", validation: { min: 0, max: 48 } },
+    valueColor:     { type: "color", label: "Value color" },
+  }
+  ```
+- **The Studio renders a "Style" section** from `styleSchema` using the same `SchemaForm` engine as `propertySchema`. The author's resolved values are persisted under the node's `props.style`.
+- **New `useWidgetStyle()` hook** returns `props.style` (an object keyed by your style-field names). Read `style.<field>` and apply each onto whatever element you choose — the host never auto-applies style, so the widget controls placement:
+  ```jsx
+  const style = useWidgetStyle();
+  <View style={[styles.card, style.cardBackground && { backgroundColor: style.cardBackground }]}>
+  ```
+- **`CONTRACT.version` → `1.15.0`** (additive: one optional manifest field + one hook). No existing field, hook, primitive, or token changed shape.
 
 ### What's new in 0.23.0
 

package/dist/contract.cjs

@@ -47,6 +47,23 @@ const HOOKS = [
     requiredContextSlice: ["workspace.theme"],
     scopes: null,
   },
+  {
+    name: "useWidgetStyle",
+    signature: "useWidgetStyle()",
+    description:
+      "Returns the author-set per-widget style values (REQ-THEME-13) — the " +
+      "resolved object the host delivers under props.style, keyed by the " +
+      "style-field names the widget declares in manifest.styleSchema. Read " +
+      "props.style.<field> and apply each onto whatever element you choose " +
+      "(spread AFTER your intrinsic styles so author choices win). Returns an " +
+      "empty object when nothing is set, so reads are always safe. Equivalent " +
+      "to reading the `style` prop directly.",
+    returnShape: {
+      "<styleFieldName>": "the author-set value (string/number/… per the styleSchema def)",
+    },
+    requiredContextSlice: ["props"],
+    scopes: null,
+  },
   {
     name: "useI18n",
     signature: "useI18n()",
@@ -314,6 +331,31 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["acl.write:records"],
   },
+  // REQ-RT-07 — realtime table subscription.
+  {
+    name: "useDatastoreSubscription",
+    signature: "useDatastoreSubscription(tableId, handlers, options?)",
+    description:
+      "Subscribe to a table's realtime change stream via the injected " +
+      "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
+      "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
+      "snake_case record verbatim (same shape REST returns). The socket opens " +
+      "on mount, re-opens when tableId changes, and is torn down on unmount. " +
+      "Returns { status } where status is 'connecting' | 'live' | " +
+      "'reconnecting' | 'fallback'. The server gates each subscribe by the " +
+      "same read ACL REST honours; on an ACL reject, a missing WebSocket, or a " +
+      "host whose client predates realtime, the hook resolves to " +
+      "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
+      "Reads the same datastore.read scope as useDatastoreQuery — declare " +
+      "datastore.read for the table you subscribe to. Pair with " +
+      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+    returnShape: {
+      status:
+        "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
   // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
@@ -576,6 +618,20 @@ const MANIFEST_SCHEMA = {
     description: "Map of prop name to property definition.",
     default: {},
   },
+  styleSchema: {
+    type: "object",
+    required: false,
+    description:
+      "Optional (REQ-THEME-13). Map of style-field name to definition — the " +
+      "SAME shape and types as propertySchema (color, number, select, " +
+      "boolean, …). Declares the per-instance styling options the widget " +
+      "exposes; the Studio Properties Panel renders a \"Style\" section from " +
+      "it. The author's resolved values are delivered to the widget under " +
+      "props.style (one object keyed by style-field name); the widget reads " +
+      "props.style.<field> and applies each wherever it chooses. The host " +
+      "never auto-applies style — the widget owns placement.",
+    default: {},
+  },
   events: {
     type: "object[]",
     required: true,
@@ -1136,7 +1192,24 @@ const CONTRACT = deepFreeze({
   //    is additive — minor bump on the pre-1.0 channel. The compiler pins the
   //    native-module members in the exported Expo app's package.json and now
   //    always emits the react-native-reanimated/plugin (CLAUDE.md §3 parity).
-  version: "1.13.0",
+  //
+  // 1.14.0: additive (REQ-RT-07) — new `useDatastoreSubscription(tableId,
+  //    handlers, options?)` hook reading ctx.datastore.records(t).subscribe.
+  //    Backed by the datastore-client 0.6.0 `subscribe` method (WebSocket to
+  //    `/datastore/ws`). Safe-by-default: resolves to { status: 'fallback' }
+  //    when the host's client predates realtime or no WebSocket is available,
+  //    so widgets degrade to polling on both platforms. No existing hook,
+  //    primitive, or contract field changed — minor bump on the pre-1.0 channel.
+  //
+  // 1.15.0: additive (REQ-THEME-13) — per-widget styling via `styleSchema`. New
+  //    optional manifest field `styleSchema`: the SAME shape as propertySchema
+  //    (color/number/select/… fields), declaring the per-instance styling
+  //    options a widget exposes. The Studio renders a "Style" section from it;
+  //    the resolved values are delivered to the widget under props.style and
+  //    the widget applies them itself (the host never auto-styles). New
+  //    `useWidgetStyle()` hook returns props.style. No existing field, hook,
+  //    primitive, or token changed shape — minor bump on the pre-1.0 channel.
+  version: "1.15.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/contract.js

@@ -47,6 +47,23 @@ const HOOKS = [
     requiredContextSlice: ["workspace.theme"],
     scopes: null,
   },
+  {
+    name: "useWidgetStyle",
+    signature: "useWidgetStyle()",
+    description:
+      "Returns the author-set per-widget style values (REQ-THEME-13) — the " +
+      "resolved object the host delivers under props.style, keyed by the " +
+      "style-field names the widget declares in manifest.styleSchema. Read " +
+      "props.style.<field> and apply each onto whatever element you choose " +
+      "(spread AFTER your intrinsic styles so author choices win). Returns an " +
+      "empty object when nothing is set, so reads are always safe. Equivalent " +
+      "to reading the `style` prop directly.",
+    returnShape: {
+      "<styleFieldName>": "the author-set value (string/number/… per the styleSchema def)",
+    },
+    requiredContextSlice: ["props"],
+    scopes: null,
+  },
   {
     name: "useI18n",
     signature: "useI18n()",
@@ -177,8 +194,7 @@ const HOOKS = [
     signature: "useDatastoreMutation(tableId)",
     returnShape: {
       create: "(record) => Promise<Record>  // rejects with DatastoreError",
-      update:
-        "(id, partial) => Promise<Record>  // rejects with DatastoreError",
+      update: "(id, partial) => Promise<Record>  // rejects with DatastoreError",
       delete: "(id) => Promise<void>  // rejects with DatastoreError",
     },
     requiredContextSlice: ["datastore.records"],
@@ -281,13 +297,7 @@ const HOOKS = [
     scopes: ["groups.read:*"],
   },
   // REQ-ACL-06 / REQ-ACL-RELINHERIT-05 — per-record VirtualPermission
-  // management for a single record. Reads the injected datastore-client at
-  // ctx.datastore.records(tableId).permissions(recordId) (the recordPermissions
-  // facade was folded into the datastore-client). The backend gates the call
-  // on `can_grant` for the target record (Studio owners short-circuit;
-  // APP_USER actors must hold `can_grant` via REQ-ACL-05 / REQ-ACL-06). A
-  // widget that declares the scope but whose caller lacks the grant receives
-  // `PermissionError { code: 'FORBIDDEN' }`.
+  // management for a single record. Mirror of contract.js.
   {
     name: "useRecordPermissions",
     signature: "useRecordPermissions(tableId, recordId)",
@@ -321,7 +331,32 @@ const HOOKS = [
     requiredContextSlice: ["datastore.records"],
     scopes: ["acl.write:records"],
   },
-  // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks.
+  // REQ-RT-07 — realtime table subscription.
+  {
+    name: "useDatastoreSubscription",
+    signature: "useDatastoreSubscription(tableId, handlers, options?)",
+    description:
+      "Subscribe to a table's realtime change stream via the injected " +
+      "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
+      "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
+      "snake_case record verbatim (same shape REST returns). The socket opens " +
+      "on mount, re-opens when tableId changes, and is torn down on unmount. " +
+      "Returns { status } where status is 'connecting' | 'live' | " +
+      "'reconnecting' | 'fallback'. The server gates each subscribe by the " +
+      "same read ACL REST honours; on an ACL reject, a missing WebSocket, or a " +
+      "host whose client predates realtime, the hook resolves to " +
+      "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
+      "Reads the same datastore.read scope as useDatastoreQuery — declare " +
+      "datastore.read for the table you subscribe to. Pair with " +
+      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+    returnShape: {
+      status:
+        "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
+    },
+    requiredContextSlice: ["datastore.records"],
+    scopes: ["datastore.read:<table>"],
+  },
+  // REQ-WSDK-PLATFORM §6 — Tier A SDK hooks. Mirror of contract.js.
   {
     name: "useClipboard",
     signature: "useClipboard()",
@@ -359,7 +394,13 @@ const HOOKS = [
   },
 ];
 
-// REQ-WSDK-RN-WEB: see contract.cjs for the source-of-truth comment.
+// REQ-WSDK-RN-WEB: the SDK exposes the React Native primitive API
+// (backed by react-native-web on the browser, by react-native on the
+// exported Expo app). The contract describes the *cross-platform
+// subset* the SDK re-exports; the per-prop reference for each
+// component is whatever React Native documents. Adding a new primitive
+// = add the name to `./primitives.js` + `./primitives.native.js` (both
+// one-line re-exports) and append it to this list.
 const PRIMITIVES = [
   {
     name: "Text",
@@ -577,6 +618,20 @@ const MANIFEST_SCHEMA = {
     description: "Map of prop name to property definition.",
     default: {},
   },
+  styleSchema: {
+    type: "object",
+    required: false,
+    description:
+      "Optional (REQ-THEME-13). Map of style-field name to definition — the " +
+      "SAME shape and types as propertySchema (color, number, select, " +
+      "boolean, …). Declares the per-instance styling options the widget " +
+      "exposes; the Studio Properties Panel renders a \"Style\" section from " +
+      "it. The author's resolved values are delivered to the widget under " +
+      "props.style (one object keyed by style-field name); the widget reads " +
+      "props.style.<field> and applies each wherever it chooses. The host " +
+      "never auto-applies style — the widget owns placement.",
+    default: {},
+  },
   events: {
     type: "object[]",
     required: true,
@@ -611,7 +666,8 @@ const MANIFEST_SCHEMA = {
 
 const WIDGET_CONTEXT_SHAPE = {
   props: {
-    description: "Resolved property values, shape per manifest.propertySchema.",
+    description:
+      "Resolved property values, shape per manifest.propertySchema.",
     required: true,
     fields: {},
   },
@@ -725,10 +781,7 @@ const WIDGET_CONTEXT_SHAPE = {
       error: "function",
     },
   },
-  // REQ-WSDK-PLATFORM §6 — backs useToast(). The host installs its own
-  // workspace-themed toast renderer here; if omitted, the SDK's useToast
-  // hook falls back to a CustomEvent on web / console.log on native so
-  // widget code still runs without a host integration.
+  // REQ-WSDK-PLATFORM §6 — backs useToast(). Mirror of contract.js.
   toast: {
     description:
       "Optional host toast slot. { showToast({ kind, message }): void }. " +
@@ -762,8 +815,14 @@ const BUNDLE_EXPORT_CONTRACT = [
 ];
 
 // REQ-WSDK-PLATFORM (docs/design/req-widget-sdk-cross-platform-primitives.md
-// §3.5, §8): `fetch` and `XMLHttpRequest` are NOT banned. See contract.cjs
-// for the source-of-truth comment.
+// §3.5, §8): `fetch` and `XMLHttpRequest` are NOT banned. Widgets may call
+// third-party APIs directly. Same-origin requests to the host's own
+// `/api/*` surface are rejected at runtime by the WidgetContextProvider's
+// network gate (`no host-api access from widgets`) — the JWT token is
+// never shared with widget code, so the call would 401 anyway; the runtime
+// gate makes the failure mode "blocked" instead of "401 noise". A soft
+// linter warning (`no-host-api-url`) flags obvious host-URL substrings at
+// submission so authors learn the rule statically.
 const BANNED_APIS = [
   { identifier: "eval", reason: "Arbitrary code evaluation." },
   {
@@ -798,8 +857,22 @@ const BANNED_APIS = [
   { identifier: "globalThis", reason: "Host environment escape." },
 ];
 
-// REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. See contract.cjs
-// for the source-of-truth comment.
+// REQ-WSDK-PLATFORM §3.4, §5: vetted package allowlist. Each entry is a
+// specifier the widget bundle may import as a bare module specifier. The
+// linter validates every `import ... from "<spec>"` line against this
+// list; specifiers not on the list fail the lint. The compiler reads it
+// to know which packages to add to the exported Expo app's package.json.
+//
+// `platforms` is one or both of "web" / "native". A widget that imports a
+// native-only package implicitly drops "web" from the package's effective
+// `supportedPlatforms` (and vice versa) — the marketplace upload pipeline
+// surfaces the derived set so the listing shows honest badges.
+//
+// Adding a package is a CONTRACT change. Review burden: confirm the
+// package does what it claims, has a credible maintainer, and the
+// import shape (named exports, default export) is stable. After that,
+// every widget using the package inherits the review — the marketplace
+// reviewer only spot-checks usage, not the package source.
 const VETTED_IMPORTS = [
   {
     specifier: "react",
@@ -981,8 +1054,19 @@ const VETTED_IMPORTS = [
   },
 ];
 
+// Back-compat shape — every existing consumer (widgetLoader, the static
+// analyzer's DEPENDENCY_ALLOWLIST, the AI prompt's "Allowed imports" line)
+// reads a plain `string[]` from `CONTRACT.allowedBareImports`. Derive it
+// from the rich list so a single edit in VETTED_IMPORTS propagates to
+// every surface.
 const ALLOWED_BARE_IMPORTS = VETTED_IMPORTS.map((v) => v.specifier);
 
+// REQ-WSDK-PLATFORM §3.5: host-API URL patterns the linter scans for as a
+// soft warning. None of these block the lint by themselves — they prompt
+// the marketplace reviewer to spot-check, and they help authors learn the
+// rule statically. Strings appear as literal substring matches (the URL
+// is reachable in widget code by composing it at runtime, so this is
+// best-effort).
 const HOST_API_URL_PATTERNS = [
   "/api/v1",
   "/uploads/",
@@ -1011,24 +1095,43 @@ function widgetTranslationKey(id, key) {
 }
 
 const CONTRACT = deepFreeze({
-  // 1.7.0: additive — new useDatastoreSchema(tableId) hook + the
-  // datastore.schema host-context slice it reads (resolves a table's column
-  // structure at runtime via the existing ACL-gated GET /tables/:id).
+  // REQ-WSDK-PLATFORM bump:
+  //   - `vettedImports` is a new field (rich allowlist with platforms +
+  //     category + description).
+  //   - `hostApiUrlPatterns` is a new field (soft-warning substrings).
+  //   - `bannedApis` no longer lists `fetch` / `XMLHttpRequest`.
+  //   - `allowedBareImports` is now derived from `vettedImports` (same
+  //     shape; same contents grow with each vetted addition).
+  // Permissive-direction change: minor bump on the contract's own
+  // versioning (per CLAUDE.md §4, pre-1.0 minor is the breaking channel —
+  // the package.json version bumps accordingly).
+  //
+  // 1.6.0: additive — `themeTokens.colors` gains `secondary` + `onSecondary`
+  // so the tenant's Theme Settings "Secondary Color" flows through
+  // `useTheme().colors.secondary` (Button secondary variant + any widget
+  // that wants the brand's second accent).
+  //
+  // 1.7.0: additive — new `useDatastoreSchema(tableId)` hook + the
+  // `datastore.schema` host-context slice it reads. Lets a widget resolve a
+  // stored columnId to its column name / dataType / relation target at
+  // runtime (Form Builder renders inputs by column type). Reads the existing
+  // ACL-gated `GET /tables/:id` — structure only, no row data.
   //
   // 1.8.0: two additive features.
-  //  - REQ-WIDGET-ACTION — manifests may declare an optional `actions` array:
-  //    server-side cron/record-triggered scripts the operator enables per
-  //    tenant, run in the existing isolated-vm action runner (never in the
-  //    rendered app). New fields actionTriggerTypes / actionScriptGlobals /
-  //    actionScriptMaxBytes feed the docs + agent prompt. 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
+  //  - 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).
+  //    /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
@@ -1089,7 +1192,24 @@ const CONTRACT = deepFreeze({
   //    is additive — minor bump on the pre-1.0 channel. The compiler pins the
   //    native-module members in the exported Expo app's package.json and now
   //    always emits the react-native-reanimated/plugin (CLAUDE.md §3 parity).
-  version: "1.13.0",
+  //
+  // 1.14.0: additive (REQ-RT-07) — new `useDatastoreSubscription(tableId,
+  //    handlers, options?)` hook reading ctx.datastore.records(t).subscribe.
+  //    Backed by the datastore-client 0.6.0 `subscribe` method (WebSocket to
+  //    `/datastore/ws`). Safe-by-default: resolves to { status: 'fallback' }
+  //    when the host's client predates realtime or no WebSocket is available,
+  //    so widgets degrade to polling on both platforms. No existing hook,
+  //    primitive, or contract field changed — minor bump on the pre-1.0 channel.
+  //
+  // 1.15.0: additive (REQ-THEME-13) — per-widget styling via `styleSchema`. New
+  //    optional manifest field `styleSchema`: the SAME shape as propertySchema
+  //    (color/number/select/… fields), declaring the per-instance styling
+  //    options a widget exposes. The Studio renders a "Style" section from it;
+  //    the resolved values are delivered to the widget under props.style and
+  //    the widget applies them itself (the host never auto-styles). New
+  //    `useWidgetStyle()` hook returns props.style. No existing field, hook,
+  //    primitive, or token changed shape — minor bump on the pre-1.0 channel.
+  version: "1.15.0",
   hooks: HOOKS,
   primitives: PRIMITIVES,
   manifestSchema: MANIFEST_SCHEMA,

package/dist/hooks.js

@@ -83,6 +83,26 @@ export function useTheme() {
   return ctx.workspace.theme;
 }
 
+/**
+ * REQ-THEME-13 — returns the author-set per-widget style values: the object the
+ * host delivers under `props.style`, keyed by the style-field names the widget
+ * declares in its `manifest.styleSchema`. Read `style.<field>` and apply each
+ * onto whatever element you choose (spread AFTER your intrinsic styles so the
+ * author's choice wins):
+ *
+ *   const style = useWidgetStyle();
+ *   <View style={[styles.card, style.cardBackground && { backgroundColor: style.cardBackground }]}>
+ *
+ * Returns an empty object when nothing is set, so reads are always safe. This
+ * is equivalent to reading the `style` prop directly — the hook is a
+ * convenience so a widget needn't thread `style` through its prop signature.
+ */
+export function useWidgetStyle() {
+  const ctx = useWidgetContextOrThrow("useWidgetStyle");
+  const style = ctx.props ? ctx.props.style : undefined;
+  return style && typeof style === "object" ? style : {};
+}
+
 /**
  * Returns the active end-user identity VERBATIM from the host, e.g.
  *   `{ id, email, display_name, roles, group_ids }` (snake_case fields).
@@ -921,6 +941,93 @@ export function useRecordPermissions(tableId, recordId) {
   return { permissions, loading, error, grant, revoke, update, refetch };
 }
 
+/**
+ * REQ-RT-07: subscribe to a table's realtime change stream. Reads
+ * `ctx.datastore.records(table).subscribe({ onCreated, onUpdated, onDeleted,
+ * onStatus })` and wires it to a React lifecycle: the socket is opened on
+ * mount (and re-opened when `table` changes) and torn down on unmount via the
+ * unsubscribe function the client returns. The author's `handlers` callbacks
+ * are held in a ref so re-renders with fresh callback identities never tear
+ * the socket down — only a `table` change does.
+ *
+ * Returns `{ status }` where status is "connecting" | "live" | "reconnecting"
+ * | "fallback". A widget typically pairs this with `useDatastoreQuery` for the
+ * initial load and merges the streamed create/update/delete envelopes into its
+ * local list; when `status === "fallback"` (no socket support on the host, the
+ * subscribe was ACL-rejected, or the connect timed out) the widget should run
+ * its own REST polling instead.
+ *
+ * Cross-platform + safe-by-default: if the host's datastore client doesn't
+ * expose `subscribe` (an older host, or a runtime with no WebSocket), the hook
+ * resolves to `{ status: "fallback" }` WITHOUT throwing, so a widget that
+ * subscribes degrades to polling on both the web Player and the native export
+ * rather than crashing at render (CLAUDE.md §11).
+ *
+ * @param {string} table  Bound table id (falsy → no subscription, status "fallback").
+ * @param {{ onCreated?, onUpdated?, onDeleted? }} [handlers]  Per-event callbacks; each receives the snake_case record.
+ * @param {{ fallbackAfterMs?: number }} [options]
+ * @returns {{ status: "connecting" | "live" | "reconnecting" | "fallback" }}
+ */
+export function useDatastoreSubscription(table, handlers, options) {
+  const ctx = useWidgetContextOrThrow("useDatastoreSubscription");
+  const [status, setStatus] = useState("connecting");
+
+  // Author callbacks live in a ref so a new closure each render does not
+  // re-run the effect (which would tear down + re-open the socket).
+  const handlersRef = useRef(handlers);
+  handlersRef.current = handlers;
+  // `ctx` is a fresh object identity per host render; hold the records
+  // factory in a ref so the effect depends only on `table`.
+  const recordsRef = useRef(
+    ctx.datastore && typeof ctx.datastore.records === "function"
+      ? ctx.datastore.records
+      : null,
+  );
+  recordsRef.current =
+    ctx.datastore && typeof ctx.datastore.records === "function"
+      ? ctx.datastore.records
+      : null;
+
+  const fallbackAfterMs =
+    options && Number.isFinite(options.fallbackAfterMs)
+      ? options.fallbackAfterMs
+      : undefined;
+
+  useEffect(() => {
+    if (!table || typeof recordsRef.current !== "function") {
+      setStatus("fallback");
+      return undefined;
+    }
+    let ns;
+    try {
+      ns = recordsRef.current(table);
+    } catch (_) {
+      setStatus("fallback");
+      return undefined;
+    }
+    if (!ns || typeof ns.subscribe !== "function") {
+      // Host's datastore client predates realtime — degrade to polling.
+      setStatus("fallback");
+      return undefined;
+    }
+    const stop = ns.subscribe(
+      {
+        onCreated: (r) => handlersRef.current?.onCreated?.(r),
+        onUpdated: (r) => handlersRef.current?.onUpdated?.(r),
+        onDeleted: (r) => handlersRef.current?.onDeleted?.(r),
+        onStatus: (s) => setStatus(s),
+      },
+      fallbackAfterMs != null ? { fallbackAfterMs } : undefined,
+    );
+    return () => {
+      if (typeof stop === "function") stop();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table, fallbackAfterMs]);
+
+  return { status };
+}
+
 /* ============================================================================
  * FILES CLIENT — ctx.files (@colixsystems/files-client)
  *

package/dist/index.d.ts

@@ -184,6 +184,14 @@ export interface WidgetManifest {
   minAppStudioVersion: string;
   requestedScopes: WidgetScope[];
   propertySchema: WidgetPropertySchema;
+  /**
+   * REQ-THEME-13 — optional per-widget styling schema. Same shape and types as
+   * `propertySchema`; declares the styling options the widget exposes. The
+   * Studio renders a "Style" section from it and delivers the author's resolved
+   * values to the widget under `props.style` (read them via `useWidgetStyle()`
+   * or the `style` prop). The widget applies each value itself.
+   */
+  styleSchema?: WidgetPropertySchema;
   events: WidgetEventDescriptor[];
   /**
    * Optional datastore template seeded into the tenant's workspace when
@@ -556,6 +564,14 @@ export function usePayments(): PaymentsApi;
 
 export function useTheme(): ThemeTokens;
 
+/**
+ * REQ-THEME-13 — the author-set per-widget style values (the `props.style`
+ * object), keyed by the names declared in `manifest.styleSchema`. Returns an
+ * empty object when nothing is set. Apply each value onto whatever element you
+ * choose; the host never auto-applies style.
+ */
+export function useWidgetStyle(): Record<string, unknown>;
+
 /**
  * Stateful single-record fetch hook. Returns `{ data, loading, error,
  * refetch }`. `data` is one row or `null` (never an array).
@@ -624,6 +640,37 @@ export function useDatastoreSchema(
   tableId: string | null | undefined,
 ): SchemaResult;
 
+// REQ-RT-07 realtime subscription transport state.
+export type DatastoreSubscriptionStatus =
+  | "connecting"
+  | "live"
+  | "reconnecting"
+  | "fallback";
+
+export interface DatastoreSubscriptionHandlers {
+  onCreated?: (record: Record<string, unknown>) => void;
+  onUpdated?: (record: Record<string, unknown>) => void;
+  onDeleted?: (record: Record<string, unknown>) => void;
+}
+
+export interface DatastoreSubscriptionOptions {
+  fallbackAfterMs?: number;
+}
+
+/**
+ * REQ-RT-07: subscribe to a table's realtime change stream via
+ * `ctx.datastore.records(tableId).subscribe(...)`. Opens on mount, re-opens on
+ * `tableId` change, tears down on unmount. Returns `{ status }`; when status
+ * is `"fallback"` (no socket support, ACL-rejected, or connect timed out) run
+ * REST polling instead. Never throws — degrades to `{ status: "fallback" }` on
+ * a host whose datastore client predates realtime.
+ */
+export function useDatastoreSubscription(
+  tableId: string | null | undefined,
+  handlers?: DatastoreSubscriptionHandlers,
+  options?: DatastoreSubscriptionOptions,
+): { status: DatastoreSubscriptionStatus };
+
 /**
  * Stateful file-asset resolver hook. Returns `{ url, file, loading, error,
  * refetch }`. The `url` is an absolute URL composed against the host's API

package/dist/index.js

@@ -20,9 +20,11 @@ export {
   useUsers,
   useGroups,
   useRecordPermissions,
+  useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
   useTheme,
+  useWidgetStyle,
   useI18n,
   useUser,
   useFill,

package/dist/index.native.js

@@ -20,9 +20,11 @@ export {
   useUsers,
   useGroups,
   useRecordPermissions,
+  useDatastoreSubscription,
   useWidgetEvent,
   usePayments,
   useTheme,
+  useWidgetStyle,
   useI18n,
   useUser,
   useFill,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js"
   },
   "engines": {
     "node": ">=18"