@lessly/sdk-app 61.2.0 → 62.1.0

package/dist/playground/index.d.cts

@@ -0,0 +1 @@
+export * from '../_types/gen/playground/index.js';

package/dist/playground/index.d.ts

@@ -0,0 +1 @@
+export * from '../_types/gen/playground/index.js';

package/dist/playground/index.js

@@ -0,0 +1,58 @@
+import { wsBindings } from '../chunk-2YAA3AF4.js';
+
+// src/gen/playground/queryOptions.gen.ts
+var playgroundAnalyticsOverviewQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "analytics", "overview", input],
+  queryFn: () => sdk["playground"]["analytics"]["overview"](input)
+});
+var playgroundBillingEntitlementsQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "billing", "entitlements", input],
+  queryFn: () => sdk["playground"]["billing"]["entitlements"](input)
+});
+var playgroundBillingRecordUsageMutationOptions = (sdk) => ({
+  mutationKey: ["playground", "billing", "record-usage"],
+  mutationFn: (input) => sdk["playground"]["billing"]["record-usage"](input)
+});
+var playgroundClickupCreateTaskMutationOptions = (sdk) => ({
+  mutationKey: ["playground", "clickup", "create-task"],
+  mutationFn: (input) => sdk["playground"]["clickup"]["create-task"](input)
+});
+var playgroundClickupGetLastWebhookQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "clickup", "get-last-webhook", input],
+  queryFn: () => sdk["playground"]["clickup"]["get-last-webhook"](input)
+});
+var playgroundClickupGetOverviewQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "clickup", "get-overview", input],
+  queryFn: () => sdk["playground"]["clickup"]["get-overview"](input)
+});
+var playgroundGdriveGetLastChangeQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "gdrive", "get-last-change", input],
+  queryFn: () => sdk["playground"]["gdrive"]["get-last-change"](input)
+});
+var playgroundGdriveReadFileQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "gdrive", "read-file", input],
+  queryFn: () => sdk["playground"]["gdrive"]["read-file"](input)
+});
+var playgroundGoogleadsReadCustomerQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "googleads", "read-customer", input],
+  queryFn: () => sdk["playground"]["googleads"]["read-customer"](input)
+});
+var playgroundLifecycleGetStateQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "lifecycle", "get-state", input],
+  queryFn: () => sdk["playground"]["lifecycle"]["get-state"](input)
+});
+var playgroundLifecycleListEventsQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "lifecycle", "list-events", input],
+  queryFn: () => sdk["playground"]["lifecycle"]["list-events"](input)
+});
+var playgroundWebhookGetLastQueryOptions = (sdk, input) => ({
+  queryKey: ["playground", "webhook", "get-last", input],
+  queryFn: () => sdk["playground"]["webhook"]["get-last"](input)
+});
+
+// src/gen/playground/connect.gen.ts
+var playgroundWsEchoConnect = (sdk, input) => sdk.openStream(wsBindings["playground"]["ws"]["echo"], input);
+
+export { playgroundAnalyticsOverviewQueryOptions, playgroundBillingEntitlementsQueryOptions, playgroundBillingRecordUsageMutationOptions, playgroundClickupCreateTaskMutationOptions, playgroundClickupGetLastWebhookQueryOptions, playgroundClickupGetOverviewQueryOptions, playgroundGdriveGetLastChangeQueryOptions, playgroundGdriveReadFileQueryOptions, playgroundGoogleadsReadCustomerQueryOptions, playgroundLifecycleGetStateQueryOptions, playgroundLifecycleListEventsQueryOptions, playgroundWebhookGetLastQueryOptions, playgroundWsEchoConnect };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/playground/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/gen/playground/queryOptions.gen.ts","../../src/gen/playground/connect.gen.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// AUTOGENERATED by scripts/generate.ts — do not edit.\nimport type { GeneratedClient } from '../client.gen';\nimport type {\n  PlaygroundAnalyticsOverviewInput,\n  PlaygroundAnalyticsOverviewOutput,\n  PlaygroundBillingEntitlementsInput,\n  PlaygroundBillingEntitlementsOutput,\n  PlaygroundBillingRecordUsageInput,\n  PlaygroundClickupCreateTaskInput,\n  PlaygroundClickupGetLastWebhookInput,\n  PlaygroundClickupGetLastWebhookOutput,\n  PlaygroundClickupGetOverviewInput,\n  PlaygroundClickupGetOverviewOutput,\n  PlaygroundGdriveGetLastChangeInput,\n  PlaygroundGdriveGetLastChangeOutput,\n  PlaygroundGdriveReadFileInput,\n  PlaygroundGdriveReadFileOutput,\n  PlaygroundGoogleadsReadCustomerInput,\n  PlaygroundGoogleadsReadCustomerOutput,\n  PlaygroundLifecycleGetStateInput,\n  PlaygroundLifecycleGetStateOutput,\n  PlaygroundLifecycleListEventsInput,\n  PlaygroundLifecycleListEventsOutput,\n  PlaygroundWebhookGetLastInput,\n  PlaygroundWebhookGetLastOutput,\n} from '../types.gen';\n\nexport const playgroundAnalyticsOverviewQueryOptions = (sdk: GeneratedClient, input: PlaygroundAnalyticsOverviewInput) => ({\n  queryKey: ['playground', 'analytics', 'overview', input] as const,\n  queryFn: () => sdk['playground']['analytics']['overview'](input),\n});\n\nexport const playgroundBillingEntitlementsQueryOptions = (sdk: GeneratedClient, input: PlaygroundBillingEntitlementsInput) => ({\n  queryKey: ['playground', 'billing', 'entitlements', input] as const,\n  queryFn: () => sdk['playground']['billing']['entitlements'](input),\n});\n\nexport const playgroundBillingRecordUsageMutationOptions = (sdk: GeneratedClient) => ({\n  mutationKey: ['playground', 'billing', 'record-usage'],\n  mutationFn: (input: PlaygroundBillingRecordUsageInput) => sdk['playground']['billing']['record-usage'](input),\n});\n\nexport const playgroundClickupCreateTaskMutationOptions = (sdk: GeneratedClient) => ({\n  mutationKey: ['playground', 'clickup', 'create-task'],\n  mutationFn: (input: PlaygroundClickupCreateTaskInput) => sdk['playground']['clickup']['create-task'](input),\n});\n\nexport const playgroundClickupGetLastWebhookQueryOptions = (sdk: GeneratedClient, input: PlaygroundClickupGetLastWebhookInput) => ({\n  queryKey: ['playground', 'clickup', 'get-last-webhook', input] as const,\n  queryFn: () => sdk['playground']['clickup']['get-last-webhook'](input),\n});\n\nexport const playgroundClickupGetOverviewQueryOptions = (sdk: GeneratedClient, input: PlaygroundClickupGetOverviewInput) => ({\n  queryKey: ['playground', 'clickup', 'get-overview', input] as const,\n  queryFn: () => sdk['playground']['clickup']['get-overview'](input),\n});\n\nexport const playgroundGdriveGetLastChangeQueryOptions = (sdk: GeneratedClient, input: PlaygroundGdriveGetLastChangeInput) => ({\n  queryKey: ['playground', 'gdrive', 'get-last-change', input] as const,\n  queryFn: () => sdk['playground']['gdrive']['get-last-change'](input),\n});\n\nexport const playgroundGdriveReadFileQueryOptions = (sdk: GeneratedClient, input: PlaygroundGdriveReadFileInput) => ({\n  queryKey: ['playground', 'gdrive', 'read-file', input] as const,\n  queryFn: () => sdk['playground']['gdrive']['read-file'](input),\n});\n\nexport const playgroundGoogleadsReadCustomerQueryOptions = (sdk: GeneratedClient, input: PlaygroundGoogleadsReadCustomerInput) => ({\n  queryKey: ['playground', 'googleads', 'read-customer', input] as const,\n  queryFn: () => sdk['playground']['googleads']['read-customer'](input),\n});\n\nexport const playgroundLifecycleGetStateQueryOptions = (sdk: GeneratedClient, input: PlaygroundLifecycleGetStateInput) => ({\n  queryKey: ['playground', 'lifecycle', 'get-state', input] as const,\n  queryFn: () => sdk['playground']['lifecycle']['get-state'](input),\n});\n\nexport const playgroundLifecycleListEventsQueryOptions = (sdk: GeneratedClient, input: PlaygroundLifecycleListEventsInput) => ({\n  queryKey: ['playground', 'lifecycle', 'list-events', input] as const,\n  queryFn: () => sdk['playground']['lifecycle']['list-events'](input),\n});\n\nexport const playgroundWebhookGetLastQueryOptions = (sdk: GeneratedClient, input: PlaygroundWebhookGetLastInput) => ({\n  queryKey: ['playground', 'webhook', 'get-last', input] as const,\n  queryFn: () => sdk['playground']['webhook']['get-last'](input),\n});\n","// AUTOGENERATED by scripts/generate.ts — do not edit.\nimport { wsBindings } from '../bindings.gen';\nimport type { LesslyStream, LesslyStreamOpener } from '../../runtime/types';\nimport type {\n  PlaygroundWsEchoInput,\n} from '../types.gen';\n\nexport const playgroundWsEchoConnect = (sdk: LesslyStreamOpener, input: PlaygroundWsEchoInput): LesslyStream =>\n  sdk.openStream(wsBindings['playground']!['ws']!['echo']!, input as Record<string, unknown>);\n"]}

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. |