@lepsto/sdk-app 84.0.0

package/docs/recipes/access.md

@@ -0,0 +1,781 @@
+# Recipe: reflecting the caller's access in the UI
+
+Some of your users cannot do some of the things your App offers. This recipe
+shows how to grey out those controls and how to render the refusal you will
+still occasionally get — without ever making your App the authority on who is
+allowed to do what.
+
+**The one rule everything here rests on:** `can()` is a *prediction*, the server
+is the authority. See APP-012 in `../rules.md`.
+
+---
+
+## What `app.access` is
+
+Every client from `createLesslyApp` carries an `access` object:
+
+```ts
+import { createLesslyApp } from '@lessly/sdk-app';
+
+const app = createLesslyApp({ baseUrl: '/api', productId });
+
+await app.access.load();          // one GET; cached; concurrent calls share it
+app.access.role;                  // 'owner' | 'admin' | 'member' | a custom role name
+app.access.state;                 // 'idle' | 'loading' | 'ready' | 'error'
+app.access.can('mail_domain_create');   // boolean, synchronous
+app.access.invalidate();          // drop the cache; the next load() refetches
+app.access.subscribe(() => {});   // fires on every state change
+```
+
+`load()` fetches the caller's own membership of the active product — their role
+and their allow/deny grant patterns — and `can()` answers from that snapshot
+using the *same matcher the gateway uses to decide*. That is the only reason a
+client-side prediction is worth anything.
+
+`can()` is **false whenever the snapshot is not ready**: before `load()`, while
+it is in flight, after a failure, and after `invalidate()`. So a control wired
+to it starts disabled and enables itself — never the reverse. A control that
+starts enabled and greys out a moment later is worse than one that never greyed
+out at all.
+
+`can()` being false is not by itself a reason to *tell the user their role is
+the problem*, though — a failed `/me` is not a denial. See the state table in
+§2 for what each `state` means for a control.
+
+The snapshot lives **in the client instance** until `invalidate()` or until the
+client itself is recreated. There is no TTL and no background refresh: a client
+made once holds the role it loaded once, for as long as it lives.
+
+That matters because a module-level singleton `createLesslyApp` client survives
+SPA navigation and bfcache back/forward. A "reload" that does not remount the
+remote — a router push, a browser Back into a restored page — keeps the old
+snapshot, and the UI can lag the real role by minutes while `GET
+products/:id/me` would answer correctly if anyone asked it. After a role change,
+call `app.access.invalidate()` and then `load()` again (or do a full page
+reload); do not wait for the snapshot to expire, because it never does.
+
+Before you measure staleness, compare the role the App's own `/me` request
+returned — read it in the Network tab — with what the API says now. Never assume
+the role from memory: the two disagree exactly in the case you are debugging.
+And it is never the HTTP cache alone: the server sends no `Cache-Control` for
+`/me` today, so the browser only revalidates via `ETag`. Staleness you see is
+the in-memory snapshot.
+
+You can pass either a tool id or a generated method, which carries its own
+identity:
+
+```ts
+app.access.can('mail_domain_create');   // a tool id
+app.access.can(app.mail.domain.create); // the method itself — no id to keep in sync
+```
+
+Prefer the second form. The accessor path is a lossy view of the tool id (a
+hyphenated resource joins several id segments), so a hand-written string can
+drift from the method it is meant to describe; the method cannot.
+
+---
+
+## 1. Load once at app mount
+
+```tsx
+// src/App.tsx
+import { useEffect } from 'react';
+import { createLesslyApp } from '@lessly/sdk-app';
+import { TooltipProvider } from '@lessly/ui';
+
+export default function App({ productId }: { productId: string }) {
+  const app = useMemo(() => createLesslyApp({ baseUrl: '/api', productId }), [productId]);
+
+  useEffect(() => {
+    // Fire and forget: a failure is reflected in app.access.state, and can() stays false
+    // until the snapshot is ready.
+    void app.access.load().catch(() => {});
+  }, [app]);
+
+  // One TooltipProvider per App canvas — see §2. Never one per control, and never
+  // borrowed from the shell: your standalone build and your tests render outside it.
+  return (
+    <TooltipProvider>
+      <Routes app={app} />
+    </TooltipProvider>
+  );
+}
+```
+
+You do not have to do this. `useAccess`/`useCan` load on mount themselves, and
+`load()` is de-duplicated inside the client — ten components mounting at once
+produce **one** request. Loading at the root is just the cheapest way to have
+the snapshot ready before the first screen paints.
+
+Call `app.access.invalidate()` after anything that can change the caller's own
+grants (they accepted an invitation, an admin changed their role in a settings
+screen you own). Nothing else invalidates it: the snapshot is deliberately not
+refetched on a timer.
+
+---
+
+## 2. `useCan` on primary actions — disable, don't hide
+
+```tsx
+import { accessReason } from '@lessly/sdk-app';
+import { useAccess, useCan } from '@lessly/sdk-app/react';
+import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@lessly/ui';
+
+function AddDomainButton({ app, onClick }: { app: App; onClick: () => void }) {
+  const { state } = useAccess(app);
+  const canCreate = useCan(app, app.mail.domain.create);
+
+  // 'error' is NOT a denial: nothing is known about the role, so make no prediction.
+  const disabled = state === 'ready' ? !canCreate : state !== 'error';
+  // The reason names the level AND the operation key, both read off the method —
+  // never hand-typed per button, and never the caller's role.
+  const reason =
+    state === 'ready' && !canCreate
+      ? accessReason(app.mail.domain.create)
+      : undefined;
+
+  const button = (
+    <Button disabled={disabled} onClick={onClick}>
+      Add domain
+    </Button>
+  );
+
+  if (reason === undefined) return button;
+
+  return (
+    <Tooltip>
+      {/* The trigger is the WRAPPER, not the Button: the base buttonVariants set
+          disabled:pointer-events-none, so a disabled control fires no hover and a
+          tooltip mounted on it never opens. */}
+      <TooltipTrigger asChild>
+        <span tabIndex={0}>{button}</span>
+      </TooltipTrigger>
+      <TooltipContent>{reason}</TooltipContent>
+    </Tooltip>
+  );
+}
+```
+
+### The reason goes on a wrapper, never on `title=`
+
+A `title` on a disabled Button is unreachable twice over: `disabled:pointer-events-none`
+swallows the hover the browser needs to show it, and a native tooltip is unreachable
+by keyboard and by touch even on an enabled control. That class sits in the **base**
+`buttonVariants`, not in an icon-only branch — so the wrapper pattern applies to
+*every* Button, not just the icon-only shape. The wrapping trigger carries
+`tabIndex={0}` for the same reason: a keyboard user has to be able to reach the hint.
+This mirrors what `@lessly/ui` documents above `ButtonIconOnlyProps` in `button.tsx`
+(`Button --disabled-with-tooltip` shows both halves).
+
+Controls that take no `title` at all — the kit's `Switch`, for one — have no other
+option: the wrapper is the only place the reason can live.
+
+**The trigger must sit outside every `pointer-events-none`, including your own.**
+The kit's `disabled:pointer-events-none` is the common case, but the mechanism is
+not the kit's: a list row, a chip or an overlay in your own App that you set
+`pointer-events-none` on swallows hover identically, and a trigger nested inside
+it is just as silent — in your code this time. Walk outwards from the control to
+the first ancestor that still receives pointer events, and put the trigger there.
+
+### One reason string, built from the method
+
+Every App says the same sentence, and both of its values come off the generated
+method:
+
+```tsx
+import { accessReason } from '@lessly/sdk-app';
+
+accessReason(app.mail.domain.create);
+// "Requires level:admin (mail_domain_create). Ask an admin of this product."
+```
+
+Use it in every example below; nothing in an App should assemble this text by
+hand. It never throws and never renders the word `undefined`: an object with a
+key but no usable level degrades to the key-only sentence, and an input with no
+usable key at all falls back to `"Not available for your role. Ask an admin of
+this product."` (plus one `console.warn` outside production, because that input
+is a caller bug).
+
+It takes **one** operation. Choosing which operation to explain — the first one
+`can()` denied, out of the several a button performs — is the caller's job, and
+it stays the caller's job: the helper accepts no array, because the rule for
+picking is not the same in the two shapes below and a helper that guessed would
+be wrong in one of them.
+
+Its signature is `Operation | string`, and the two arms are not equals. Passing a
+method is the norm. The string arm is a **degradation**, there for the controls
+that have no generated method to point at — a runtime probe, an operation no
+method covers — and it says less because less is known:
+
+```tsx
+accessReason('some_runtime_probe');
+// "Requires access to some_runtime_probe. Ask an admin of this product."
+```
+
+It drops the level rather than inventing one: with only a key there is nothing to
+read a level from, and `level:undefined` in front of a user is worse than saying
+less. It is not permission to pass strings where a method exists — the accessor
+path is a lossy view of the key, so a hand-written string can drift from the
+operation it names, and only the method's arm gives an admin both halves of what
+they grant on. An App whose every gate receives an `Operation` never writes the
+string form at all; that is the normal shape of an App, not a gap in it.
+
+`can()` is cautious with a bare string in the same way. It resolves the level
+from the catalog when the key is one the SDK knows, but a key with **no** catalog
+entry can only be matched by key pattern — no level grant reaches it, which is
+exactly what the gateway does with an uncatalogued key.
+
+> **On an older SDK.** `accessReason` ships from `@lessly/sdk-app`. On a version
+> before it landed, define it locally with exactly this signature and body, then
+> replace it with the import when you upgrade:
+>
+> ```ts
+> import type { Operation } from '@lessly/sdk-app';
+>
+> const ok = (v: unknown): v is string => typeof v === 'string' && v.trim() !== '';
+>
+> export const accessReason = (op: Operation | string): string => {
+>   if (ok(op)) return `Requires access to ${op}. Ask an admin of this product.`;
+>   // A generated method is a CALLABLE carrying operationKey/level, so not just 'object'.
+>   if (op !== null && (typeof op === 'object' || typeof op === 'function')) {
+>     const { operationKey, level } = op as { operationKey?: unknown; level?: unknown };
+>     if (ok(operationKey)) {
+>       return ok(level) && ['read', 'write', 'admin'].includes(level)
+>         ? `Requires level:${level} (${operationKey}). Ask an admin of this product.`
+>         : `Requires access to ${operationKey}. Ask an admin of this product.`;
+>     }
+>   }
+>   return 'Not available for your role. Ask an admin of this product.';
+> };
+> ```
+>
+> It never throws — a render helper that crashes takes the whole screen with it —
+> and never renders `level:undefined`.
+
+**Why both values.** The reason says what an admin has to *grant*, not what the
+caller happens to be — a role name gives them nothing to act on, and "your role
+cannot do this" sends the user into a conversation with no next step. But a level
+alone is not enough either: seventeen controls on a screen can all read
+`level:write` and be seventeen different grants. An admin grants both **by level
+and by exact operation key**, so the user has to be able to pass on both. The key
+is what makes the sentence actionable; the level is what makes it
+comprehensible.
+
+**Both come only from the method.** `op.level` and `op.operationKey` — every
+generated method satisfies `interface Operation { operationKey, level }`. No
+lookup table in your App, no literal in the JSX, and above all no rule of thumb
+about which verbs are which level. There is no such rule: `analytics_dashboard_delete`
+and `analytics_insight_delete` are `write`, `mail_domain_create` is `admin`, and
+the whole `users` namespace has exactly six `admin` operations. Only the catalog
+knows, the method carries what the catalog said, and a reason built from the
+method cannot drift the day an operation is re-levelled. The accessor path is a
+lossy view of the key, so never rebuild `operationKey` from it either — read it
+off the method.
+
+### Reading a level without a method
+
+Sometimes there is no method to read `op.level` from: an App test double that has
+to answer `can()` for a key, a runtime probe over keys it was handed. The answer
+is still not a literal and still not a table in the App — `@lessly/sdk-app`
+exports the catalog's own level map:
+
+```ts
+import { operations, accessReason } from '@lessly/sdk-app';
+
+operations['mail_domain_create'];   // 'admin'
+operations['analytics_insight_delete'];  // 'write'
+```
+
+`operations` is `Readonly<Record<string, ToolLevel>>`, keyed by operation key. It
+is regenerated at publish time from the live catalog, so it re-levels with the
+platform exactly as the generated methods do — which is the whole reason it may
+be read where a hand-written table may not (APP-012).
+
+A key the map does not carry answers `undefined`, and that is the case
+`accessReason`'s string form already covers: pass the bare key and get
+*"Requires access to `<key>`. Ask an admin of this product."* — no level invented,
+no `level:undefined` in front of a user. Where you do hold a method, keep reading
+`op.level` off it: the map is for the keys no method covers, not a second way to
+do what the method already does.
+
+### Your App mounts its own `TooltipProvider`
+
+Mount **one `TooltipProvider` per App canvas** — at the root of your remote, as in
+§1 — and never one per control. Do not rely on the shell for it: `Tooltip.Root`
+*throws* without a provider above it, so a remote that inherits one only by luck
+does not lose its hint, it crashes — and your standalone build, your dev entry and
+your tests all render outside the shell entirely.
+
+### What each access state means for a control
+
+| `state` | Control | Reason shown |
+| --- | --- | --- |
+| `idle` / `loading` | disabled | none |
+| `ready` | disabled iff `can()` is false | only when `can()` is false |
+| `error` | **enabled** | none — no prediction |
+
+`idle`/`loading` start disabled and enable themselves — a control that starts
+enabled and greys out a moment later is worse than one that never greyed out.
+But it claims **no reason** while the snapshot is still in flight: nothing is
+known yet about which level is missing, so there is nothing to say.
+
+`error` (the `/me` call failed: a 500, a dropped connection, an unparsable product
+id) is the case worth getting right: **make no prediction**. Leave the control
+enabled, name no missing level, let the gateway decide, and render the refusal
+neutrally through `isAccessDenied` — disabling on error makes your client the
+authority and tells the user a level is missing when nothing at all is known
+about their access.
+
+`can()` itself is unchanged by any of this: it is `false` unless the state is
+`ready`. The `error` branch is a decision your *control* makes, not something
+`can()` reports.
+
+**Disable, with a hint. Do not hide.** A user who cannot see the button cannot
+tell their admin which permission they are missing — they file a "the app is
+broken" ticket instead, and the admin who could have fixed it in ten seconds
+never hears about it. The greyed-out control with a one-line reason *is* the
+support channel.
+
+`useAccess` gives you the same information plus the role, for the cases where
+one flag is not enough:
+
+```tsx
+const { state, role, reload } = useAccess(app);
+
+if (state === 'loading') return <Spinner />;
+if (state === 'error') return <p>Could not load your permissions. <button onClick={reload}>Retry</button></p>;
+```
+
+React is an **optional peer** of this package: `@lessly/sdk-app/react` is only
+loaded if you import it, and installing the SDK does not pull React in.
+
+### Actions without a button
+
+A write does not stop being a write because nothing on screen says "Save". Drag to
+reorder, an inline-editable cell, a field that autosaves on blur — each is a
+gated operation, and each is gated the **same way** a button is: put the control
+into its inactive state the native way for that control, then hang the reason on
+a keyboard-reachable `Tooltip` wrapper exactly as above.
+
+| Control | Inactive state |
+| --- | --- |
+| Drag handle / sortable row | `draggable={false}` (and drop the drag listeners) |
+| Inline-editable field | `readOnly` |
+| Autosave-on-blur input | `readOnly` |
+| Switch / checkbox | `disabled` |
+
+```tsx
+function ReorderableRow({ app, row }: { app: App; row: Row }) {
+  const { state } = useAccess(app);
+  const canReorder = useCan(app, app.mail.domain.update);
+  const denied = state === 'ready' && !canReorder;
+
+  const item = (
+    <li draggable={!denied} onDragStart={denied ? undefined : startDrag}>
+      {row.name}
+    </li>
+  );
+
+  if (!denied) return item;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span tabIndex={0}>{item}</span>
+      </TooltipTrigger>
+      <TooltipContent>
+        {accessReason(app.mail.domain.update)}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+```
+
+**Gate the operation, not the gesture.** A write is often reachable by more than
+one path — a row that reorders by mouse drag *and* by arrow keys, a control that
+fires on click *and* on Enter, an action with a button *and* a hotkey. The gate
+has to silence all of them at once. Gating the drag and leaving the arrow keys
+live is not a cosmetic miss: it is a hole, and it is a hole that only keyboard
+users fall into. Derive the flag once per operation and let every path read it,
+rather than attaching a check to each handler. Acceptance under a viewer checks
+the alternative path too, not just the obvious one.
+
+**Enter inside a form field is one of those paths.** A form with a single text
+input submits on Enter whether or not you wired anything to it — that is implicit
+submission, and a disabled submit button does not reliably stop it. Gate the
+`onSubmit` handler itself, or make the fields `readOnly`; a greyed-out button
+beside a live Enter key is the same keyboard-only hole in a different costume.
+
+```tsx
+<form
+  onSubmit={(event) => {
+    event.preventDefault();
+    if (denied) return;   // the button being disabled is NOT enough
+    save();
+  }}
+>
+```
+
+"Don't gate it, let the gateway refuse" is allowed for exactly one case: the
+element physically has no wrapper that can be made focusable. That is rare, and
+it is not a judgement call you make silently — write it into your App's spec as a
+named exception with the reason. An ungated write that nobody wrote down is
+indistinguishable from one nobody thought about.
+
+### One reason for a surface-wide gate
+
+Where a gate disables a *capability across a whole surface* — dragging any node on
+a canvas, a bulk action over a list or a grid — the reason goes on the control
+that **owns** the capability: the toggle, the toolbar button, the surface header.
+Not on every affected element. Thirty identical focusable wrappers are thirty
+extra tab stops and one sentence repeated thirty times; that is noise, not thirty
+explanations. Keyboard reachability (below) is satisfied on the owning control,
+and the elements themselves just go inert — `draggable={false}`, `readOnly`,
+`disabled` — with no wrapper of their own.
+
+Some surfaces have no such control. A calendar's Month/Week toggle owns the
+*view*, not the move; a board's filter bar owns the filter, not the drop. Do not
+hang the reason on it: the reason names the operation actually gated, and
+`accessReason(app.content.publications.reschedule)` under a control that switches
+weeks explains a gate that control does not hold. Where nothing owns the
+capability, the reason goes on the **surface itself, as one `CardNote`** — the
+same shape as a deferred-save form:
+
+```tsx
+<Card title="Schedule">
+  <Calendar events={events} draggable={false} />
+  {denied && <CardNote>{accessReason(app.content.publications.reschedule)}</CardNote>}
+</Card>
+```
+
+One line for the surface, elements inert, no tooltip anywhere on the grid.
+
+### Buttons that touch more than one operation
+
+Two shapes, and they gate differently. Get this wrong and you either grey out a
+working button or leave a broken one live.
+
+**A button that performs several operations per click** — "Deploy" that creates,
+uploads and promotes — is disabled if **any** of them is denied, and names the
+level and key of the one that blocked it, not those of the headline operation. Call
+`useAccess` once and use the synchronous `access.can()` for each; `useCan` is a
+hook and cannot be called in a loop.
+
+```tsx
+const OPS = [app.mail.domain.create, app.mail.domain.verify] as const;
+
+function AddAndVerifyButton({ app, onClick }: { app: App; onClick: () => void }) {
+  const { state, access } = useAccess(app);
+  const blocking = state === 'ready' ? OPS.find((op) => !access.can(op)) : undefined;
+
+  const disabled = state === 'ready' ? blocking !== undefined : state !== 'error';
+  const reason = blocking
+    ? accessReason(blocking)
+    : undefined;
+
+  // …same wrapper as above when `reason` is set.
+}
+```
+
+**A dispatcher button** — one operation per click, picked by a mode or a switch
+beside it: *Import* over `users | waitlist`, *Save* that creates or updates
+depending on whether the record exists — is gated by the operation it is
+**actually about to call**, and its reason names *that* operation's level and key. Not
+the union: a caller who may import users but not the waitlist keeps a working
+Import button, and it greys out when they flip the switch.
+
+```tsx
+const op = mode === 'users' ? app.users.users.import : app.users.waitlist.import;
+
+const { state, access } = useAccess(app);
+const denied = state === 'ready' && !access.can(op);
+const reason = denied
+  ? accessReason(op)
+  : undefined;
+```
+
+Both shapes hand the method to `accessReason`, so neither needs to know which
+operation it ended up gating on.
+
+### Controls that stage a change
+
+A control that **stages** a change — it writes nothing itself; the write is sent
+later, by a Save or an Apply — is gated on the operation that staged change will
+eventually send. Two failure modes, and both are common:
+
+- **Gated on nothing.** A Viewer rearranges, fills in and stages happily, and
+  meets the refusal at Save — somewhere else on the screen, after the work.
+- **Gated twice in a row.** If the entry point that reaches the staging control
+  is already gated on that same operation, the staging control does not repeat
+  the gate: the reader has met the sentence once and cannot get here without
+  passing it.
+
+So: gate the staging control on the staged operation *unless* the upstream
+control is already gated on the same one.
+
+A surface-level `CardNote` counts as that upstream gate. If the card already
+carries `accessReason` for the *same* operation, its staging controls are not
+gated on it a second time: the reader has met the sentence before starting, and
+N repetitions of it explain nothing the one line did not.
+
+What that removes is the **duplicate explanation, not the disabled state**. The
+staging or submit button stays `disabled` — with no tooltip of its own, because
+the `CardNote` is the explanation — while the draft's own fields and switches
+stay editable (they send nothing; see below). Never re-enable the button
+"because the gateway will refuse anyway": that is precisely the case this rule
+exists against, the caller doing the whole job and meeting the refusal at the end.
+
+And gate only what actually writes. Parsing a pasted CSV, rendering a preview,
+editing a local draft — anything that calls no SDK method — is **reading**, and
+gating it is forbidden: it costs the caller a capability nobody denied them.
+This rule covers the control after which a user without the right would reach
+the refusal having already done the work, with no explanation before it. A
+preview they can look at and discard is not that control.
+
+### Forms with a deferred save
+
+A form the reader fills in and *then* saves is the one case where a hint per
+control is the wrong shape. Fifteen disabled fields, each explaining itself on
+hover, tell the same sentence fifteen times — and the reader who is going to be
+refused learns it only after typing.
+
+Prefer **one line in the card's footer**, stating the constraint before anyone
+starts editing:
+
+```tsx
+import { Card, CardNote } from '@lessly/ui';
+
+<Card title="Domain settings">
+  {fields}
+  {denied && (
+    <CardNote>{accessReason(app.mail.domain.update)}</CardNote>
+  )}
+</Card>
+```
+
+`CardNote` is exactly this line — a lock and one sentence at the card's foot,
+with no tone and no variant, precisely so a frozen card does not grow a box it
+did not have when it was live. It speaks for the card, not for one control on it;
+a constraint that covers a single row still belongs on that row.
+
+The fields themselves stay `readOnly` and the Save button stays disabled — the
+footer note replaces the *per-control tooltips*, not the gate.
+
+### Verify the hint from the keyboard
+
+The whole point of the wrapper is that the reason survives the disabled state, and
+the only proof of that is **reaching it with the keyboard**. Tab to the wrapper;
+the tooltip opens.
+
+```tsx
+it('explains the missing level to a keyboard user', async () => {
+  const user = userEvent.setup();
+  render(<AddDomainButton app={viewerApp} onClick={() => {}} />);
+
+  await user.tab();                                   // focus lands on the wrapper
+  expect(await screen.findByRole('tooltip')).toHaveTextContent(
+    'Requires level:admin (mail_domain_create). Ask an admin of this product.'
+  );
+});
+```
+
+Assert the **rendered tooltip**, not an attribute. A test that only checks that
+some `title`, `aria-describedby` or `data-*` is present passes cheerfully against
+a hint no user can ever see — which is exactly the bug this pattern exists to fix.
+Manual acceptance is the same check by hand: Tab to the control, the reason
+appears, no mouse involved.
+
+---
+
+## 3. `isAccessDenied` in the shared query state — a neutral empty state
+
+A prediction is not a guarantee, so keep handling the real refusal. Grants can
+change between the load and the click, and a screen can always be reached
+before the snapshot is.
+
+```tsx
+import { isAccessDenied } from '@lessly/sdk-app';
+import { useQuery } from '@tanstack/react-query';
+import { mailDomainListQueryOptions } from '@lessly/sdk-app/mail';
+
+function DomainList({ app }: { app: App }) {
+  const { data, error, isPending } = useQuery(mailDomainListQueryOptions(app, {}));
+
+  if (isPending) return <Spinner />;
+
+  // A permission boundary is a NORMAL condition, not a failure of your App.
+  if (isAccessDenied(error)) {
+    return <EmptyState title="You don't have access to domains" body="Ask an admin of this product to grant it." />;
+  }
+
+  if (error) return <ErrorState error={error} />;   // red, retryable — real failures only
+
+  return <Table rows={data.domains} />;
+}
+```
+
+Put that branch in your shared query-state component once, rather than in every
+screen. `isAccessDenied` is true for exactly the three gateway codes that mean
+*the caller's access was the reason* — `role_denied`,
+`operation_uncatalogued`, `no_tool_permission` — and false for every other 403.
+A `tenant_blocked` 403 is not a permission problem and must not be rendered as
+one: it sends the user to an admin who can do nothing about it.
+
+**Never render an access denial in red.** A permission boundary is expected,
+frequent and not the user's mistake. Painting it as a crash teaches people to
+ignore the colour you need for real failures.
+
+
+### State keeps the error OBJECT, not its message
+
+A refusal is only classifiable while it is still an object. The moment a reducer,
+a queue item or a store slice flattens it to a string — `error: errorMessage(err)`,
+`error: err.message`, `` error: `Upload failed: ${err}` `` — `isAccessDenied` has
+nothing left to read, and a denial by role arrives red from a file that has no
+render site at all. Sweeping your render sites never finds it: the classification
+was lost upstream, in state.
+
+So state holds `unknown`, and exactly one shared component classifies it:
+
+```tsx
+// before — the refusal is a string by the time anything renders it
+type UploadItem = { id: string; error: string };
+dispatch({ type: 'failed', id, error: errorMessage(err) });
+{item.error && <ErrorState>{item.error}</ErrorState>}   // always red
+
+// after — the object survives; one component decides the words and the tone
+type UploadItem = { id: string; error: unknown };
+dispatch({ type: 'failed', id, error: err });
+{item.error && <RequestError error={item.error} />}     // isAccessDenied → neutral
+```
+
+`RequestError` is the same classifier as your shared query state — it calls
+`isAccessDenied(error)` and renders the neutral sentence for a denial, red only
+for everything else. Write it once; give every error in the App one way out.
+
+When you audit an App for this, do not comb the render sites. Comb the **state**:
+every reducer, every queue, every store slice, every `useState` whose type says
+`string | null` where an error goes. Content shipped this bug twice — an upload
+queue and a calendar — and both were invisible to a review of the screens.
+
+### A refusal inside the kit's `ConfirmDialog`
+
+`ConfirmDialog` takes `onError?: (error: unknown) => string` — a string, and the
+kit picks the tone from it. So a 403 raised by the confirmed action cannot yet be
+rendered *neutrally* inside the dialog the way it is on a screen: you own the
+words, the kit owns the colour.
+
+Do the half you own. Route the error through the same classifier your shared
+query state uses, so the sentence a denied caller reads is the same neutral one
+everywhere:
+
+```tsx
+<ConfirmDialog
+  title="Delete domain"
+  onConfirm={() => app.mail.domain.delete({ id })}
+  onError={(error) =>
+    isAccessDenied(error)
+      ? "You don't have access to delete domains. Ask an admin of this product."
+      : 'Could not delete the domain. Try again.'
+  }
+/>
+```
+
+**Do not move the confirm flow into your App to win the colour.** Reimplementing
+the dialog costs you the focus trap, the busy state, the confirm phrase and the
+step-up — all to repaint one line of text.
+
+This is known kit debt, tracked as platform **#2915** (`onError` returning
+`{ text, tone }` so the kit can render a denial neutrally). It is tolerable in
+the meantime because a denied caller rarely reaches the dialog at all: the
+control that opens it is disabled under exactly the roles that would be refused.
+A red refusal inside the dialog is only reachable in the snapshot's `error`
+state, where — by the rule above — the App deliberately makes no prediction and
+lets the gateway answer.
+
+---
+
+## 4. Access fixtures in e2e
+
+Do not point an e2e run at a real product to get a real role. Mock
+`GET /governance/api/v1/products/:productId/me` per scenario instead: it is one
+flat body, and the role you need is whichever one the scenario is about.
+
+Never hard-code a real product uuid in the repo, and never create a long-lived
+"smoke test" product to own these roles — both rot into a shared fixture nobody
+dares change, and both make the suite depend on grants that live outside it.
+
+```ts
+// An owner: everything, minus the deny patterns seeded on every product.
+const OWNER = {
+  role: 'owner',
+  allow: ['*'],
+  deny: [],
+};
+
+// A member: read and write, no governance and no billing.
+const MEMBER = {
+  role: 'member',
+  allow: ['level:read', 'level:write'],
+  deny: [
+    '*_roles_create',
+    '*_roles_update',
+    '*_roles_delete',
+    '*_members_assign-role',
+    '*_billing_*',
+  ],
+};
+
+// A viewer: read only — the scenario that greys out every primary action.
+const VIEWER = {
+  role: 'viewer',
+  allow: ['level:read'],
+  deny: [
+    '*_roles_create',
+    '*_roles_update',
+    '*_roles_delete',
+    '*_members_assign-role',
+    '*_billing_*',
+  ],
+};
+```
+
+Two more responses are worth a scenario each, because they are the two the UI
+gets wrong: a **failing** `/me` (500 or a dropped connection — every control
+stays enabled and claims nothing about the role) and a **403** from the action
+itself with a `role_denied` body (the neutral empty state, not the red one).
+
+---
+
+## What not to do
+
+| Don't | Why |
+| --- | --- |
+| Skip the call because `can()` returned false | The snapshot can be stale or simply not loaded. Let the server answer; handle the 403. |
+| Treat `can() === true` as authorisation | It is a prediction. The gateway may still refuse, and only the gateway's answer is a fact. |
+| Drop the `isAccessDenied` branch because every button is gated | A screen can be deep-linked, and grants change mid-session. |
+| Hide controls the caller cannot use | Makes the missing permission unreportable. Disable with a reason instead. |
+| Rebuild a tool id from the accessor path | The path is a lossy view of the id. Pass the method: `app.mail.domain.create`. |
+| Poll `load()` on a timer | The snapshot changes when a role changes; call `invalidate()` then, and only then. |
+| Hand-write the reason text | It goes stale when the catalog re-levels the tool. Build it with `accessReason(op)`. |
+| Name the caller's role in the reason | A role is not something an admin grants. Name the level and the operation key. |
+| Assert only that a hint attribute exists | Green against a tooltip no user can reach. Tab to it and assert the rendered `role="tooltip"`. |
+| Rely on a disabled submit button to stop Enter | Implicit submission fires anyway. Gate `onSubmit`, or make the fields `readOnly`. |
+| Gate a dispatcher button on the union of its modes | It calls one operation per click. Gate the one it is about to call. |
+| Repeat the same tooltip on every field of a deferred-save form | One `CardNote` in the footer, read before editing rather than after. |
+| Gate the drag but not the arrow keys | Same operation, two paths. The hole is keyboard-only, which is the worst place for one. |
+| Nest the Tooltip trigger inside your own `pointer-events-none` | Same silence as the kit's disabled button, in your code. Put the trigger outside it. |
+| Infer a level from the verb ("delete means admin") | There is no such rule: analytics deletes are `write`. Read `op.level`. |
+| Say only the level, with no operation key | Seventeen controls can share one level. The key is what an admin grants on. |
+| Render `level:undefined` for a key with no method | Use the string arm of `accessReason`: name the key, drop the level. |
+| Pass a string key where the method exists | The string arm is a degradation for methodless operations, not an equal input. |
+| Hand `accessReason` a list of operations | It explains one. Pick the denied one first; the rule differs per button shape. |
+| Reimplement `ConfirmDialog` to repaint a denial | Costs the focus trap, busy state, confirm phrase and step-up for one line of text. Kit debt #2915. |
+| Leave a drag handle or inline edit ungated because it has no button | It is the same write. Set the native inactive state and wrap it. Skipping the gate is a spec'd exception, not a default. |
+| Name the headline operation on a multi-operation button | Name the level and key of the operation that actually blocked it. |
+| Put the reason in a native `title=` on the control | `disabled:pointer-events-none` swallows the hover, and a native tooltip is unreachable by keyboard and by touch. Wrap the control in a `TooltipTrigger`. |
+| Hang a surface's reason on a control that owns a different action | The reason must name the operation actually gated. No owning control means one `CardNote` on the surface. |
+| Gate a staging control the surface's `CardNote` already explains | One explanation for the same operation, not N. |
+| Gate a parse, a preview or a local draft | Nothing is sent, so nothing can be refused. Gating reading takes a capability nobody denied. |
+| Store an error as a string in a reducer, queue or store | `isAccessDenied` needs the object. A flattened refusal arrives red from a file with no render site. |
+| Disable a control because `state === 'error'` | Nothing is known about the role. Stay enabled, say nothing about the role, let the gateway answer. |