@colixsystems/widget-sdk 0.205.0 → 0.206.0

package/README.md

@@ -83,7 +83,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.205.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.206.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.206.0 (contract 1.165.0)
+
+**Who is online — `useOnlineMembers(tableId, recordIds)` and `useOnlineVisibility()`.** For the people who share a record (a conversation, a team, a case): which members of records you are a member of — users holding their own read grant on it, given by a person — have the app open now and show their online status. A table opts in: a template table declares `presence: true` (an upgrade that declares it turns it on), or a builder turns on the table's "Show members' online status" setting in the Studio. `online` is a `Set` of user ids across the records and `byRecord[recordId]` is `{ online_user_ids, online_count }` (ids capped at 100, so count with `online_count`); a record the viewer only reads (through a group or a grant to everyone) or cannot read answers with nobody, and there are never timestamps. It refreshes every minute while the app is in front, on return to it and on pull-to-refresh. `supported` is true only once the workspace answered: it is false while the workspace does not record user activity, when the table has not opted in, when the viewer hides their own status, or in a preview — then show no online state at all, never "offline". Declare `directory.read:users`; the publish checks do not require it for this hook, but it is the scope the hook belongs to. `useOnlineVisibility()` is the viewer's own "Show when I'm online" switch (`{ supported, showOnline, setShowOnline }`, on by default): hiding takes the viewer out of everyone's answers, and they then see nobody online either.
+
+### What's new in 0.205.1
+
+**An encrypted column never labels a relation.** A RELATION read's `label` now comes from the first non-encrypted STRING/TEXT column on the target table when no display column is set, and an encrypted display column gives no label (`null`): a label is read whatever the reader may read of the target row, so it never carries encrypted text. To show an encrypted value of a related row, read that row through the table it lives in. A documentation correction; `CONTRACT.version` is unchanged.
 
 ### What's new in 0.205.0 (contract 1.164.0)
 
@@ -2110,7 +2118,7 @@ useEffect(() => {
 
 ### What's new in 0.42.0
 
-**RELATION columns hydrate with a display label (sc-1181).** Record reads now return `{ id, label }` for ONE_TO_ONE / ONE_TO_MANY and `[{ id, label }, ...]` for MANY_TO_MANY (empty array when no links) — `label` is the value of the column pointed at by the new optional `display_column_id` on `DatastoreSchemaColumn`, or, when unset, the first STRING/TEXT column on the target table. Widgets should render `record.<rel>.label` (or `record.<rel>.map(r => r.label).join(", ")` for M:M) directly; `.id` is still there for the foreign-key case. The cell-formatting helpers in the built-in `DataList` and `DataValue` widgets already walk arrays and prefer `label` over `name` / `id` — author widgets that need the same can copy that pattern. `CONTRACT.version` is unchanged.
+**RELATION columns hydrate with a display label (sc-1181).** Record reads now return `{ id, label }` for ONE_TO_ONE / ONE_TO_MANY and `[{ id, label }, ...]` for MANY_TO_MANY (empty array when no links) — `label` is the value of the column pointed at by the new optional `display_column_id` on `DatastoreSchemaColumn`, or, when unset, the first STRING/TEXT column on the target table (since 0.205.1: the first non-encrypted one; an encrypted display column gives no label). Widgets should render `record.<rel>.label` (or `record.<rel>.map(r => r.label).join(", ")` for M:M) directly; `.id` is still there for the foreign-key case. The cell-formatting helpers in the built-in `DataList` and `DataValue` widgets already walk arrays and prefer `label` over `name` / `id` — author widgets that need the same can copy that pattern. `CONTRACT.version` is unchanged.
 
 ### What's new in 0.41.0
 

package/dist/contract.cjs

@@ -2064,6 +2064,62 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11025 / REQ-USERMGMT-12 — online status for people who share a record.
+  {
+    name: "useOnlineMembers",
+    signature: "useOnlineMembers(tableId, recordIds)",
+    description:
+      "Who is online among the members of each record the viewer is a " +
+      "member of (a conversation, a team, a case), on a table that shows its " +
+      "members' online status (a template table's `presence: true`, or the " +
+      "table setting in the Studio). Members hold their OWN read grant on the " +
+      "record, given to them by a person (a grant from a template or one " +
+      "inherited from a parent row names no member). `online` is a Set of " +
+      "the user ids online across the records; `byRecord[recordId]` is " +
+      "{ online_user_ids, online_count } — the ids are capped at 100 per " +
+      "record, so count with `online_count`. A record the viewer only reads " +
+      "(through a group or a grant to everyone) or cannot read answers with " +
+      "nobody. Refreshes every minute while the app is in front, on return " +
+      "to it and on pull-to-refresh. `supported` is true only once the " +
+      "workspace answered: it is false while the workspace does not record " +
+      "user activity, when the table has not opted in, when the viewer hides " +
+      "their own status (useOnlineVisibility), and in a preview — then show " +
+      "NO online state at all, never \"offline\". The viewer's own id may be " +
+      "in `online`; leave it out when you mean \"someone else is here\". " +
+      "Never timestamps. Declare `directory.read:users`: the publish checks " +
+      "do not require it for this hook, but it is the scope the hook belongs to.",
+    returnShape: {
+      supported: "boolean  // false: render no online dots, no counts, no 'offline' state",
+      online: "Set<string>  // user ids online across the records",
+      byRecord: "{ [recordId]: { online_user_ids: string[], online_count: number } }",
+      loading: "boolean",
+      error: "DirectoryError | null  // reason ACTIVITY_UNAVAILABLE, ACTIVITY_DISABLED, ONLINE_STATUS_HIDDEN, PRESENCE_NOT_ENABLED or FORBIDDEN (not a live person) when refused",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: ["directory.read:users"],
+  },
+  {
+    name: "useOnlineVisibility",
+    signature: "useOnlineVisibility()",
+    description:
+      "The viewer's own \"Show when I'm online\" switch, on by default. " +
+      "`supported` is false where the workspace shows nobody online: offer " +
+      "the switch only when it is true. `setShowOnline(false)` hides the " +
+      "viewer from everyone, and they then see nobody online either; every " +
+      "useOnlineMembers on the page re-reads. No scope: it is the viewer's " +
+      "own setting.",
+    returnShape: {
+      supported: "boolean",
+      showOnline: "boolean | null  // null until known",
+      loading: "boolean",
+      saving: "boolean",
+      error: "DirectoryError | null",
+      setShowOnline: "(showOnline: boolean) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: null,
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -3218,7 +3274,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation).",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table.",
   },
   translations: {
     type: "object",
@@ -3369,10 +3425,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ 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) }, " +
-      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). 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:* (destructive user removal by users.delete:*).",
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() }, " +
+      "presence: { online(tableId, recordIds) -> { data: [{ record_id, online_user_ids, online_count }] }, me() -> { show_online }, setShowOnline(bool) -> { show_online } } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope); presence backs useOnlineMembers() + useOnlineVisibility() (session-gated, no scope header). 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:* (destructive user removal by users.delete:*).",
     required: true,
-    fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
+    fields: { users: "object", groups: "object", invites: "object", bankid: "object", presence: "object" },
   },
   assets: {
     description:
@@ -5464,7 +5521,11 @@ const CONTRACT = deepFreeze({
   //    and `useInactiveUsers` read user activity through the new
   //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
   //    new `users.activity:*` scope.
-  version: "1.164.0",
+  // 1.165.0: additive (sc-11025) — `useOnlineMembers(tableId, recordIds)`
+  //    and `useOnlineVisibility()` read who of a record's members is online
+  //    and the viewer's own switch, through the new `ctx.directory.presence`.
+  //    A `datastoreTemplate` table may declare `presence: true`.
+  version: "1.165.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -2064,6 +2064,62 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11025 / REQ-USERMGMT-12 — online status for people who share a record.
+  {
+    name: "useOnlineMembers",
+    signature: "useOnlineMembers(tableId, recordIds)",
+    description:
+      "Who is online among the members of each record the viewer is a " +
+      "member of (a conversation, a team, a case), on a table that shows its " +
+      "members' online status (a template table's `presence: true`, or the " +
+      "table setting in the Studio). Members hold their OWN read grant on the " +
+      "record, given to them by a person (a grant from a template or one " +
+      "inherited from a parent row names no member). `online` is a Set of " +
+      "the user ids online across the records; `byRecord[recordId]` is " +
+      "{ online_user_ids, online_count } — the ids are capped at 100 per " +
+      "record, so count with `online_count`. A record the viewer only reads " +
+      "(through a group or a grant to everyone) or cannot read answers with " +
+      "nobody. Refreshes every minute while the app is in front, on return " +
+      "to it and on pull-to-refresh. `supported` is true only once the " +
+      "workspace answered: it is false while the workspace does not record " +
+      "user activity, when the table has not opted in, when the viewer hides " +
+      "their own status (useOnlineVisibility), and in a preview — then show " +
+      "NO online state at all, never \"offline\". The viewer's own id may be " +
+      "in `online`; leave it out when you mean \"someone else is here\". " +
+      "Never timestamps. Declare `directory.read:users`: the publish checks " +
+      "do not require it for this hook, but it is the scope the hook belongs to.",
+    returnShape: {
+      supported: "boolean  // false: render no online dots, no counts, no 'offline' state",
+      online: "Set<string>  // user ids online across the records",
+      byRecord: "{ [recordId]: { online_user_ids: string[], online_count: number } }",
+      loading: "boolean",
+      error: "DirectoryError | null  // reason ACTIVITY_UNAVAILABLE, ACTIVITY_DISABLED, ONLINE_STATUS_HIDDEN, PRESENCE_NOT_ENABLED or FORBIDDEN (not a live person) when refused",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: ["directory.read:users"],
+  },
+  {
+    name: "useOnlineVisibility",
+    signature: "useOnlineVisibility()",
+    description:
+      "The viewer's own \"Show when I'm online\" switch, on by default. " +
+      "`supported` is false where the workspace shows nobody online: offer " +
+      "the switch only when it is true. `setShowOnline(false)` hides the " +
+      "viewer from everyone, and they then see nobody online either; every " +
+      "useOnlineMembers on the page re-reads. No scope: it is the viewer's " +
+      "own setting.",
+    returnShape: {
+      supported: "boolean",
+      showOnline: "boolean | null  // null until known",
+      loading: "boolean",
+      saving: "boolean",
+      error: "DirectoryError | null",
+      setShowOnline: "(showOnline: boolean) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: null,
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -3214,7 +3270,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation).",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table.",
   },
   translations: {
     type: "object",
@@ -3365,10 +3421,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ 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) }, " +
-      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). 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:* (destructive user removal by users.delete:*).",
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() }, " +
+      "presence: { online(tableId, recordIds) -> { data: [{ record_id, online_user_ids, online_count }] }, me() -> { show_online }, setShowOnline(bool) -> { show_online } } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope); presence backs useOnlineMembers() + useOnlineVisibility() (session-gated, no scope header). 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:* (destructive user removal by users.delete:*).",
     required: true,
-    fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
+    fields: { users: "object", groups: "object", invites: "object", bankid: "object", presence: "object" },
   },
   assets: {
     description:
@@ -5460,7 +5517,11 @@ const CONTRACT = deepFreeze({
   //    and `useInactiveUsers` read user activity through the new
   //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
   //    new `users.activity:*` scope.
-  version: "1.164.0",
+  // 1.165.0: additive (sc-11025) — `useOnlineMembers(tableId, recordIds)`
+  //    and `useOnlineVisibility()` read who of a record's members is online
+  //    and the viewer's own switch, through the new `ctx.directory.presence`.
+  //    A `datastoreTemplate` table may declare `presence: true`.
+  version: "1.165.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -235,6 +235,12 @@ export interface WidgetDatastoreTemplateTable {
   suffix: string;
   /** REQ-ACL-05: when true, the row creator gets full RWD+G on the new record. */
   grantCreatorPermissions?: boolean;
+  /**
+   * When true, the people who share a row see which of each other are online
+   * (`useOnlineMembers`), while the workspace records user activity. An
+   * upgrade that declares it turns it on for the existing table.
+   */
+  presence?: boolean;
   /**
    * REQ-TEMPLATES-ACL: optional table-level public grant. Omitted means
    * the table starts purely per-record (record-level grants are the only
@@ -1118,6 +1124,48 @@ export function useInactiveUsers(query?: {
   remind(id: string, message: { title: string; body: string }): Promise<void>;
 };
 
+/** One record's online members, as `useOnlineMembers` reports them. */
+export interface RecordOnlineMembers {
+  /** At most 100 ids; `online_count` counts them all. */
+  online_user_ids: string[];
+  online_count: number;
+}
+
+/**
+ * Who is online among the members of records the viewer is a member of, on a
+ * table that shows its members' online status (template `presence: true` or
+ * the Studio table setting). Members hold their own read grant, given by a
+ * person; a record the viewer only reads answers with nobody. `supported` is
+ * false while the workspace does not record activity, the table has not opted
+ * in, the viewer hides their own status, or in a preview: then show no online
+ * state at all. Refreshes every minute while the app is in front.
+ */
+export function useOnlineMembers(
+  tableId: string | null | undefined,
+  recordIds: string[] | null | undefined,
+): {
+  supported: boolean;
+  /** User ids online across the records. */
+  online: Set<string>;
+  byRecord: Record<string, RecordOnlineMembers>;
+  loading: boolean;
+  /** `reason` when refused: ACTIVITY_UNAVAILABLE, ACTIVITY_DISABLED, ONLINE_STATUS_HIDDEN, PRESENCE_NOT_ENABLED or FORBIDDEN. */
+  error: DirectoryError | null;
+  refetch(): Promise<void>;
+};
+
+/** The viewer's own "Show when I'm online" switch; offer it only when `supported`. */
+export function useOnlineVisibility(): {
+  supported: boolean;
+  /** Null until known. */
+  showOnline: boolean | null;
+  loading: boolean;
+  saving: boolean;
+  error: DirectoryError | null;
+  /** Save the switch; every switch and useOnlineMembers on the page follows. Rejects with DirectoryError. */
+  setShowOnline(showOnline: boolean): Promise<void>;
+};
+
 export function useDatastoreMutation<T = unknown>(
   table: string,
 ): MutationApi<T>;
@@ -1416,8 +1464,9 @@ export interface DatastoreSchemaColumn {
   /**
    * For RELATION columns only — id of a column on `target_table_id` whose
    * value supplies the `label` hydrated next to the related record id in
-   * record responses. `null` falls back to the first STRING/TEXT column on
-   * the target table.
+   * record responses. `null` falls back to the first non-encrypted
+   * STRING/TEXT column on the target table; an encrypted display column
+   * gives no label (`null`).
    */
   display_column_id?: string | null;
   /** True when this column is the table's display/identification column. */

package/dist/index.js

@@ -129,6 +129,8 @@ export {
   useUserActivity,
   useInactiveUsers,
 } from "./stats-hooks.js";
+// sc-11025 — one source, bound to how each platform says the app is in front.
+export { useOnlineMembers, useOnlineVisibility } from "./presence.js";
 // sc-6607 — `<Overlay>` is one shared component (./overlay-view.js) bound to
 // each platform's primitives, so a widget's modal escapes its container box
 // identically on the Player and the Expo export.

package/dist/index.native.js

@@ -127,6 +127,8 @@ export {
   useUserActivity,
   useInactiveUsers,
 } from "./stats-hooks.js";
+// sc-11025 — see the note on the web mirror in ./index.js.
+export { useOnlineMembers, useOnlineVisibility } from "./presence.native.js";
 // sc-6607 — see the note on the web mirror in ./index.js.
 export { Overlay } from "./overlay.native.js";
 // sc-8104 — see the note on the web mirror in ./index.js.

package/dist/presence-hooks.js

@@ -0,0 +1,239 @@
+// sc-11025 — who is online among the people who share a record, and the
+// viewer's own "Show when I'm online" switch. One source for both entries:
+// ./presence.js and ./presence.native.js only bind how each platform says
+// the app is in front.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { toDirectoryError, useRefresh, useWidgetContextOrThrow } from "./hooks.js";
+
+// Recorded activity moves about once a minute, so polling faster shows nothing new.
+export const PRESENCE_REFRESH_MS = 60 * 1000;
+// Before the feature reaches a workspace, ask again only this seldom.
+export const PRESENCE_UNAVAILABLE_RETRY_MS = 10 * 60 * 1000;
+// The server answers at most this many records per call.
+const RECORDS_PER_CALL = 100;
+
+const NO_RECORDS = Object.freeze({});
+
+/**
+ * How a read leaves the hook asking again. `live`: every minute and on
+ * return. `refused` (setting off, hidden, table not opted in): on return
+ * only. `unavailable` (not released): every ten minutes, never on return.
+ */
+const CADENCE = {
+  live: { everyMs: PRESENCE_REFRESH_MS, onReturn: true },
+  refused: { everyMs: null, onReturn: true },
+  unavailable: { everyMs: PRESENCE_UNAVAILABLE_RETRY_MS, onReturn: false },
+};
+
+function cadenceAfter(error) {
+  if (!error || !(error.status === 401 || error.status === 403)) return "live";
+  return error.reason === "ACTIVITY_UNAVAILABLE" ? "unavailable" : "refused";
+}
+
+// A changed switch re-reads every presence read and updates every switch.
+const presenceReaders = new Set();
+const visibilityHolders = new Set();
+
+function presenceClient(ctx) {
+  const presence = ctx.directory && ctx.directory.presence;
+  return presence && typeof presence.online === "function" ? presence : null;
+}
+
+function uniqueIds(recordIds) {
+  if (!Array.isArray(recordIds)) return [];
+  return [...new Set(recordIds.filter((id) => typeof id === "string" && id))].sort();
+}
+
+async function readOnline(presence, tableId, ids) {
+  const calls = [];
+  for (let i = 0; i < ids.length; i += RECORDS_PER_CALL) {
+    calls.push(presence.online(tableId, ids.slice(i, i + RECORDS_PER_CALL)));
+  }
+  const pages = await Promise.all(calls);
+  const byRecord = {};
+  for (const page of pages) {
+    for (const entry of (page && Array.isArray(page.data) ? page.data : [])) {
+      byRecord[entry.record_id] = {
+        online_user_ids: entry.online_user_ids,
+        online_count: entry.online_count,
+      };
+    }
+  }
+  return byRecord;
+}
+
+/** Runs `onTick` on the cadence's timer while in front, and on return when it says so. */
+function useWhileInFront(appInFront, onTick, cadence) {
+  const tickRef = useRef(onTick);
+  tickRef.current = onTick;
+  const { everyMs, onReturn } = CADENCE[cadence];
+  useEffect(() => {
+    let timer = null;
+    let inFront = appInFront.isActive();
+    const start = () => {
+      if (everyMs && !timer) timer = setInterval(() => tickRef.current(), everyMs);
+    };
+    const stop = () => {
+      clearInterval(timer);
+      timer = null;
+    };
+    if (inFront) start();
+    const unsubscribe = appInFront.subscribe((active) => {
+      if (active === inFront) return;
+      inFront = active;
+      if (!active) return stop();
+      if (onReturn) tickRef.current();
+      return start();
+    });
+    return () => {
+      stop();
+      if (typeof unsubscribe === "function") unsubscribe();
+    };
+  }, [appInFront, everyMs, onReturn]);
+}
+
+/**
+ * Bind the presence hooks to a platform's notion of "the app is in front":
+ * `{ isActive(): boolean, subscribe(onChange(active)): unsubscribe }`.
+ */
+export function makePresenceHooks(appInFront) {
+  /**
+   * Who is online among the members of each record the viewer is a member
+   * of. Returns `{ supported, online, byRecord, loading, error, refetch }`:
+   * `online` is a Set of the user ids online across the records,
+   * `byRecord[id]` is `{ online_user_ids, online_count }` (ids capped at 100).
+   * `supported` is true only once the workspace answered; while it is false
+   * the widget shows no online state at all.
+   */
+  function useOnlineMembers(tableId, recordIds) {
+    const ctx = useWidgetContextOrThrow("useOnlineMembers");
+    const presence = presenceClient(ctx);
+    const presenceRef = useRef(presence);
+    presenceRef.current = presence;
+    const hasPresence = presence !== null;
+    const ids = uniqueIds(recordIds);
+    const key = tableId && ids.length > 0 ? `${tableId}:${ids.join(",")}` : null;
+    const requestRef = useRef(null);
+    requestRef.current = key === null ? null : { tableId, ids };
+    const [state, setState] = useState({ tableId: null, supported: false, byRecord: NO_RECORDS, error: null });
+    const runRef = useRef(0);
+
+    const read = useCallback(async () => {
+      const run = ++runRef.current;
+      const client = presenceRef.current;
+      const request = requestRef.current;
+      if (!client || !request) {
+        setState((prev) => (prev.tableId === null ? prev : { tableId: null, supported: false, byRecord: NO_RECORDS, error: null }));
+        return;
+      }
+      try {
+        const byRecord = await readOnline(client, request.tableId, request.ids);
+        if (runRef.current === run) setState({ tableId: request.tableId, supported: true, byRecord, error: null });
+      } catch (err) {
+        if (runRef.current !== run) return;
+        const error = toDirectoryError(err);
+        setState((prev) =>
+          cadenceAfter(error) === "live"
+            ? { ...(prev.tableId === request.tableId ? prev : { supported: false, byRecord: NO_RECORDS }), tableId: request.tableId, error }
+            : { tableId: request.tableId, supported: false, byRecord: NO_RECORDS, error },
+        );
+      }
+    }, []);
+
+    useEffect(() => {
+      read();
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key, hasPresence]);
+    useEffect(() => {
+      presenceReaders.add(read);
+      return () => presenceReaders.delete(read);
+    }, [read]);
+    useRefresh(read);
+    useWhileInFront(appInFront, read, key !== null && hasPresence ? cadenceAfter(state.error) : "refused");
+
+    // Another set of records of the same table keeps showing the last answer.
+    const current = key !== null && state.tableId === tableId;
+    const byRecord = current ? state.byRecord : NO_RECORDS;
+    const online = useMemo(
+      () => new Set(Object.values(byRecord).flatMap((entry) => entry.online_user_ids || [])),
+      [byRecord],
+    );
+    return {
+      supported: current && state.supported,
+      online,
+      byRecord,
+      loading: key !== null && hasPresence && !current,
+      error: current ? state.error : null,
+      refetch: read,
+    };
+  }
+
+  /**
+   * The viewer's own "Show when I'm online" switch: `{ supported, showOnline,
+   * loading, saving, error, setShowOnline }`. `supported` is false where the
+   * workspace shows nobody online, so the switch is not offered there.
+   * `setShowOnline(bool)` saves it, updates every switch on the page and
+   * re-asks every presence read; hiding also hides everyone from the viewer.
+   */
+  function useOnlineVisibility() {
+    const ctx = useWidgetContextOrThrow("useOnlineVisibility");
+    const presence = presenceClient(ctx);
+    const presenceRef = useRef(presence);
+    presenceRef.current = presence;
+    const hasPresence = presence !== null;
+    const [state, setState] = useState({ loading: hasPresence, supported: false, showOnline: null, error: null });
+    const [saving, setSaving] = useState(false);
+
+    const read = useCallback(async () => {
+      const client = presenceRef.current;
+      if (!client || typeof client.me !== "function") {
+        setState({ loading: false, supported: false, showOnline: null, error: null });
+        return;
+      }
+      try {
+        const own = await client.me();
+        setState({ loading: false, supported: true, showOnline: own.show_online === true, error: null });
+      } catch (err) {
+        const error = toDirectoryError(err);
+        setState((prev) =>
+          cadenceAfter(error) === "live"
+            ? { ...prev, loading: false, error }
+            : { loading: false, supported: false, showOnline: null, error },
+        );
+      }
+    }, []);
+
+    useEffect(() => {
+      read();
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [hasPresence]);
+    useRefresh(read);
+    useEffect(() => {
+      const holder = (showOnline) => setState((prev) => ({ ...prev, showOnline, error: null }));
+      visibilityHolders.add(holder);
+      return () => visibilityHolders.delete(holder);
+    }, []);
+
+    const setShowOnline = useCallback(async (showOnline) => {
+      const client = presenceRef.current;
+      if (!client || typeof client.setShowOnline !== "function") {
+        throw new Error("useOnlineVisibility: host did not inject ctx.directory.presence.setShowOnline");
+      }
+      setSaving(true);
+      let saved;
+      try {
+        saved = (await client.setShowOnline(showOnline === true)).show_online === true;
+      } catch (err) {
+        throw toDirectoryError(err);
+      } finally {
+        setSaving(false);
+      }
+      for (const holder of visibilityHolders) holder(saved);
+      for (const reader of presenceReaders) reader();
+    }, []);
+
+    return { ...state, saving, setShowOnline };
+  }
+
+  return { useOnlineMembers, useOnlineVisibility };
+}

package/dist/presence.js

@@ -0,0 +1,18 @@
+// sc-11025 — the presence hooks bound to the web: the page is in front while
+// it is visible.
+import { makePresenceHooks } from "./presence-hooks.js";
+
+const visible = () =>
+  typeof document === "undefined" || document.visibilityState !== "hidden";
+
+const appInFront = {
+  isActive: visible,
+  subscribe(onChange) {
+    if (typeof document === "undefined") return () => {};
+    const handler = () => onChange(visible());
+    document.addEventListener("visibilitychange", handler);
+    return () => document.removeEventListener("visibilitychange", handler);
+  },
+};
+
+export const { useOnlineMembers, useOnlineVisibility } = makePresenceHooks(appInFront);

package/dist/presence.native.js

@@ -0,0 +1,16 @@
+// sc-11025 — the presence hooks bound to the device: the app is in front
+// unless AppState says "background" ("inactive" is a passing overlay).
+import { AppState } from "react-native";
+import { makePresenceHooks } from "./presence-hooks.js";
+
+const inFront = (state) => state !== "background";
+
+export const appInFront = {
+  isActive: () => inFront(AppState.currentState),
+  subscribe(onChange) {
+    const subscription = AppState.addEventListener("change", (state) => onChange(inFront(state)));
+    return () => subscription?.remove();
+  },
+};
+
+export const { useOnlineMembers, useOnlineVisibility } = makePresenceHooks(appInFront);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.205.0",
+  "version": "0.206.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -2064,6 +2064,62 @@ const HOOKS = [
     requiredContextSlice: ["directory.users"],
     scopes: ["users.activity:*"],
   },
+  // sc-11025 / REQ-USERMGMT-12 — online status for people who share a record.
+  {
+    name: "useOnlineMembers",
+    signature: "useOnlineMembers(tableId, recordIds)",
+    description:
+      "Who is online among the members of each record the viewer is a " +
+      "member of (a conversation, a team, a case), on a table that shows its " +
+      "members' online status (a template table's `presence: true`, or the " +
+      "table setting in the Studio). Members hold their OWN read grant on the " +
+      "record, given to them by a person (a grant from a template or one " +
+      "inherited from a parent row names no member). `online` is a Set of " +
+      "the user ids online across the records; `byRecord[recordId]` is " +
+      "{ online_user_ids, online_count } — the ids are capped at 100 per " +
+      "record, so count with `online_count`. A record the viewer only reads " +
+      "(through a group or a grant to everyone) or cannot read answers with " +
+      "nobody. Refreshes every minute while the app is in front, on return " +
+      "to it and on pull-to-refresh. `supported` is true only once the " +
+      "workspace answered: it is false while the workspace does not record " +
+      "user activity, when the table has not opted in, when the viewer hides " +
+      "their own status (useOnlineVisibility), and in a preview — then show " +
+      "NO online state at all, never \"offline\". The viewer's own id may be " +
+      "in `online`; leave it out when you mean \"someone else is here\". " +
+      "Never timestamps. Declare `directory.read:users`: the publish checks " +
+      "do not require it for this hook, but it is the scope the hook belongs to.",
+    returnShape: {
+      supported: "boolean  // false: render no online dots, no counts, no 'offline' state",
+      online: "Set<string>  // user ids online across the records",
+      byRecord: "{ [recordId]: { online_user_ids: string[], online_count: number } }",
+      loading: "boolean",
+      error: "DirectoryError | null  // reason ACTIVITY_UNAVAILABLE, ACTIVITY_DISABLED, ONLINE_STATUS_HIDDEN, PRESENCE_NOT_ENABLED or FORBIDDEN (not a live person) when refused",
+      refetch: "() => Promise<void>",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: ["directory.read:users"],
+  },
+  {
+    name: "useOnlineVisibility",
+    signature: "useOnlineVisibility()",
+    description:
+      "The viewer's own \"Show when I'm online\" switch, on by default. " +
+      "`supported` is false where the workspace shows nobody online: offer " +
+      "the switch only when it is true. `setShowOnline(false)` hides the " +
+      "viewer from everyone, and they then see nobody online either; every " +
+      "useOnlineMembers on the page re-reads. No scope: it is the viewer's " +
+      "own setting.",
+    returnShape: {
+      supported: "boolean",
+      showOnline: "boolean | null  // null until known",
+      loading: "boolean",
+      saving: "boolean",
+      error: "DirectoryError | null",
+      setShowOnline: "(showOnline: boolean) => Promise<void>  // rejects with DirectoryError",
+    },
+    requiredContextSlice: ["directory.presence"],
+    scopes: null,
+  },
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUserGroup administration. Returns
   // `{ groups, loading, error, refetch, create, remove, addMember, removeMember }`.
   // Reads need `groups.read:*`; mutations need `groups.write:*`. Removing a
@@ -3214,7 +3270,7 @@ const MANIFEST_SCHEMA = {
     type: "object",
     required: false,
     description:
-      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation).",
+      "Optional. Tables the widget needs, seeded into the workspace at install time. Authors wire them into the widget's `tableRef` properties via the Properties Panel — the SDK does not auto-bind. Limits: 8 tables, 24 columns per table. RELATION columns address siblings by `targetSuffix` (any table in the same array, in any order; tables may relate to each other both ways). Tables persist across uninstalls. A `tableRef` property may also carry `sharedTable: true`, declaring that the table is the APP'S OWN — the author picks an existing table and the widget seeds nothing for it. That is the correct shape for a widget that reads data it does not own (a chart, a metric, a manager view over another widget's table). `sharedTable` exempts the property from needing a seeded table at publish (`manifest.requiredTableRefsHaveTemplate`) WITHOUT making it optional: the author must still bind one, and the host still refuses to place the widget unbound. Use it instead of dropping `required` — a widget that silently renders an empty tile is the defect it looks like a fix for. sc-7530: a table may also declare `roleGrants` — group-scoped access named SYMBOLICALLY, because a group id belongs to the workspace that installs the widget and could never travel in the manifest. Declare the audiences once at template level as `roles: [{ key, label, description? }]` (key is lowercase kebab, max 8 roles), then per table `roleGrants: [{ role, canRead?, canWrite?, canDelete? }]`. The installing workspace binds each role to one of its own user groups (or has one created) during the install consent step, so a permission model where an admin group does everything and signed-in users only read survives the trip between workspaces. Use `publicGrant` for the two id-less audiences (everyone / any signed-in user) and `roleGrants` for anything that names a group. A role nobody binds simply writes no grant — it never fails the install. sc-7557: a column may declare `encrypted: true` — its values are stored AES-256-GCM encrypted at rest under a per-workspace subkey. The widget still reads and writes PLAINTEXT (the platform encrypts on write, decrypts for end users); studio users see `🔒` instead, and the column cannot be searched, filtered or sorted on. Sample `rows` you seed for it are encrypted the same way. Not valid on `RELATION` — its value is a foreign key the backend must resolve — and publishing one is rejected. An `inheritAcl` RELATION column may add `inheritAclReadOnly: true` — rows then inherit READ access only, so members of the parent read every child and may add children, but change or delete only the rows they created (pair with `grantCreatorPermissions`). A column may declare `defaultValue`, written when a create omits it: `@currentUser` on USER, `@now` on DATE / DATETIME, or a literal of the column's own type (none on FILE, RELATION or USER_GROUP — ids belong to the installing workspace). `defaultLocked: true` on an `@currentUser` / `@now` default makes the server always stamp it and ignore any client value on create and update, so an author column cannot be forged. `immutable: true` makes a column write-once: a create sets it as usual and any value sent for it on update is ignored (not valid on a MANY_TO_MANY relation). A table may declare `presence: true` so the people who share a row see which of each other are online (useOnlineMembers); it takes effect only while the workspace records user activity, and an upgrade that declares it turns it on for the existing table.",
   },
   translations: {
     type: "object",
@@ -3365,10 +3421,11 @@ const WIDGET_CONTEXT_SHAPE = {
       "{ 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) }, " +
-      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() } }. " +
-      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope). 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:* (destructive user removal by users.delete:*).",
+      "bankid: { status() -> { linked, available }, startLink() -> { order_ref, qr, ... }, collect(orderRef), cancel(orderRef), unlink() }, " +
+      "presence: { online(tableId, recordIds) -> { data: [{ record_id, online_user_ids, online_count }] }, me() -> { show_online }, setShowOnline(bool) -> { show_online } } }. " +
+      "users backs useDirectory() + useUsers(); groups backs useGroups(); invites backs useInvites() (list/resend/revoke pending invites, gated by users.write:* + the users.write capability); bankid backs useBankIdLink() (REQ-BANKID-AUTH — self-service account linking, JWT-gated, no widget scope); presence backs useOnlineMembers() + useOnlineVisibility() (session-gated, no scope header). 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:* (destructive user removal by users.delete:*).",
     required: true,
-    fields: { users: "object", groups: "object", invites: "object", bankid: "object" },
+    fields: { users: "object", groups: "object", invites: "object", bankid: "object", presence: "object" },
   },
   assets: {
     description:
@@ -5460,7 +5517,11 @@ const CONTRACT = deepFreeze({
   //    and `useInactiveUsers` read user activity through the new
   //    `ctx.directory.users.activity` / `.inactive` / `.remind`, behind the
   //    new `users.activity:*` scope.
-  version: "1.164.0",
+  // 1.165.0: additive (sc-11025) — `useOnlineMembers(tableId, recordIds)`
+  //    and `useOnlineVisibility()` read who of a record's members is online
+  //    and the viewer's own switch, through the new `ctx.directory.presence`.
+  //    A `datastoreTemplate` table may declare `presence: true`.
+  version: "1.165.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,