@colixsystems/widget-sdk 0.196.0 → 0.198.0

package/dist/hooks.js

@@ -590,6 +590,91 @@ export function useNavigation() {
   return ctx.navigation;
 }
 
+/**
+ * sc-10268 — `{ uri }` an `<Image>` can show for a file the person picked but
+ * has not uploaded yet, such as a photo waiting in a composer. Native picks
+ * carry their own file uri; on the web the SDK makes a temporary object URL
+ * and releases it when the file changes or the component unmounts. `uri` is
+ * null for no file, or a host that cannot preview one.
+ */
+export function useFilePreview(file) {
+  const [uri, setUri] = useState(null);
+  useEffect(() => {
+    if (!file) {
+      setUri(null);
+      return undefined;
+    }
+    if (typeof file.uri === "string" && file.uri) {
+      setUri(file.uri);
+      return undefined;
+    }
+    const urls = typeof URL !== "undefined" ? URL : null;
+    const isBlob = typeof Blob !== "undefined" && file instanceof Blob;
+    if (!urls || typeof urls.createObjectURL !== "function" || !isBlob) {
+      setUri(null);
+      return undefined;
+    }
+    const objectUrl = urls.createObjectURL(file);
+    setUri(objectUrl);
+    return () => urls.revokeObjectURL(objectUrl);
+  }, [file]);
+  return { uri };
+}
+
+// A count the host can draw: a whole number, 0 for nothing to show.
+function _badgeCount(count) {
+  return typeof count === "number" && Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
+}
+
+/**
+ * sc-10268 — puts `count` on the menu entry or tab of the page this widget is
+ * on, such as a chat's unread messages. Returns `{ supported }`. The host sums
+ * every widget on the page and keeps the last count after the widget leaves
+ * the screen, until it reports again; 0 (or anything not a positive number)
+ * clears this widget's share. A host without page badges (the Builder canvas)
+ * ignores it.
+ */
+export function usePageBadge(count) {
+  const ctx = useWidgetContextOrThrow("usePageBadge");
+  const nav = ctx.navigation || {};
+  const setBadge = typeof nav.setBadge === "function" ? nav.setBadge : null;
+  const value = _badgeCount(count);
+  useEffect(() => {
+    if (setBadge) setBadge(value);
+  }, [setBadge, value]);
+  return { supported: Boolean(setBadge) };
+}
+
+/**
+ * sc-10268 — Android's back button, for a widget with pages of its own (a
+ * thread over a list, a settings page over a thread). `handler` runs on a
+ * back press while the widget's screen is in view; return true when it went
+ * back a step, false to let the app go back. Pass null while there is nothing
+ * to go back from. Returns `{ supported }`: false on the web, where browsers
+ * have no hardware back, so keep a visible back control there.
+ */
+export function useHardwareBack(handler) {
+  const ctx = useWidgetContextOrThrow("useHardwareBack");
+  const nav = ctx.navigation || {};
+  const subscribe =
+    typeof nav.onHardwareBack === "function" ? nav.onHardwareBack : null;
+  // Refs, so a new handler or context each render never re-subscribes.
+  const subscribeRef = useRef(subscribe);
+  subscribeRef.current = subscribe;
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  const active = Boolean(subscribe) && typeof handler === "function";
+  useEffect(() => {
+    if (!active) return undefined;
+    return subscribeRef.current(() =>
+      typeof handlerRef.current === "function"
+        ? Boolean(handlerRef.current())
+        : false,
+    );
+  }, [active]);
+  return { supported: Boolean(subscribe) };
+}
+
 const EMPTY_PARAMS = Object.freeze({});
 // Stable references so `useEffect([params])` / `[records]` don't re-fire every
 // render on a page that declares no parameters.
@@ -1863,6 +1948,15 @@ function toCameraError(err) {
   return new CameraError(code, message, { cause: err });
 }
 
+const CAMERA_PICK_LIMIT = 10;
+
+// One asset or a multi-pick's array: every one holds a host resource to free.
+function releaseCameraAssets(result) {
+  for (const item of Array.isArray(result) ? result : [result]) {
+    if (item && typeof item.release === "function") item.release();
+  }
+}
+
 /**
  * Take a photo or choose one from the device library. Returns
  *   `{ asset, loading, error, supported, capture, pick, reset }`.
@@ -1886,6 +1980,10 @@ function toCameraError(err) {
  *
  * Check `supported` before rendering a camera button; a host with no broker
  * reports false rather than throwing at render.
+ *
+ * `pick({ multiple: true })` lets the user choose up to 10 photos at once and
+ * resolves an array of assets (or `null` when dismissed); `asset` then holds
+ * that array. `capture()` always takes one photo.
  */
 export function useCamera(options) {
   const ctx = useWidgetContextOrThrow("useCamera");
@@ -1950,7 +2048,7 @@ export function useCamera(options) {
   // run through one request path — otherwise the loading/abort bookkeeping
   // would exist twice and drift.
   const request = useCallback(
-    async (method) => {
+    async (method, callOptions) => {
       const client = clientRef.current;
       if (
         !client ||
@@ -1969,17 +2067,16 @@ export function useCamera(options) {
       setError(null);
       try {
         inFlightRef.current += 1;
-        const next = await client[method](optionsRef.current || {});
+        const next = await client[method]({ ...(optionsRef.current || {}), ...(callOptions || {}) });
         // A reset() or a newer request landed while this one was open — drop
         // the result rather than clobbering what the widget now shows.
         if (run !== runRef.current) {
-          if (next && typeof next.release === "function") next.release();
+          releaseCameraAssets(next);
           return null;
         }
-        if (!next) return null;
+        if (!next || (Array.isArray(next) && next.length === 0)) return null;
         release();
-        releaseRef.current =
-          typeof next.release === "function" ? next.release : null;
+        releaseRef.current = () => releaseCameraAssets(next);
         setAsset(next);
         return next;
       } catch (err) {
@@ -2001,7 +2098,26 @@ export function useCamera(options) {
   );
 
   const capture = useCallback(() => request("capture"), [request]);
-  const pick = useCallback(() => request("pick"), [request]);
+  // sc-10268: pick({ multiple: true }) resolves an array of up to
+  // CAMERA_PICK_LIMIT photos, and { videos: true } offers videos beside them.
+  // Anything else (an onPress event) is a single photo.
+  const pick = useCallback(
+    (callOptions) => {
+      const opts = callOptions && typeof callOptions === "object" ? callOptions : {};
+      const many = opts.multiple === true;
+      const videos = opts.videos === true;
+      return request(
+        "pick",
+        many || videos
+          ? {
+              ...(many ? { multiple: true, limit: CAMERA_PICK_LIMIT } : null),
+              ...(videos ? { videos: true } : null),
+            }
+          : undefined,
+      );
+    },
+    [request],
+  );
 
   return { asset, loading, error, supported, capture, pick, reset };
 }
@@ -3596,7 +3712,9 @@ export function useDatastoreMutation(table) {
     [resolveNs],
   );
 
-  return { create, update, delete: del };
+  // sc-10268: one object while the methods are unchanged, so a widget can list
+  // the mutation in a dependency array without re-running every render.
+  return useMemo(() => ({ create, update, delete: del }), [create, update, del]);
 }
 
 /**
@@ -4303,8 +4421,10 @@ export function useAssetsByTag(tag, options) {
 // owned by the signed-in app user (ctx.user.id). The widget only chooses the
 // space. PUBLIC is world-readable, so its files resolve even when there is no
 // signed-in user (ctx.workspace.id is set for a logged-out Player visitor too).
-function _filestoreOwnerId(ctx, spaceType) {
+// sc-10269: a RECORD space is owned by the datastore record the widget names.
+function _filestoreOwnerId(ctx, spaceType, recordId) {
   const space = String(spaceType || "project").toUpperCase();
+  if (space === "RECORD") return recordId || null;
   if (space === "PERSONAL") return (ctx.user && ctx.user.id) || null;
   return (ctx.workspace && ctx.workspace.id) || null;
 }
@@ -4312,8 +4432,9 @@ function _filestoreOwnerId(ctx, spaceType) {
 /**
  * Browse the end-user's Filestore files. Returns { files, loading, error,
  * refetch }. The widget passes only the SPACE (`{ spaceType, folderId, q,
- * type }`); the hook resolves owner_id from the host context (tenant for
- * project, app user for personal) and calls
+ * type }`, plus `recordId` for a `record` space); the hook resolves owner_id
+ * from the host context (tenant for project, app user for personal, the named
+ * record for record) and calls
  * `ctx.filestore.files.list({ space_type, owner_id, folder_id, q, type })`,
  * unwrapping the `{ data, meta }` envelope to the files array. When the owner
  * can't be resolved (no signed-in user for a personal space) it collapses to an
@@ -4330,8 +4451,8 @@ export function useFilestoreFiles(options) {
       "useFilestoreFiles: host did not inject a filestore client (ctx.filestore.files.list)",
     );
   }
-  const { spaceType = "project", folderId = null, q, type } = options || {};
-  const ownerId = _filestoreOwnerId(ctx, spaceType);
+  const { spaceType = "project", recordId = null, folderId = null, q, type } = options || {};
+  const ownerId = _filestoreOwnerId(ctx, spaceType, recordId);
 
   const [files, setFiles] = useState([]);
   const [loading, setLoading] = useState(true);
@@ -4468,9 +4589,10 @@ export function useFilestoreFile(fileId) {
 /**
  * sc-1378 — upload a file into the end-user's Filestore space. Returns
  * `{ upload, uploading, error, lastUploaded }`. The widget passes the
- * SPACE (`{ spaceType, folderId? }`); the hook resolves `owner_id` the
- * same way the read hooks do (tenant for PROJECT, app user for PERSONAL)
- * and posts a multipart FormData to `ctx.filestore.files.upload`.
+ * SPACE (`{ spaceType, folderId? }`, or `{ spaceType: "record", recordId }`
+ * to attach the file to a datastore record); the hook resolves `owner_id` the
+ * same way the read hooks do (tenant for PROJECT, app user for PERSONAL, the
+ * record for RECORD) and posts a multipart FormData to `ctx.filestore.files.upload`.
  *
  * `upload(file, { folderId?, fileName? })` takes a browser `File` on the web
  * Player and expo-file-system's `File` on the Expo export, as `<FilePicker>`,
@@ -4502,10 +4624,11 @@ export function useFilestoreUpload(options) {
   }
   const {
     spaceType = "project",
+    recordId = null,
     folderId: defaultFolderId = null,
     compress: defaultCompress = true,
   } = options || {};
-  const ownerId = _filestoreOwnerId(ctx, spaceType);
+  const ownerId = _filestoreOwnerId(ctx, spaceType, recordId);
 
   const [uploading, setUploading] = useState(false);
   const [error, setError] = useState(null);
@@ -4901,11 +5024,13 @@ export function useFilestoreCreateFolder(options) {
 
 /**
  * Copy a Filestore file into any space and folder the caller may add files
- * to — including ACROSS spaces (project, public, the user's personal space).
- * Returns `{ copy, copying, error, lastCopied }`.
+ * to — including ACROSS spaces (project, public, the user's personal space,
+ * a datastore record's attachments). Returns `{ copy, copying, error, lastCopied }`.
  *
- * `copy(fileId, { spaceType, folderId?, name? })` names the DESTINATION;
- * `spaceType` is required. The hook resolves the destination owner_id the same
+ * `copy(fileId, { spaceType, recordId?, folderId?, name? })` names the
+ * DESTINATION; `spaceType` is required, and `{ spaceType: "record", recordId }`
+ * attaches the copy to that record (write access to it is needed; a record has
+ * no folders). The hook resolves the destination owner_id the same
  * way the upload hook does and posts through `ctx.filestore.files.copy`. It
  * resolves to the NEW file row (its own id and url); the source is untouched.
  * A name already taken at the destination lands as "name (2).ext" rather than
@@ -4938,11 +5063,14 @@ export function useFilestoreCopy() {
 
   const copy = useCallback(async (fileId, destination) => {
     if (!fileId) throw new Error("useFilestoreCopy: fileId is required");
-    const { spaceType, folderId, name } = destination || {};
+    const { spaceType, recordId, folderId, name } = destination || {};
     if (!spaceType) {
       throw new Error("useFilestoreCopy: destination spaceType is required");
     }
-    const ownerId = _filestoreOwnerId(ctxRef.current, spaceType);
+    if (String(spaceType).toUpperCase() === "RECORD" && !recordId) {
+      throw new Error("useFilestoreCopy: a record destination needs its recordId");
+    }
+    const ownerId = _filestoreOwnerId(ctxRef.current, spaceType, recordId);
     if (!ownerId) {
       const err = new Error("Sign in to copy files");
       setError(err);
@@ -4971,6 +5099,48 @@ export function useFilestoreCopy() {
   return { copy, copying, error, lastCopied };
 }
 
+/**
+ * sc-10269 — delete a Filestore file the caller may delete. Returns
+ * `{ remove, removing, error }`. `remove(fileId)` calls
+ * `ctx.filestore.files.remove`: a record attachment is deleted permanently and
+ * only its uploader may do it; a file in any other space moves to the trash.
+ * Refusals arrive as `err.status` (403 not permitted, 404 not visible).
+ */
+export function useFilestoreDelete() {
+  const ctx = useWidgetContextOrThrow("useFilestoreDelete");
+  if (
+    !ctx.filestore ||
+    !ctx.filestore.files ||
+    typeof ctx.filestore.files.remove !== "function"
+  ) {
+    throw new Error(
+      "useFilestoreDelete: host did not inject a filestore client (ctx.filestore.files.remove)",
+    );
+  }
+
+  const [removing, setRemoving] = useState(false);
+  const [error, setError] = useState(null);
+
+  const filesRef = useRef(ctx.filestore.files);
+  filesRef.current = ctx.filestore.files;
+
+  const remove = useCallback(async (fileId) => {
+    if (!fileId) throw new Error("useFilestoreDelete: fileId is required");
+    setRemoving(true);
+    setError(null);
+    try {
+      await filesRef.current.remove(fileId);
+      setRemoving(false);
+    } catch (err) {
+      setError(err);
+      setRemoving(false);
+      throw err;
+    }
+  }, []);
+
+  return { remove, removing, error };
+}
+
 /**
  * Drive a BankID signing flow for one Filestore file. Returns
  * `{ status, qr, autoStartToken, message, signerName, signedAt, verdict,
@@ -6521,7 +6691,7 @@ export function usePayments() {
 /* ============================================================================
  * NOTIFICATIONS CLIENT — ctx.notifications (@colixsystems/notifications-client)
  *
- * send. Covers: useSendNotification.
+ * send, mutes. Covers: useSendNotification, useRecordMute.
  * ==========================================================================*/
 
 /**
@@ -6539,7 +6709,9 @@ export function usePayments() {
  *   - "INTERNAL"             — anything else (network, 5xx)
  *
  * The server's stable `code` (when volunteered in the error body) is preserved
- * over the status-derived one.
+ * over the status-derived one. `useRecordMute` adds "RECORD_NOT_FOUND" (404:
+ * the record is missing or the user cannot read it), "INVALID_MUTED_UNTIL",
+ * "INVALID_RECORD_REF" and "NOTIFICATIONS_UNAVAILABLE" (no mute client here).
  */
 export class NotificationError extends Error {
   constructor(code, message, opts) {
@@ -6550,7 +6722,7 @@ export class NotificationError extends Error {
   }
 }
 
-function toNotificationError(err) {
+function toNotificationError(err, notFoundCode = "RECIPIENT_NOT_FOUND") {
   if (err instanceof NotificationError) return err;
   // The injected notifications-client rejects with its own NotificationError
   // subclass carrying { code, status }; the host facade may instead throw an
@@ -6562,18 +6734,21 @@ function toNotificationError(err) {
       : err && typeof err.status === "number"
         ? err.status
         : null;
+  // The client keeps the server body at err.details; its own err.code is a
+  // per-status class default, so it only answers when nothing else does.
   const bodyCode =
     (err && err.response && err.response.data && err.response.data.code) ||
-    (err && typeof err.code === "string" ? err.code : null);
+    (err && err.details && typeof err.details.code === "string" ? err.details.code : null);
   const bodyMessage =
     err && err.response && err.response.data && err.response.data.error;
   let code = "INTERNAL";
   if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
   else if (status === 401) code = "AUTH_REQUIRED";
   else if (status === 403) code = "FORBIDDEN";
-  else if (status === 404) code = "RECIPIENT_NOT_FOUND";
+  else if (status === 404) code = notFoundCode;
   else if (status === 429) code = "RATE_LIMITED";
   else if (status === 400) code = "VALIDATION";
+  else if (err && typeof err.code === "string" && err.code) code = err.code;
   const message =
     (typeof bodyMessage === "string" && bodyMessage) ||
     (err && typeof err.message === "string"
@@ -6638,3 +6813,335 @@ export function useSendNotification() {
 
   return { send, sending, error };
 }
+
+const _NOT_MUTED = Object.freeze({ muted: false, mutedUntil: null });
+// setTimeout overflows past ~24.8 days; a later expiry waits for a refetch.
+const _MAX_TIMER_MS = 2147483647;
+
+const _RECORD_MUTE_IDLE = Object.freeze({
+  muted: false,
+  mutedUntil: null,
+  loading: false,
+  error: null,
+  mute: async () => undefined,
+  unmute: async () => undefined,
+  refetch: async () => undefined,
+});
+
+// `mute(until)` input → the wire's ISO string, or null for until unmuted.
+function _muteUntilIso(until) {
+  if (until === undefined || until === null) return null;
+  const at =
+    until instanceof Date ? until : typeof until === "string" ? new Date(until) : null;
+  if (!at || Number.isNaN(at.getTime())) {
+    throw new NotificationError(
+      "INVALID_MUTED_UNTIL",
+      "useRecordMute: mute(until) takes an ISO time, a Date, or null for until unmuted",
+    );
+  }
+  return at.toISOString();
+}
+
+function _muteStateFrom(wire) {
+  if (!wire || !wire.muted) return _NOT_MUTED;
+  return {
+    muted: true,
+    mutedUntil: typeof wire.muted_until === "string" ? wire.muted_until : null,
+  };
+}
+
+/**
+ * sc-10268 — the signed-in user's mute of the notifications ONE datastore
+ * record produces for them (a chat conversation, a thread). Returns
+ * `{ muted, mutedUntil, loading, error, mute, unmute, refetch }`.
+ *
+ * `mute(until)` takes an ISO time or a `Date`, or `null` (or nothing) to mute
+ * until `unmute()`. While muted, a server action's
+ * `notifications.notifyRecordSubjects` on the record sends this user nothing:
+ * no inbox row, no push, no email. `mutedUntil` is an ISO string, or null when
+ * muted until unmuted; `muted` turns false on its own once `mutedUntil` passes.
+ *
+ * The user must be able to read the record; otherwise every call fails with
+ * `NotificationError { code: "RECORD_NOT_FOUND" }`, exactly as for a missing
+ * record. A falsy `tableId` / `recordId` collapses to a stable not-muted result
+ * with no network call. A host without `ctx.notifications.mutes` (the Builder
+ * canvas preview) reads not muted, and `mute` / `unmute` reject with
+ * `NOTIFICATIONS_UNAVAILABLE` rather than the hook throwing at render.
+ */
+export function useRecordMute(tableId, recordId) {
+  const ctx = useWidgetContextOrThrow("useRecordMute");
+  const mutes = ctx.notifications && ctx.notifications.mutes;
+  const available =
+    Boolean(mutes) &&
+    typeof mutes.get === "function" &&
+    typeof mutes.set === "function" &&
+    typeof mutes.clear === "function";
+  const ready = Boolean(tableId && recordId);
+
+  const mutesRef = useRef(null);
+  mutesRef.current = available ? mutes : null;
+  const recordRef = useRef(null);
+  recordRef.current = ready ? { table_id: tableId, record_id: recordId } : null;
+
+  const [state, setState] = useState(_NOT_MUTED);
+  const [loading, setLoading] = useState(ready && available);
+  const [error, setError] = useState(null);
+  // Each read or write takes a ticket; only the latest may land its result.
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const client = mutesRef.current;
+    const record = recordRef.current;
+    if (!client || !record) {
+      setState(_NOT_MUTED);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const wire = await client.get(record);
+      if (runRef.current !== myRun) return;
+      setState(_muteStateFrom(wire));
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toNotificationError(err, "RECORD_NOT_FOUND"));
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    setState(_NOT_MUTED);
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tableId, recordId, available]);
+
+  // Another instance on the same record (a list's sheet, a header's bell)
+  // that mutes or unmutes it updates this one too.
+  useEffect(() => {
+    if (!ready) return undefined;
+    const listener = (changedTable, changedRecord, next) => {
+      if (changedTable !== tableId || changedRecord !== recordId) return;
+      runRef.current += 1;
+      setState(next);
+      setLoading(false);
+    };
+    _muteListeners.add(listener);
+    return () => {
+      _muteListeners.delete(listener);
+    };
+  }, [ready, tableId, recordId]);
+
+  useEffect(() => {
+    if (!state.muted || !state.mutedUntil) return undefined;
+    const remaining = Date.parse(state.mutedUntil) - Date.now();
+    if (!(remaining <= _MAX_TIMER_MS)) return undefined;
+    const timer = setTimeout(() => setState(_NOT_MUTED), Math.max(remaining, 0));
+    return () => clearTimeout(timer);
+  }, [state]);
+
+  const write = useCallback(async (perform) => {
+    const client = mutesRef.current;
+    if (!client) {
+      const err = new NotificationError(
+        "NOTIFICATIONS_UNAVAILABLE",
+        "Muting notifications is not available here",
+      );
+      setError(err);
+      throw err;
+    }
+    const record = recordRef.current;
+    if (!record) return;
+    const myRun = ++runRef.current;
+    setError(null);
+    try {
+      const next = await perform(client, record);
+      _announceMute(record.table_id, record.record_id, next);
+      if (runRef.current === myRun) {
+        setState(next);
+        setLoading(false);
+      }
+    } catch (err) {
+      const e = toNotificationError(err, "RECORD_NOT_FOUND");
+      setError(e);
+      throw e;
+    }
+  }, []);
+
+  const mute = useCallback(
+    (until) => {
+      let mutedUntil;
+      try {
+        mutedUntil = _muteUntilIso(until);
+      } catch (err) {
+        setError(err);
+        return Promise.reject(err);
+      }
+      return write(async (client, record) =>
+        _muteStateFrom(await client.set({ ...record, muted_until: mutedUntil })),
+      );
+    },
+    [write],
+  );
+
+  const unmute = useCallback(
+    () =>
+      write(async (client, record) => {
+        await client.clear(record);
+        return _NOT_MUTED;
+      }),
+    [write],
+  );
+
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  if (!ready) return _RECORD_MUTE_IDLE;
+  return { muted: state.muted, mutedUntil: state.mutedUntil, loading, error, mute, unmute, refetch };
+}
+
+// A useRecordMute write is announced, so every useRecordMutes list on the
+// same table shows it at once, without a second read.
+const _muteListeners = new Set();
+
+function _announceMute(tableId, recordId, state) {
+  for (const listener of _muteListeners) listener(tableId, recordId, state);
+}
+
+const _MUTED_RECORDS_PAGE = 200;
+// Bounds one load to 1,000 mutes, however many a user has on a table.
+const _MUTED_RECORDS_MAX_PAGES = 5;
+const _NO_MUTED_RECORDS = Object.freeze({});
+
+// { [recordId]: mutedUntil } with one record's new state applied.
+function _withMuteState(byId, recordId, state) {
+  const next = { ...byId };
+  if (state && state.muted) next[recordId] = state.mutedUntil;
+  else delete next[recordId];
+  return Object.freeze(next);
+}
+
+function _isMutedAt(byId, recordId, now) {
+  if (!recordId || !Object.prototype.hasOwnProperty.call(byId, recordId)) return false;
+  const until = byId[recordId];
+  return until === null || Date.parse(until) > now;
+}
+
+// The soonest future time a timed mute in the map lapses, or Infinity.
+function _nextMuteLapse(byId, now) {
+  let soonest = Infinity;
+  for (const recordId of Object.keys(byId)) {
+    const at = byId[recordId] === null ? NaN : Date.parse(byId[recordId]);
+    if (at > now && at < soonest) soonest = at;
+  }
+  return soonest;
+}
+
+const _RECORD_MUTES_IDLE = Object.freeze({
+  isMuted: () => false,
+  loading: false,
+  error: null,
+  refetch: async () => {},
+});
+
+/**
+ * sc-10268 — which records of one table the signed-in user has muted, read in
+ * one request for a whole list (a chat's conversations), never one per row.
+ * Returns `{ isMuted(recordId), loading, error, refetch }`.
+ *
+ * Only active mutes count, and `isMuted` turns false by itself once a timed
+ * mute lapses. A mute or unmute made through `useRecordMute` on the same table
+ * shows here at once. A falsy `tableId`, or a host without
+ * `ctx.notifications.mutes.list` (the Builder canvas preview), reads nothing
+ * muted with no network call.
+ */
+export function useRecordMutes(tableId) {
+  const ctx = useWidgetContextOrThrow("useRecordMutes");
+  const mutes = ctx.notifications && ctx.notifications.mutes;
+  const available = Boolean(mutes) && typeof mutes.list === "function";
+
+  const mutesRef = useRef(null);
+  mutesRef.current = available ? mutes : null;
+  const tableRef = useRef(null);
+  tableRef.current = tableId || null;
+
+  const [byId, setById] = useState(_NO_MUTED_RECORDS);
+  const [now, setNow] = useState(() => Date.now());
+  const [loading, setLoading] = useState(Boolean(tableId) && available);
+  const [error, setError] = useState(null);
+  const runRef = useRef(0);
+
+  const doFetch = useCallback(async () => {
+    const myRun = ++runRef.current;
+    const client = mutesRef.current;
+    const table = tableRef.current;
+    if (!client || !table) {
+      setById(_NO_MUTED_RECORDS);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const next = {};
+      for (let page = 0; page < _MUTED_RECORDS_MAX_PAGES; page += 1) {
+        const offset = page * _MUTED_RECORDS_PAGE;
+        const res = await client.list({ table_id: table, limit: _MUTED_RECORDS_PAGE, offset });
+        if (runRef.current !== myRun) return;
+        const rows = res && Array.isArray(res.data) ? res.data : [];
+        for (const row of rows) {
+          if (row && typeof row.record_id === "string") {
+            next[row.record_id] = typeof row.muted_until === "string" ? row.muted_until : null;
+          }
+        }
+        const total = res && res.meta && Number.isFinite(res.meta.total) ? res.meta.total : 0;
+        if (rows.length < _MUTED_RECORDS_PAGE || offset + rows.length >= total) break;
+      }
+      setById(Object.freeze(next));
+      setNow(Date.now());
+      setLoading(false);
+    } catch (err) {
+      if (runRef.current !== myRun) return;
+      setError(toNotificationError(err, "INVALID_TABLE_ID"));
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    setById(_NO_MUTED_RECORDS);
+    doFetch();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tableId, available]);
+
+  useEffect(() => {
+    const listener = (table, recordId, state) => {
+      if (table !== tableRef.current) return;
+      setById((prev) => _withMuteState(prev, recordId, state));
+      setNow(Date.now());
+    };
+    _muteListeners.add(listener);
+    return () => {
+      _muteListeners.delete(listener);
+    };
+  }, []);
+
+  useEffect(() => {
+    const remaining = _nextMuteLapse(byId, now) - Date.now();
+    if (!(remaining <= _MAX_TIMER_MS)) return undefined;
+    const timer = setTimeout(() => setNow(Date.now()), Math.max(remaining, 0));
+    return () => clearTimeout(timer);
+  }, [byId, now]);
+
+  const isMuted = useCallback((recordId) => _isMutedAt(byId, recordId, now), [byId, now]);
+  const refetch = useCallback(async () => {
+    await doFetch();
+  }, [doFetch]);
+
+  if (!tableId) return _RECORD_MUTES_IDLE;
+  return { isMuted, loading, error, refetch };
+}