@stapel/workspaces-react 0.13.0 → 0.15.0

package/src/headless/RoleSelect.tsx

@@ -1,14 +1,16 @@
 import type { ReactNode } from "react";
-import { useI18n } from "@stapel/core";
-import type { StapelApiError } from "@stapel/core";
+import { loadStateFromQuery, useI18n } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
 import type { RoleInfo } from "../api/types.js";
 import { useRoles } from "../model/queries.js";
 
 /** Render-prop bag for {@link RoleSelect}. */
 export interface RoleSelectBag {
   /** The effective registry (GET /roles): builtin four + the deployment's
-   * overlay, rank-descending. Empty while loading. */
-  readonly roles: readonly RoleInfo[];
+   * overlay, rank-descending. A state rather than an array: a role picker
+   * built from `[]` because the registry read FAILED offers no roles at all
+   * and looks exactly like a deployment that defined none. */
+  readonly state: LoadState<readonly RoleInfo[]>;
   /**
    * Display label for a role key: the i18n key `workspaces.role.<key>` when
    * the current locale's merged bundle carries it (the pair ships the builtin
@@ -18,9 +20,6 @@ export interface RoleSelectBag {
    * never render as a dotted i18n key.
    */
   labelFor(role: string): string;
-  readonly isLoading: boolean;
-  readonly isError: boolean;
-  readonly error: StapelApiError | null;
 }
 
 /**
@@ -30,9 +29,16 @@ export interface RoleSelectBag {
  *
  * ```tsx
  * <RoleSelect>
- *   {({ roles, labelFor }) => (
- *     <Select options={roles.map((r) => ({ value: r.role, label: labelFor(r.role) }))} />
- *   )}
+ *   {({ state, labelFor }) =>
+ *     matchList(state, {
+ *       loading: () => <Select loading options={[]} />,
+ *       failed: (error) => <RoleLoadFailed error={error} />,
+ *       empty: () => <Select disabled options={[]} />,
+ *       ready: (roles) => (
+ *         <Select options={roles.map((r) => ({ value: r.role, label: labelFor(r.role) }))} />
+ *       ),
+ *     })
+ *   }
  * </RoleSelect>
  * ```
  *
@@ -49,10 +55,7 @@ export function RoleSelect(props: {
   // must show its raw name, not `workspaces.role.secretary`).
   const bundle = i18n.getBundle();
   return props.children({
-    roles: query.data ?? [],
+    state: loadStateFromQuery(query),
     labelFor: (role) => bundle[`workspaces.role.${role}`] ?? role,
-    isLoading: query.isLoading,
-    isError: query.isError,
-    error: query.error ?? null,
   });
 }

package/src/headless/WorkspaceList.tsx

@@ -1,25 +1,34 @@
 import type { ReactNode } from "react";
-import type { StapelApiError } from "@stapel/core";
+import { loadStateFromQuery, mapLoad } from "@stapel/core";
+import type { LoadState, StapelApiError } from "@stapel/core";
 import type { Workspace, WorkspaceCreate } from "../api/types.js";
 import { useWorkspaces } from "../model/queries.js";
 import { useCreateWorkspace } from "../model/mutations.js";
 
 /** Render-prop bag for {@link WorkspaceList}. */
 export interface WorkspaceListBag {
-  /** The caller's workspaces once loaded (empty before load). */
-  readonly workspaces: readonly Workspace[];
-  /** The initial list load is in flight (no data yet). */
-  readonly isLoading: boolean;
-  /** Either the read or the create failed. */
-  readonly isError: boolean;
-  /** The error, when `isError` (a localizable `StapelApiError`), else null. */
-  readonly error: StapelApiError | null;
+  /**
+   * The read, as a state a skin cannot flatten: `loading` / `ready` with the
+   * rows / `failed` with the error. Render it with core's `matchList`, whose
+   * four arms are all required, so "you have no workspaces" can only be said
+   * about a load that actually succeeded.
+   *
+   * This replaced a `workspaces: readonly Workspace[]` field that was `[]` in
+   * all three cases. On 2026-08-09 the list endpoint answered 404 for hours
+   * and every screen built on that field said the person had no workspaces.
+   * The bag carried `isError` beside it the whole time; nothing forced a skin
+   * to look, so nothing did.
+   */
+  readonly state: LoadState<readonly Workspace[]>;
   /** Create a workspace (owner-seeded). */
   create(body: WorkspaceCreate): void;
   /** A create call is in flight. */
   readonly isCreating: boolean;
   /** The workspace created by the last `create`, else null. */
   readonly created: Workspace | null;
+  /** The CREATE's failure — a write, and therefore a different question from
+   * {@link state}, which is about the read. */
+  readonly createError: StapelApiError | null;
   /** Refetch the list from the server. */
   refetch(): void;
 }
@@ -32,7 +41,14 @@ export interface WorkspaceListBag {
  *
  * ```tsx
  * <WorkspaceList>
- *   {({ workspaces, create }) => ( ... )}
+ *   {({ state, create }) =>
+ *     matchList(state, {
+ *       loading: () => <Spinner />,
+ *       failed: (error) => <ErrorPanel error={error} onRetry={refetch} />,
+ *       empty: () => <FirstWorkspacePrompt onCreate={create} />,
+ *       ready: (workspaces) => <List items={workspaces} />,
+ *     })
+ *   }
  * </WorkspaceList>
  * ```
  */
@@ -42,15 +58,16 @@ export function WorkspaceList(props: {
   const query = useWorkspaces();
   const mutation = useCreateWorkspace();
   return props.children({
-    workspaces: query.data?.workspaces ?? [],
-    isLoading: query.isLoading,
-    isError: query.isError || mutation.isError,
-    error: query.error ?? mutation.error ?? null,
+    // `workspaces` is optional in the wire schema, so a SUCCESSFUL response
+    // may legitimately carry none. That is an empty list, not a failed load —
+    // the distinction this whole field exists for is already made above it.
+    state: mapLoad(loadStateFromQuery(query), (list) => list.workspaces ?? []),
     create: (body) => {
       mutation.mutate(body);
     },
     isCreating: mutation.isPending,
     created: mutation.data ?? null,
+    createError: mutation.error ?? null,
     refetch: () => {
       void query.refetch();
     },

package/src/i18n/generated/errors.es.gen.ts

@@ -56,6 +56,7 @@ export const workspacesErrorBundleEs: Record<WorkspacesErrorCode, string> = {
   "error.403.role_exceeds_inviter_rank": "No puedes conceder un rol superior al tuyo ({role})",
   "error.403.verification_enrollment_required": "Es necesario registrar un factor de verificación.",
   "error.403.verification_required": "Se requiere verificación adicional",
+  "error.403.workspace_creation_closed": "Esta instancia no te permite crear espacios de trabajo",
   "error.404.ad_not_found": "Anuncio no encontrado",
   "error.404.invitation_not_found": "Invitación no encontrada",
   "error.404.member_not_found": "Miembro no encontrado en este espacio de trabajo",
@@ -73,6 +74,7 @@ export const workspacesErrorBundleEs: Record<WorkspacesErrorCode, string> = {
   "error.422.unprocessable_entity": "Entidad no procesable",
   "error.423.locked": "El recurso está bloqueado",
   "error.423.verification_locked": "Demasiados intentos fallidos — verificación bloqueada",
+  "error.429.invitation_resend_cooldown": "Esta invitación se envió por correo hace poco; puedes volver a enviarla en {retry_after} segundos",
   "error.429.rate_limit": "Demasiados intentos. Inténtalo de nuevo en {retry_after_minutes} minutos.",
   "error.429.too_many_requests": "Demasiadas solicitudes. Inténtalo de nuevo más tarde.",
   "error.500.internal": "Algo salió mal",

package/src/i18n/generated/errors.gen.ts

@@ -79,6 +79,7 @@ export const WORKSPACES_ERRORS = {
   "error.403.role_exceeds_inviter_rank": { status: 403, params: ["role"], remediation: "fix_input", en: "You cannot grant a role that outranks your own ({role})" },
   "error.403.verification_enrollment_required": { status: 403, params: [], remediation: "verify", en: "Verification factor enrollment required" },
   "error.403.verification_required": { status: 403, params: [], remediation: "verify", en: "Additional verification required" },
+  "error.403.workspace_creation_closed": { status: 403, params: [], remediation: "contact_support", en: "This instance does not allow you to create workspaces" },
   "error.404.ad_not_found": { status: 404, params: [], remediation: "retry", en: "Listing not found" },
   "error.404.invitation_not_found": { status: 404, params: [], remediation: "fix_input", en: "Invitation not found" },
   "error.404.member_not_found": { status: 404, params: [], remediation: "fix_input", en: "Member not found in this workspace" },
@@ -96,6 +97,7 @@ export const WORKSPACES_ERRORS = {
   "error.422.unprocessable_entity": { status: 422, params: [], remediation: "wait_and_retry", en: "Unprocessable entity" },
   "error.423.locked": { status: 423, params: [], remediation: "wait_and_retry", en: "Resource is locked" },
   "error.423.verification_locked": { status: 423, params: [], remediation: "wait_and_retry", en: "Too many failed attempts — verification locked" },
+  "error.429.invitation_resend_cooldown": { status: 429, params: ["retry_after"], remediation: "wait_and_retry", en: "This invitation was emailed recently; you can send it again in {retry_after} seconds" },
   "error.429.rate_limit": { status: 429, params: ["retry_after_minutes"], remediation: "wait_and_retry", en: "Too many attempts. Try again in {retry_after_minutes} minutes." },
   "error.429.too_many_requests": { status: 429, params: [], remediation: "wait_and_retry", en: "Too many requests. Please try again later." },
   "error.500.internal": { status: 500, params: [], remediation: "contact_support", en: "Something went wrong" },
@@ -152,6 +154,7 @@ export const WORKSPACES_ERROR_CODES: readonly WorkspacesErrorCode[] = [
   "error.403.role_exceeds_inviter_rank",
   "error.403.verification_enrollment_required",
   "error.403.verification_required",
+  "error.403.workspace_creation_closed",
   "error.404.ad_not_found",
   "error.404.invitation_not_found",
   "error.404.member_not_found",
@@ -169,6 +172,7 @@ export const WORKSPACES_ERROR_CODES: readonly WorkspacesErrorCode[] = [
   "error.422.unprocessable_entity",
   "error.423.locked",
   "error.423.verification_locked",
+  "error.429.invitation_resend_cooldown",
   "error.429.rate_limit",
   "error.429.too_many_requests",
   "error.500.internal",
@@ -227,6 +231,7 @@ export const workspacesErrorBundleEn: Record<WorkspacesErrorCode, string> = {
   "error.403.role_exceeds_inviter_rank": "You cannot grant a role that outranks your own ({role})",
   "error.403.verification_enrollment_required": "Verification factor enrollment required",
   "error.403.verification_required": "Additional verification required",
+  "error.403.workspace_creation_closed": "This instance does not allow you to create workspaces",
   "error.404.ad_not_found": "Listing not found",
   "error.404.invitation_not_found": "Invitation not found",
   "error.404.member_not_found": "Member not found in this workspace",
@@ -244,6 +249,7 @@ export const workspacesErrorBundleEn: Record<WorkspacesErrorCode, string> = {
   "error.422.unprocessable_entity": "Unprocessable entity",
   "error.423.locked": "Resource is locked",
   "error.423.verification_locked": "Too many failed attempts — verification locked",
+  "error.429.invitation_resend_cooldown": "This invitation was emailed recently; you can send it again in {retry_after} seconds",
   "error.429.rate_limit": "Too many attempts. Try again in {retry_after_minutes} minutes.",
   "error.429.too_many_requests": "Too many requests. Please try again later.",
   "error.500.internal": "Something went wrong",

package/src/i18n/generated/errors.json

@@ -341,6 +341,13 @@
     "remediation": "verify",
     "en": "Additional verification required"
   },
+  {
+    "code": "error.403.workspace_creation_closed",
+    "status": 403,
+    "params": [],
+    "remediation": "contact_support",
+    "en": "This instance does not allow you to create workspaces"
+  },
   {
     "code": "error.404.ad_not_found",
     "status": 404,
@@ -460,6 +467,15 @@
     "remediation": "wait_and_retry",
     "en": "Too many failed attempts — verification locked"
   },
+  {
+    "code": "error.429.invitation_resend_cooldown",
+    "status": 429,
+    "params": [
+      "retry_after"
+    ],
+    "remediation": "wait_and_retry",
+    "en": "This invitation was emailed recently; you can send it again in {retry_after} seconds"
+  },
   {
     "code": "error.429.rate_limit",
     "status": 429,

package/src/i18n/generated/errors.ru.gen.ts

@@ -56,6 +56,7 @@ export const workspacesErrorBundleRu: Record<WorkspacesErrorCode, string> = {
   "error.403.role_exceeds_inviter_rank": "Вы не можете выдать роль, которая превышает вашу собственную ({role})",
   "error.403.verification_enrollment_required": "Требуется регистрация фактора подтверждения.",
   "error.403.verification_required": "Требуется дополнительная проверка",
+  "error.403.workspace_creation_closed": "На этом сервере вам недоступно создание рабочих пространств",
   "error.404.ad_not_found": "Объявление не найдено",
   "error.404.invitation_not_found": "Приглашение не найдено",
   "error.404.member_not_found": "Участник не найден в этом рабочем пространстве",
@@ -73,6 +74,7 @@ export const workspacesErrorBundleRu: Record<WorkspacesErrorCode, string> = {
   "error.422.unprocessable_entity": "Невозможно обработать данные запроса",
   "error.423.locked": "Ресурс заблокирован",
   "error.423.verification_locked": "Слишком много неудачных попыток — подтверждение заблокировано",
+  "error.429.invitation_resend_cooldown": "Это приглашение недавно отправлялось; отправить снова можно через {retry_after} с",
   "error.429.rate_limit": "Слишком много попыток. Повторите попытку через {retry_after_minutes} мин.",
   "error.429.too_many_requests": "Слишком много запросов. Пожалуйста, повторите попытку позже.",
   "error.500.internal": "Что-то пошло не так",

package/src/i18n/keys.ts

@@ -12,13 +12,26 @@ import { workspacesErrorBundleEn } from "./generated/errors.gen.js";
  */
 export const WORKSPACES_I18N_KEYS = {
   unknownError: "workspaces.error.unknown",
+  // Retry affordance beside a stated failure — an error a person cannot act
+  // on is only half the message.
+  retry: "workspaces.retry",
   // Workspace list (WorkspaceList headless)
   listLoading: "workspaces.list.loading",
   listEmpty: "workspaces.list.empty",
+  /**
+   * "We could not load your workspaces" — the sentence whose ABSENCE was the
+   * 2026-08-09 incident. Deliberately about US failing to load, never about
+   * the person having none, and never a 404's "no longer available" (which
+   * asserts the thing does not exist — tracker #211).
+   */
+  listLoadFailed: "workspaces.list.load_failed",
   listCreate: "workspaces.list.create",
   listCreating: "workspaces.list.creating",
   // Members (Members headless)
   membersLoading: "workspaces.members.loading",
+  membersEmpty: "workspaces.members.empty",
+  membersLoadFailed: "workspaces.members.load_failed",
+  rolesLoadFailed: "workspaces.roles.load_failed",
   membersInvite: "workspaces.members.invite",
   membersInviting: "workspaces.members.inviting",
   membersUpdateRole: "workspaces.members.update_role",
@@ -34,6 +47,9 @@ export const WORKSPACES_I18N_KEYS = {
   fieldSlug: "workspaces.settings.field.slug",
   fieldType: "workspaces.settings.field.type",
   save: "workspaces.settings.save",
+  // Why a settings control is switched off (core's `useActionGate`).
+  blockedNotOwner: "workspaces.settings.blocked.not_owner",
+  blockedNameRequired: "workspaces.settings.blocked.name_required",
   saving: "workspaces.settings.saving",
   dangerZoneTitle: "workspaces.settings.danger_zone.title",
   deleteWorkspace: "workspaces.settings.danger_zone.delete",
@@ -102,11 +118,18 @@ export const workspacesI18nBundleEn: I18nDictionary = {
 
   // workspaces-react UI
   "workspaces.error.unknown": "Something went wrong. Please try again.",
+  "workspaces.retry": "Try again",
   "workspaces.list.loading": "Loading workspaces…",
   "workspaces.list.empty": "No workspaces yet.",
+  "workspaces.list.load_failed":
+    "We could not load your workspaces. This is a problem on our side, not a sign that you have none.",
   "workspaces.list.create": "Create workspace",
   "workspaces.list.creating": "Creating…",
   "workspaces.members.loading": "Loading members…",
+  "workspaces.members.empty": "No members yet.",
+  "workspaces.members.load_failed": "We could not load the member list.",
+  "workspaces.roles.load_failed":
+    "We could not load the role list, so the role picker is empty. It is not a workspace without roles.",
   "workspaces.members.invite": "Invite",
   "workspaces.members.inviting": "Inviting…",
   "workspaces.members.update_role": "Change role",
@@ -120,6 +143,9 @@ export const workspacesI18nBundleEn: I18nDictionary = {
   "workspaces.settings.field.slug": "URL slug",
   "workspaces.settings.field.type": "Type",
   "workspaces.settings.save": "Save changes",
+  "workspaces.settings.blocked.not_owner":
+    "Only the workspace owner can change these settings.",
+  "workspaces.settings.blocked.name_required": "Enter a workspace name.",
   "workspaces.settings.saving": "Saving…",
   "workspaces.settings.danger_zone.title": "Danger zone",
   "workspaces.settings.danger_zone.delete": "Delete workspace",

package/src/i18n/ru.ts

@@ -25,11 +25,18 @@ export const workspacesI18nBundleRu: I18nDictionary = {
 
   // workspaces-react UI (hand-written ru mirror of the en copy in keys.ts)
   "workspaces.error.unknown": "Что-то пошло не так. Попробуйте ещё раз.",
+  "workspaces.retry": "Попробовать снова",
   "workspaces.list.loading": "Загрузка рабочих пространств…",
   "workspaces.list.empty": "Пока нет рабочих пространств.",
+  "workspaces.list.load_failed":
+    "Не удалось загрузить ваши рабочие пространства. Это сбой на нашей стороне, а не признак того, что их у вас нет.",
   "workspaces.list.create": "Создать рабочее пространство",
   "workspaces.list.creating": "Создание…",
   "workspaces.members.loading": "Загрузка участников…",
+  "workspaces.members.empty": "Пока нет участников.",
+  "workspaces.members.load_failed": "Не удалось загрузить список участников.",
+  "workspaces.roles.load_failed":
+    "Не удалось загрузить список ролей, поэтому выбор роли пуст. Это не рабочее пространство без ролей.",
   "workspaces.members.invite": "Пригласить",
   "workspaces.members.inviting": "Приглашение…",
   "workspaces.members.update_role": "Изменить роль",
@@ -43,6 +50,9 @@ export const workspacesI18nBundleRu: I18nDictionary = {
   "workspaces.settings.field.slug": "URL-идентификатор",
   "workspaces.settings.field.type": "Тип",
   "workspaces.settings.save": "Сохранить изменения",
+  "workspaces.settings.blocked.not_owner":
+    "Менять эти настройки может только владелец рабочего пространства.",
+  "workspaces.settings.blocked.name_required": "Введите название рабочего пространства.",
   "workspaces.settings.saving": "Сохранение…",
   "workspaces.settings.danger_zone.title": "Опасная зона",
   "workspaces.settings.danger_zone.delete": "Удалить рабочее пространство",

package/src/index.ts

@@ -69,6 +69,8 @@ export {
   useWorkspaces,
   useWorkspace,
   useMembers,
+  useAudit,
+  useCanCreateWorkspace,
   useInvitations,
   useInfiniteInvitations,
   useRoles,
@@ -126,6 +128,9 @@ export type {
   WorkspaceList as WorkspaceListData,
   WorkspaceCreate,
   WorkspaceUpdate,
+  AuditEvent,
+  AuditPage,
+  AuditParams,
   Member as MemberData,
   MemberPage as MemberListData,
   MembersParams,

package/src/model/queries.ts

@@ -4,14 +4,16 @@ import type {
   UseInfiniteQueryResult,
   UseQueryResult,
 } from "@tanstack/react-query";
-import { useActiveSessionReady } from "@stapel/core";
-import type { StapelApiError } from "@stapel/core";
+import { loadStateFromQuery, mapLoad, useActiveSessionReady } from "@stapel/core";
+import type { LoadState, StapelApiError } from "@stapel/core";
 import type {
   InvitationPage,
   InvitationPreview,
   InstanceShape,
   InvitationsParams,
   MemberPage,
+  AuditPage,
+  AuditParams,
   MembersParams,
   RoleInfo,
   Workspace,
@@ -90,6 +92,55 @@ export function useMembers(
   });
 }
 
+/**
+ * One page of a workspace's membership history (GET /{id}/audit,
+ * stapel-workspaces 0.24) — who let this person in, who took them out, when.
+ *
+ * WHY THE PAIR CARRIES THIS AT ALL. Nothing kept a record before: the comm
+ * events this module emits are notifications to other services that nobody
+ * stores, and half the transitions emit nothing. Every product that grew an
+ * admin screen therefore had the same unanswerable question, and the first one
+ * to need it wrote a bespoke fetch through the runtime client — the copy this
+ * hook exists to make unnecessary.
+ *
+ * Gated on `members.view` server-side: every role that may see who is in the
+ * room may see how they got there. Disabled until a `workspaceId` is given
+ * (and the session is ready — see {@link useWorkspace}).
+ *
+ * ANCHOR pagination like {@link useMembers}. `action` narrows to one
+ * transition, `user_id` to one person's history AS THE SUBJECT — a value the
+ * server cannot parse matches nothing rather than being ignored.
+ */
+export function useAudit(
+  workspaceId: string | null,
+  params?: AuditParams
+): UseQueryResult<AuditPage, StapelApiError> {
+  const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
+  const p = params ?? {};
+  return useQuery({
+    queryKey: workspacesQueryKeys.auditPage(workspaceId ?? "", p),
+    queryFn: () => api.listAudit(workspaceId as string, p),
+    enabled: sessionReady && workspaceId !== null && workspaceId !== "",
+  });
+}
+
+/**
+ * MAY THIS CALLER FOUND A WORKSPACE on this instance — the server's answer
+ * (`can_create_workspace`, stapel-workspaces 0.24's `WORKSPACE_CREATE_POLICY`),
+ * not a rule re-derived from the deploy shape.
+ *
+ * Ask this before drawing a "+ New space" control. The same helper answers the
+ * gate on `POST /workspaces`, so a drawn button always opens — a client that
+ * decided for itself would either draw one that 403s or hide one that should
+ * be there. FAILS CLOSED while the list is loading or failed: a hidden action
+ * for a second beats an action that refuses.
+ */
+export function useCanCreateWorkspace(): boolean {
+  const { data } = useWorkspaces();
+  return data?.can_create_workspace ?? false;
+}
+
 /**
  * One page of a workspace's invitations (GET /{id}/invitations, #109) — the
  * admin's "who has not accepted yet" table. Disabled until a `workspaceId` is
@@ -223,15 +274,21 @@ export function useInvitationPreview(
 /** What {@link useCapabilities} returns: the caller's granted capability
  * strings in one workspace plus the wildcard-aware `can()` check. */
 export interface CapabilitiesResult {
-  /** Verbatim registry strings of the caller's role (wildcards included);
-   * empty while loading or when the caller is not a member. */
-  readonly capabilities: readonly string[];
+  /**
+   * The capability read, as a state. `ready` with the verbatim registry
+   * strings of the caller's role (wildcards included; `[]` for a non-member,
+   * and for a backend older than 0.6.0 which does not send the field at all).
+   *
+   * A state and not an array, because "you may not do this" and "we could not
+   * find out whether you may" both end in a hidden button, and only one of
+   * them should end in silence. `can()` stays deny-by-default in both — that
+   * part is a security property and does not change — but a screen that wants
+   * to SAY why can now tell them apart.
+   */
+  readonly state: LoadState<readonly string[]>;
   /** Wildcard-aware check (`*` / `prefix.*` — the backend matcher, ported).
    * UI convenience only: the backend re-checks on every operation. */
   can(capability: string): boolean;
-  readonly isLoading: boolean;
-  readonly isError: boolean;
-  readonly error: StapelApiError | null;
 }
 
 /**
@@ -243,13 +300,17 @@ export interface CapabilitiesResult {
  */
 export function useCapabilities(workspaceId: string | null): CapabilitiesResult {
   const query = useWorkspace(workspaceId);
-  const capabilities = query.data?.my_capabilities ?? [];
+  // `my_capabilities` is additive since stapel-workspaces 0.6.0, so a
+  // SUCCESSFUL read against an older backend legitimately carries none. That
+  // is an empty grant, not a failed load, and the two must not merge.
+  const state = mapLoad(
+    loadStateFromQuery(query),
+    (workspace) => workspace.my_capabilities ?? []
+  );
   return {
-    capabilities,
-    can: (capability) => hasCapability(capabilities, capability),
-    isLoading: query.isLoading,
-    isError: query.isError,
-    error: query.error ?? null,
+    state,
+    can: (capability) =>
+      state.status === "ready" && hasCapability(state.data, capability),
   };
 }
 
@@ -299,7 +360,7 @@ export function useCapabilityGate(
   workspaceId: string | null,
   capability: string
 ): CapabilityGate {
-  const { can, isLoading } = useCapabilities(workspaceId);
+  const { can, state } = useCapabilities(workspaceId);
   const level = capabilityLevel(capability);
   return {
     capability,
@@ -307,6 +368,6 @@ export function useCapabilityGate(
     level,
     requiresStepUp: level === "high",
     stepUpScope: level === "high" ? SENSITIVE_SCOPE : null,
-    isLoading,
+    isLoading: state.status === "loading",
   };
 }

package/src/model/queryKeys.ts

@@ -1,4 +1,8 @@
-import type { InvitationsParams, MembersParams } from "../api/types.js";
+import type {
+  AuditParams,
+  InvitationsParams,
+  MembersParams,
+} from "../api/types.js";
 
 /**
  * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
@@ -19,6 +23,11 @@ export const workspacesQueryKeys: {
     workspaceId: string,
     params: MembersParams
   ): readonly ["workspaces", "members", string, MembersParams];
+  audit(workspaceId: string): readonly ["workspaces", "audit", string];
+  auditPage(
+    workspaceId: string,
+    params: AuditParams
+  ): readonly ["workspaces", "audit", string, AuditParams];
   invitations(workspaceId: string): readonly ["workspaces", "invitations", string];
   invitationsPage(
     workspaceId: string,
@@ -46,6 +55,12 @@ export const workspacesQueryKeys: {
   // The bare 3-tuple is a valid prefix of membersPage's 4-tuple, so
   // invalidating `members(workspaceId)` (mutations.ts) drops every page.
   members: (workspaceId) => [ROOT, "members", workspaceId],
+  /** The workspace's membership history (stapel-workspaces 0.24). Its own
+   * root, not a slice of `members`: history is append-only and a member
+   * mutation invalidates the ROSTER — the history it also appended to is
+   * invalidated deliberately, by naming this key, not as a side effect. */
+  audit: (workspaceId) => [ROOT, "audit", workspaceId],
+  auditPage: (workspaceId, params) => [ROOT, "audit", workspaceId, params],
   // EVERY workspace's roster, not one. Not a read key — nothing fetches it —
   // but the invalidation scope of a write that moves a name the whole fleet
   // shares: `MemberResponse.display_name` is a live lookup in