@lessly/sdk-app 62.0.0 → 62.1.0

package/docs/recipes/access.md

@@ -33,10 +33,14 @@ 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 anything you
-render from it must start in the disabled state and enable 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.
+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.
 
 You can pass either a tool id or a generated method, which carries its own
 identity:
@@ -58,17 +62,24 @@ drift from the method it is meant to describe; the method cannot.
 // 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 every consumer of
-    // can() is already fail-closed.
+    // 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]);
 
-  return <Routes app={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>
+  );
 }
 ```
 
@@ -87,23 +98,174 @@ refetched on a timer.
 ## 2. `useCan` on primary actions — disable, don't hide
 
 ```tsx
-import { useCan } from '@lessly/sdk-app/react';
+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);
 
-  return (
-    <button
-      onClick={onClick}
-      disabled={!canCreate}
-      title={canCreate ? undefined : 'Your role cannot add domains. Ask an admin of this product.'}
-    >
+  // '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>
+    </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 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';
+> export const accessReason = (op: Operation | string): string =>
+>   typeof op === 'string'
+>     ? `Requires access to ${op}. Ask an admin of this product.`
+>     : `Requires level:${op.level} (${op.operationKey}). Ask an admin of this product.`;
+> ```
+
+**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.
+
+### 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
@@ -123,6 +285,179 @@ if (state === 'error') return <p>Could not load your permissions. <button onClic
 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.
+
+### 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.
+
+### 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
@@ -163,6 +498,94 @@ one: it sends the user to an admin who can do nothing about it.
 frequent and not the user's mistake. Painting it as a crash teaches people to
 ignore the colour you need for real failures.
 
+
+### 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
@@ -175,3 +598,21 @@ ignore the colour you need for real failures.
 | 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`. |
+| Disable a control because `state === 'error'` | Nothing is known about the role. Stay enabled, say nothing about the role, let the gateway answer. |

package/docs/rules.md

@@ -338,6 +338,91 @@ An App SHOULD reflect the caller's access in its UI: **disable, with a reason**
 (not hide) a primary action the caller cannot perform, using `useCan` from
 `@lessly/sdk-app/react` or `app.access.can()` directly, and render a 403 that
 `isAccessDenied()` recognises as a **neutral empty state** rather than an error.
+That reason MUST live on a `Tooltip` wrapper around the disabled control, never
+on a native `title=` of the control itself: the base `buttonVariants` carry
+`disabled:pointer-events-none`, so a disabled control fires no hover for the
+browser to render a `title` from, and a native tooltip is unreachable by
+keyboard and by touch in any case. An App that draws such a tooltip MUST mount
+its own `TooltipProvider` once at the root of its remote — `Tooltip.Root` throws
+without one, and the standalone build, the dev entry and the tests all render
+outside the shell.
+
+That reason MUST be exactly one sentence, the same in every App:
+
+> `Requires level:<op.level> (<op.operationKey>). Ask an admin of this product.`
+
+— e.g. `Requires level:admin (mail_domain_create). Ask an admin of this product.`
+Both values MUST be read from the generated method, never written as literals.
+`@lessly/sdk-app` exports `accessReason(op)`, which is that sentence; an App
+SHOULD use it rather than assembling the text itself.
+
+Where a control has only an operation key and no generated method to point at,
+the App MUST NOT guess the level or render `level:undefined`; it says instead:
+
+> `Requires access to <operationKey>. Ask an admin of this product.`
+
+That string form is a **degradation** for operations no generated method covers,
+not licence to pass a key where a method exists — the accessor path is a lossy
+view of the key. An App whose every gate holds an `Operation` never uses it, and
+that is the norm rather than an omission. `accessReason` explains ONE operation;
+choosing which one to explain among a button's several is the caller's, not the
+helper's.
+It names what an admin can grant, not the caller's role: a role name gives them
+nothing to act on. It names the operation key as well as the level because a
+level alone does not identify the grant — seventeen controls on one screen can
+all require `level:write` — and an admin grants both by level and by exact key,
+so the user has to be able to pass on both. Building it from the method also
+keeps it from drifting when the catalog re-levels a tool. Whatever renders it MUST be verified reachable **from the keyboard** —
+Tab to the wrapper, the tooltip opens (in tests: `userEvent.tab()` then
+`findByRole('tooltip')`). Asserting only that a hint attribute is present does
+not satisfy this: that assertion is green against a hint no user can reach.
+
+The level MUST come from the generated method itself (`op.level`, on the
+`Operation` the method satisfies) and from nowhere else: not a lookup table in
+the App, not a literal, and never a rule of thumb about verbs — `analytics_*_delete`
+is `write` while `mail_domain_create` is `admin`, and only the catalog knows.
+
+The gate belongs to the OPERATION, not to a gesture: where a write is reachable
+by several paths (drag and arrow keys, click and Enter, button and hotkey) all of
+them MUST be gated together, or the hole left behind is one only keyboard users
+find. Implicit form submission is such a path: a disabled submit button does not
+reliably stop Enter inside a field, so the `onSubmit` handler MUST be gated (or
+the fields made `readOnly`) rather than the button alone.
+
+A control that performs SEVERAL operations per click is disabled if ANY of them
+is denied. A DISPATCHER control — one operation per click, selected by a mode or
+a switch — MUST instead be gated on the operation it is about to call, and name
+that operation's level and key; gating it on the union greys out a button the caller can
+in fact use.
+
+An App SHOULD state the constraint once in a card footer (`CardNote`) rather than
+on every control of a form whose save is deferred: the reader meets the sentence
+before editing rather than after, and one line replaces fifteen identical
+tooltips. The fields stay inactive and the save stays disabled either way — the
+note replaces the per-control hints, not the gate. And the `Tooltip` trigger MUST sit outside every element carrying
+`pointer-events-none` — the App's own lists, chips and overlays as much as the
+kit's disabled buttons — since the hint is swallowed by the same mechanics either
+way.
+
+This applies to every gated write, not only the ones with a button. A drag
+handle, an inline-editable cell and a field that autosaves on blur are gated the
+same way: the native inactive state for that control (`draggable={false}`,
+`readOnly`, `disabled`) plus the reason on a keyboard-reachable `Tooltip`
+wrapper. Leaving a write ungated for the gateway to refuse is permitted ONLY
+where the element has no wrapper that can be made focusable, and that exception
+MUST be written into the App's own spec with its reason. A button that performs
+several operations is disabled if ANY of them is denied, and its reason names
+the level and key of the operation that blocked it.
+
+The reason is claimed only when the App actually knows it. With
+`access.state === 'error'` the `/me` call failed and **nothing** is known about
+the caller's role: the App MUST make no prediction — leave the control enabled,
+name no missing operation, and let the gateway answer, rendering any refusal through
+`isAccessDenied`. Disabling on error makes the client the authority and tells
+the user their role forbids something no one has established. (`can()` itself is
+unaffected: it stays `false` unless the state is `ready`.) While the state is
+`idle` or `loading` the control SHOULD start disabled and enable itself, but
+SHOULD NOT name a missing level or operation it does not yet know.
 
 An App MUST NOT treat that prediction as enforcement. `can()` answers from a
 snapshot fetched once from the `organization_product_me` tool; the gateway is
@@ -363,4 +448,11 @@ Pass the generated method rather than a hand-written tool id
 (`app.access.can(app.mail.domain.create)`): the accessor path is a lossy view
 of the tool id, so a literal string can silently drift from the call it gates.
 
+One gap is known and accepted: `@lessly/ui`'s `ConfirmDialog` takes an `onError`
+that returns a string, so the kit picks the tone and a refusal raised inside the
+dialog cannot be painted neutrally yet. An App SHOULD still route that error
+through `isAccessDenied()` for the *words*, and MUST NOT reimplement the confirm
+flow to win the colour — it would forfeit the focus trap, busy state, confirm
+phrase and step-up. Tracked as platform #2915.
+
 See `recipes/access.md` for the load-once pattern and the empty-state shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessly/sdk-app",
-  "version": "62.0.0",
+  "version": "62.1.0",
   "type": "module",
   "sideEffects": false,
   "engines": {