@colixsystems/widget-sdk 0.205.1 → 0.207.0

package/dist/contract.js

@@ -704,6 +704,25 @@ const THEME_COMPONENTS = Object.freeze({
     }),
     targets: Object.freeze({}),
   }),
+  // Inline messages: `<Banner>` reads this scope directly, so it names the
+  // SDK component it styles and binds no widget field.
+  alert: Object.freeze({
+    label: "Alerts",
+    sdkComponents: Object.freeze(["Banner"]),
+    tokens: Object.freeze({
+      radius: Object.freeze({ type: "size", min: 0, max: 32, uiDefault: "radii.md" }),
+      borderWidth: Object.freeze({ type: "size", min: 0, max: 4 }),
+      infoBackground: Object.freeze({ type: "color" }),
+      infoTextColor: Object.freeze({ type: "color" }),
+      successBackground: Object.freeze({ type: "color" }),
+      successTextColor: Object.freeze({ type: "color" }),
+      warningBackground: Object.freeze({ type: "color" }),
+      warningTextColor: Object.freeze({ type: "color" }),
+      errorBackground: Object.freeze({ type: "color" }),
+      errorTextColor: Object.freeze({ type: "color" }),
+    }),
+    targets: Object.freeze({}),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2064,6 +2083,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
@@ -2906,6 +2981,13 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  {
+    name: "Banner",
+    description:
+      'Themed inline message. `<Banner tone="error" title="Could not save" message={err.message} action={{ label: "Retry", onPress: save }} onDismiss={() => setErr(null)} />`. THE way to show an error, warning, success or notice that belongs to a place in the widget and stays until it is resolved: a list that failed to load, a form the user cannot submit yet, a "read-only" or "offline" notice. Render it where the problem is — above the list or form it concerns. Use `useToast()` instead for a brief confirmation of something the user just did ("Saved", "Deleted") that needs no decision and may disappear on its own; never both for one event. Its fill, text colour, border and corner radius come from the app\'s theme per tone (Design > Components > Alerts), so never hand-roll a tinted box from `View` + a border + a hex. Props: `tone` ("info" default | "success" | "warning" | "error"), `title` (optional, one short line) and `message` (wraps — never truncate it): text, or an element you built when part of it needs its own styling, `icon` (a lucide name replacing the tone\'s own glyph, or `false` for none), `action` (`{ label, onPress, accessibilityLabel?, testID? }`, ONE action such as Retry), `onDismiss` (pass it to show a close control; you hide the banner in the handler), `dismissAccessibilityLabel` (default "Dismiss" — pass a translated one), `style` (spacing around it), `testID`. An `error` is marked as an alert, and the other tones as a polite status: the web and Android announce them when they appear, while iOS reads the banner in place.',
+    rnComponent: null,
+    docsUrl: null,
+  },
   {
     name: "Accordion",
     description:
@@ -3214,7 +3296,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 +3447,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 +5543,14 @@ 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`.
+  // 1.166.0: additive (sc-10927) — the `Banner` primitive (a themed inline
+  //    error, warning, success or notice) and the `alert` component scope it
+  //    reads.
+  version: "1.166.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -39,6 +39,12 @@ export type ThemeWidgetStyles = Record<string, ThemeComponentStyle>;
  */
 export function normaliseThemeComponents(raw: unknown): ThemeComponents;
 
+/**
+ * What each token of the `alert` component scope resolves to while unset,
+ * keyed by token name: the values `<Banner>` paints an unthemed app with.
+ */
+export function bannerScopeDefaults(theme: unknown): Record<string, string | number>;
+
 /** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
 export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
 

package/dist/host.js

@@ -55,6 +55,10 @@ export {
   TOAST_DEFAULTS,
 } from "./toast-host.js";
 
+// What each `alert` scope token resolves to while unset, for the Studio's
+// Design page to preview beside its controls.
+export { bannerScopeDefaults } from "./banner-tokens.js";
+
 // REQ-NAV-STRUCTURE: the navigation resolver both hosts draw their chrome from.
 // `normaliseNavigation` turns a stored `theme_config.navigation` block into the
 // resolved `{ menuType }` — always `sidebar` since sc-7352 retired the other

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>;
@@ -3523,6 +3571,40 @@ export const Tabs: (props: {
   testID?: string;
 }) => any;
 
+export type BannerTone = "info" | "success" | "warning" | "error";
+
+/**
+ * Themed inline message: an error, warning, success or notice that stays in
+ * place until it is resolved. Its fill, text colour, border and corners come
+ * from the theme's `alert` scope, so every banner in the app matches. An
+ * `error` is marked as an alert and the other tones as a polite status: the
+ * web and Android announce them when they appear, iOS reads them in place.
+ * For a brief confirmation that may disappear on its own, use `useToast()`.
+ *
+ * @example
+ *   <Banner tone="error" message={error.message} action={{ label: "Retry", onPress: refetch }} />
+ */
+export const Banner: (props: {
+  /** Default "info". */
+  tone?: BannerTone;
+  /** Text is themed; an element renders as given. */
+  title?: ReactNode;
+  /** Text wraps onto as many lines as it needs; an element renders as given. */
+  message?: ReactNode;
+  /** A lucide name replacing the tone's glyph, or `false` for none. */
+  icon?: string | false | null;
+  action?: { label: string; onPress: () => void; accessibilityLabel?: string; testID?: string };
+  /** Shows a close control; hide the banner in the handler. */
+  onDismiss?: () => void;
+  /** Default "Dismiss". */
+  dismissAccessibilityLabel?: string;
+  /** For hosts rendering outside a widget context; widgets omit it. */
+  theme?: any;
+  style?: any;
+  /** The action and close control default to `<testID>-action` / `<testID>-dismiss`. */
+  testID?: string;
+}) => any;
+
 /**
  * Themed collapsible sections. The surface comes from the theme's `card`
  * scope and the headers and dividers from its `list` scope, so every

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.
@@ -268,6 +270,8 @@ export { Accordion, AccordionItem } from "./accordion.js";
 export { Tabs } from "./tabs.js";
 // Themed loading states; follow the theme's `loading` scope.
 export { Spinner, Skeleton } from "./loading.js";
+// A themed inline message; follows the theme's `alert` scope.
+export { Banner } from "./banner.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

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.
@@ -261,6 +263,8 @@ export { Accordion, AccordionItem } from "./accordion.native.js";
 export { Tabs } from "./tabs.native.js";
 // Themed loading states; follow the theme's `loading` scope.
 export { Spinner, Skeleton } from "./loading.native.js";
+// A themed inline message; follows the theme's `alert` scope.
+export { Banner } from "./banner.native.js";
 // The semantic text tiers, shared with the built-in widgets.
 export {
   textRoleStyle,

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/dist/readable-ink.js

@@ -0,0 +1,28 @@
+// The label colour for a fill an author chose. Picked by contrast between a
+// FIXED dark and a fixed light: the theme's own text colour is light on a
+// dark theme, so it cannot stand in for "the dark option".
+
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { contrastRatio, hexAlphaPercent, isHexColor, mixHex } from "./contract.js";
+
+export const INK_DARK = DEFAULT_THEME_TOKENS.colors.onSurface;
+export const INK_LIGHT = "#ffffff";
+
+/** A fill as the opaque colour it shows once painted over `surface`. */
+export function compositeOver(fill, surface) {
+  if (!isHexColor(fill)) return fill;
+  const backdrop = isHexColor(surface) ? surface : DEFAULT_THEME_TOKENS.colors.surface;
+  return mixHex(backdrop, fill, hexAlphaPercent(fill) / 100);
+}
+
+/**
+ * Whichever of the dark and light ink has the higher contrast on `fill`. A
+ * translucent fill is measured as it appears over `surface`.
+ */
+export function readableInk(fill, surface) {
+  if (!isHexColor(fill)) return INK_DARK;
+  const painted = compositeOver(fill, surface);
+  return contrastRatio(painted, INK_DARK) >= contrastRatio(painted, INK_LIGHT)
+    ? INK_DARK
+    : INK_LIGHT;
+}

package/dist/tabs-tokens.js

@@ -3,7 +3,8 @@
 // the same numbers and tests can pin them without a renderer.
 
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
-import { CONTRACT, contrastRatio } from "./contract.js";
+import { CONTRACT } from "./contract.js";
+import { readableInk } from "./readable-ink.js";
 
 export const TAB_STYLES = CONTRACT.themeComponentTabStyles;
 
@@ -56,7 +57,7 @@ export function resolveTabsTokens(theme, overrides) {
       pick(overrides, scope, "activeTextColor") ??
       (style === "pill"
         ? ownAccent
-          ? readableOn(ownAccent, colors)
+          ? readableInk(ownAccent, colors.surface)
           : colors.onPrimary
         : activeColor),
     textColor: pick(overrides, scope, "textColor") ?? colors.onSurfaceMuted,
@@ -66,10 +67,3 @@ export function resolveTabsTokens(theme, overrides) {
     rule: colors.border,
   };
 }
-
-// A chosen accent carries the label that reads best on it, dark or light.
-function readableOn(fill, colors) {
-  const dark = colors.onSurface;
-  const light = "#ffffff";
-  return contrastRatio(fill, dark) >= contrastRatio(fill, light) ? dark : light;
-}