@stapel/workspaces-react 0.13.0 → 0.14.0

package/src/default/MembersManager.tsx

@@ -15,9 +15,9 @@
  */
 import { useState } from "react";
 import type { ReactElement } from "react";
-import { Button, Card, Input, Modal, Popconfirm, Select, Table, Typography } from "antd";
+import { Button, Card, Empty, Input, Modal, Popconfirm, Select, Table, Typography } from "antd";
 import type { TableProps } from "antd";
-import { useErrorDisplay, useT } from "@stapel/core";
+import { loadedRowsOrEmpty, matchList, useErrorDisplay, useT } from "@stapel/core";
 import { Members } from "../headless/Members.js";
 import { RoleSelect } from "../headless/RoleSelect.js";
 import type { RoleSelectBag } from "../headless/RoleSelect.js";
@@ -54,9 +54,15 @@ export function MembersManager(props: MembersManagerProps): ReactElement {
     <RoleSelect>
       {(rolesBag: RoleSelectBag) => (
         <Members workspaceId={props.workspaceId}>
-          {({ members, isLoading, isError, error, invite, isInviting, updateRole, remove }) => {
+          {({ state, writeError, invite, isInviting, updateRole, remove, refetch }) => {
             const { labelFor } = rolesBag;
-            const roleOptions = rolesBag.roles.map((r) => ({
+            // The registry read is a SEPARATE load from the roster's, and it
+            // gets its own sentence below rather than silently producing an
+            // empty picker — a role menu with nothing in it and a role menu
+            // that could not be fetched look identical to a person.
+            const rolesFailed = rolesBag.state.status === "failed";
+            const rolesLoading = rolesBag.state.status === "loading";
+            const roleOptions = loadedRowsOrEmpty(rolesBag.state).map((r) => ({
               value: r.role,
               label: labelFor(r.role),
             }));
@@ -95,7 +101,7 @@ export function MembersManager(props: MembersManagerProps): ReactElement {
                     <Select<string>
                       value={member.role}
                       style={{ width: 160 }}
-                      loading={rolesBag.isLoading}
+                      loading={rolesLoading}
                       onChange={(next) => updateRole({ userId: member.user_id, role: next })}
                       // A member's CURRENT role may be missing from the
                       // registry options (a deployment removed an overlay
@@ -148,17 +154,64 @@ export function MembersManager(props: MembersManagerProps): ReactElement {
                   )}
                 </div>
 
-                {isError && <ErrorAlert error={errorDisplay(error)} style={{ marginTop: 12 }} />}
+                {/* A write that failed — the roster read has its own arm below. */}
+                {writeError !== null && (
+                  <ErrorAlert error={errorDisplay(writeError)} style={{ marginTop: 12 }} />
+                )}
+                {rolesFailed && (
+                  <ErrorAlert
+                    testId="members-roles-error"
+                    error={{ message: t(WORKSPACES_I18N_KEYS.rolesLoadFailed), detail: undefined }}
+                    style={{ marginTop: 12 }}
+                  />
+                )}
 
-                <Table<Member>
-                  style={{ marginTop: 16 }}
-                  size="small"
-                  loading={isLoading}
-                  rowKey={(member) => member.id}
-                  dataSource={members as Member[]}
-                  columns={columns}
-                  pagination={false}
-                />
+                {matchList(state, {
+                  loading: () => (
+                    <Table<Member>
+                      style={{ marginTop: 16 }}
+                      size="small"
+                      loading
+                      rowKey={(member) => member.id}
+                      dataSource={[]}
+                      columns={columns}
+                      pagination={false}
+                    />
+                  ),
+                  // An antd Table with no rows renders "No data". On a failed
+                  // read that is the empty-state lie with a built-in
+                  // illustration, so the table does not get rendered at all.
+                  failed: (error) => (
+                    <div style={{ marginTop: 16 }} data-testid="members-list-error">
+                      <ErrorAlert error={errorDisplay(error)} />
+                      <Button
+                        style={{ marginTop: 12 }}
+                        onClick={refetch}
+                        data-analytics="none"
+                        data-analytics-reason="local-ui-refetch-after-a-stated-read-failure"
+                      >
+                        {t(WORKSPACES_I18N_KEYS.retry)}
+                      </Button>
+                    </div>
+                  ),
+                  empty: () => (
+                    <Empty
+                      style={{ marginTop: 16 }}
+                      data-testid="members-list-empty"
+                      description={t(WORKSPACES_I18N_KEYS.membersEmpty)}
+                    />
+                  ),
+                  ready: (members) => (
+                    <Table<Member>
+                      style={{ marginTop: 16 }}
+                      size="small"
+                      rowKey={(member) => member.id}
+                      dataSource={[...members]}
+                      columns={columns}
+                      pagination={false}
+                    />
+                  ),
+                })}
 
                 <Modal
                   title={t(WORKSPACES_I18N_KEYS.membersInviteDialogTitle)}
@@ -182,7 +235,7 @@ export function MembersManager(props: MembersManagerProps): ReactElement {
                         value={inviteRole}
                         onChange={setInviteRole}
                         style={{ width: "100%" }}
-                        loading={rolesBag.isLoading}
+                        loading={rolesLoading}
                         options={inviteRoleOptions}
                       />
                     </div>

package/src/default/WorkspaceSettings.tsx

@@ -9,7 +9,14 @@
 import { useEffect, useState } from "react";
 import type { ReactElement } from "react";
 import { Badge, Button, Card, Input, Popconfirm, Spin, Typography } from "antd";
-import { useErrorDisplay, useT } from "@stapel/core";
+import {
+  actionAvailable,
+  actionBlocked,
+  firstBlock,
+  useActionGate,
+  useErrorDisplay,
+  useT,
+} from "@stapel/core";
 import { useWorkspace } from "../model/queries.js";
 import { useUpdateWorkspace, useDeleteWorkspace } from "../model/mutations.js";
 import { WORKSPACES_I18N_KEYS } from "../i18n/keys.js";
@@ -35,6 +42,17 @@ export function WorkspaceSettings(props: WorkspaceSettingsProps): ReactElement {
   const workspace = query.data;
   const [name, setName] = useState("");
 
+  // Two unrelated situations used to share one `disabled={!isOwner ||
+  // !name.trim()}` bit, and a person facing either of them saw the same dead
+  // button. `firstBlock` keeps them two, in the order you would explain them.
+  const isOwner = workspace?.my_role === "owner";
+  const saveGate = useActionGate(
+    firstBlock(
+      isOwner ? actionAvailable() : actionBlocked(WORKSPACES_I18N_KEYS.blockedNotOwner),
+      name.trim() ? actionAvailable() : actionBlocked(WORKSPACES_I18N_KEYS.blockedNameRequired)
+    )
+  );
+
   useEffect(() => {
     if (workspace) setName(workspace.name);
   }, [workspace]);
@@ -66,8 +84,6 @@ export function WorkspaceSettings(props: WorkspaceSettingsProps): ReactElement {
     );
   }
 
-  const isOwner = workspace.my_role === "owner";
-
   return (
     <div data-testid="workspace-settings" style={{ display: "grid", gap: 16 }}>
       <Card>
@@ -79,7 +95,18 @@ export function WorkspaceSettings(props: WorkspaceSettingsProps): ReactElement {
         <div style={{ display: "grid", gap: 12, maxWidth: 480, marginTop: 16 }}>
           <div>
             <Typography.Text>{t(WORKSPACES_I18N_KEYS.fieldName)}</Typography.Text>
-            <Input value={name} onChange={(e) => setName(e.target.value)} disabled={!isOwner} />
+            <Input
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              disabled={!isOwner}
+            />
+            {!isOwner && (
+              <div>
+                <Typography.Text type="secondary" data-testid="workspace-name-blocked">
+                  {t(WORKSPACES_I18N_KEYS.blockedNotOwner)}
+                </Typography.Text>
+              </div>
+            )}
           </div>
           <div>
             <Typography.Text>{t(WORKSPACES_I18N_KEYS.fieldSlug)}</Typography.Text>
@@ -101,13 +128,22 @@ export function WorkspaceSettings(props: WorkspaceSettingsProps): ReactElement {
           type="primary"
           style={{ marginTop: 16 }}
           loading={updateMutation.isPending}
-          disabled={!isOwner || !name.trim()}
+          disabled={saveGate.disabled}
           onClick={handleSave}
           data-analytics="none"
           data-analytics-reason="business action — host app wraps with its own tracked(); pairs carry no @stapel/analytics runtime dependency by architecture"
         >
           {updateMutation.isPending ? t(WORKSPACES_I18N_KEYS.saving) : t(WORKSPACES_I18N_KEYS.save)}
         </Button>
+        {/* Beside the control, as TEXT: a disabled button receives no pointer
+            events, so a tooltip on it is a reason nobody can read. */}
+        {saveGate.reason !== undefined && (
+          <div style={{ marginTop: 8 }}>
+            <Typography.Text type="secondary" data-testid="workspace-save-blocked">
+              {saveGate.reason}
+            </Typography.Text>
+          </div>
+        )}
       </Card>
 
       {isOwner && (

package/src/headless/Can.tsx

@@ -8,6 +8,14 @@ export interface CanBag {
   /** The underlying read is still in flight (verdict is `false` meanwhile —
    * deny-by-default; render a skeleton off this if flicker matters). */
   readonly isLoading: boolean;
+  /**
+   * The read FAILED, so `allowed: false` means "we could not find out",
+   * not "you may not". Deny-by-default still holds — a capability check that
+   * opened up on an outage would be a security hole — but a skin with
+   * somewhere to put a sentence should say which of the two it is rather than
+   * silently withholding the control.
+   */
+  readonly isUnknown: boolean;
 }
 
 /**
@@ -43,7 +51,11 @@ export function Can(props: {
   const caps = useCapabilities(props.workspaceId);
   const allowed = caps.can(props.capability);
   if (typeof props.children === "function") {
-    return props.children({ allowed, isLoading: caps.isLoading });
+    return props.children({
+      allowed,
+      isLoading: caps.state.status === "loading",
+      isUnknown: caps.state.status === "failed",
+    });
   }
   return allowed ? props.children : (props.fallback ?? null);
 }

package/src/headless/Members.tsx

@@ -1,5 +1,6 @@
 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 { Member, MemberInvite } from "../api/types.js";
 import { useMembers } from "../model/queries.js";
 import {
@@ -12,18 +13,19 @@ import type { MemberRoleChange } from "../model/mutations.js";
 /** Render-prop bag for {@link Members}. */
 export interface MembersBag {
   /**
-   * The workspace's members once loaded (empty before load). This is one page
-   * (default 100) — the roster's own {@link Member.email}/`search` narrows
-   * further; a full pager is out of scope for this renderless view (bring
-   * your own via `useMembers`' `params` for anchor pagination).
+   * The roster read, as a state a skin cannot flatten — render it with core's
+   * `matchList`. This is one page (default 100); a full pager is out of scope
+   * for this renderless view (bring your own via `useMembers`' `params` for
+   * anchor pagination).
+   *
+   * Separate from {@link writeError} on purpose: "the roster could not be
+   * loaded" and "your invite was rejected" are different sentences, and the
+   * old merged `isError` could only produce one of them.
    */
-  readonly members: readonly Member[];
-  /** The initial member-list load is in flight. */
-  readonly isLoading: boolean;
-  /** The read, an invite, a role change, or a removal failed. */
-  readonly isError: boolean;
-  /** The error, when `isError` (a localizable `StapelApiError`), else null. */
-  readonly error: StapelApiError | null;
+  readonly state: LoadState<readonly Member[]>;
+  /** An invite, a role change, or a removal failed. Never the read — that is
+   * {@link state}. */
+  readonly writeError: StapelApiError | null;
   /** Invite one or more emails at a role. */
   invite(body: MemberInvite): void;
   /** An invite call is in flight. */
@@ -49,7 +51,7 @@ export interface MembersBag {
  *
  * ```tsx
  * <Members workspaceId={id}>
- *   {({ members, invite, updateRole, remove }) => ( ... )}
+ *   {({ state, invite, updateRole, remove }) => ( ... )}
  * </Members>
  * ```
  */
@@ -62,19 +64,9 @@ export function Members(props: {
   const roleMutation = useUpdateMemberRole(props.workspaceId);
   const removeMutation = useRemoveMember(props.workspaceId);
   return props.children({
-    members: query.data?.items ?? [],
-    isLoading: query.isLoading,
-    isError:
-      query.isError ||
-      inviteMutation.isError ||
-      roleMutation.isError ||
-      removeMutation.isError,
-    error:
-      query.error ??
-      inviteMutation.error ??
-      roleMutation.error ??
-      removeMutation.error ??
-      null,
+    state: mapLoad(loadStateFromQuery(query), (page) => page.items),
+    writeError:
+      inviteMutation.error ?? roleMutation.error ?? removeMutation.error ?? null,
     invite: (body) => {
       inviteMutation.mutate(body);
     },

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/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/model/queries.ts

@@ -4,8 +4,8 @@ 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,
@@ -223,15 +223,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 +249,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 +309,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 +317,6 @@ export function useCapabilityGate(
     level,
     requiresStepUp: level === "high",
     stepUpScope: level === "high" ? SENSITIVE_SCOPE : null,
-    isLoading,
+    isLoading: state.status === "loading",
   };
 }