@antelopejs/interface-dms 0.10.3 → 0.12.0

package/docs/1.core/3.components.md

@@ -1,21 +1,20 @@
 ---
 title: "Components"
 description: "A component is a serializable description of a piece of UI, not a live object."
+mode: reference
 ---
 
-# Components
-
 ## Overview
 
 A component is a serializable description of a piece of UI, not a live object. `ComponentBuilder` collects a component name, an options object, children, watches and actions; `serialize()` turns that into plain JSON-safe data; the page layout route returns the result. Nothing in this interface renders anything.
 
 Everything on this page lives in `@antelopejs/interface-dms/component`. The [Base](/docs/interfaces/base/introduction) domain ships the concrete builders (`Form`, `TableView`, `Grid`, the chart family) built on top of these types; use this page when you write a builder of your own or when you need to know what a serialized component looks like.
 
-## The Serialize-Then-Render Contract
+## Serialize, then render
 
 Two shapes describe the same component on the two sides of serialization:
 
-```typescript
+```typescript fragment
 interface ComponentInfo<T = unknown, C = Component<T>, ChildType = ComponentChild<T, C>> {
   componentName: string;
   options?: T;
@@ -39,7 +38,7 @@ type ComponentInfoSerialized<T = unknown> = Omit<ComponentInfo<T>, "children"> &
 
 The extra index signature on a child is the escape hatch for per-child props a container needs (a grid column span, a tab label): whatever you pass in the child metadata survives serialization next to `id`, `component` and `slot`.
 
-## Build a Component
+## Build a component
 
 `ComponentBuilder<T>` is the class you instantiate with the frontend component name. Every method returns `this`, so calls chain.
 
@@ -66,14 +65,14 @@ Assign the result to a static field of a page class and `@RegisterPage()` picks
 | `mergeOptions(opts)` | Shallow-merge into the existing options. Logs a warning and does nothing when no options were set. |
 | `child(id, component, metadata?)` | Append a child with its own positional permission. `metadata` may carry `slot` plus any additional props. A duplicate `id` logs a warning. |
 | `meta(meta)` | Merge into the component metadata (`name`, `description`, `icon`). |
-| `onCreated(callback)` | Run `callback(pageMetadata)` when the component's page registers. |
+| `onCreated(callback)` | Run `callback(page)` when the component's page registers. `page` is typed `CreatedPage` (`target`, `pageInfo.fullId`, `pageInfo.fullSlug`); at run time it is the page's `PageMetadata`. |
 | `onFilter(callback)` | Transform the options per caller, from their permission set. |
 | `watch(event, functionId, opts?)` | Declare a watch on this component. |
 | `watchOn(childId, event, functionId, opts?)` | Declare a watch spliced into a child's options at serialization time. |
 | `watchFilter(callback)` | Filter the accumulated watches per caller. |
 | `action(id, definition)` | Declare an `Action` on the component. |
 | `button(id, { permission? })` | Register a named button a quick action can press, with the permission (an action id of this component, or any `Action`) that gates it. A duplicate `id` logs a warning. The table view registers its `customButtons` that carry an `id`. |
-| `navBadge({ count, page? })` | Publish a count as the navigation badge of a page (`NavBadgeSource`): `count(ctx, user)` answers it for the caller on each page visit — a number, drawn neutral, or `{ count, tone }` ([Navigation badges](#navigation-badges)) — and throws to publish nothing for a caller who may not read it. `page` names the page controller the badge goes to, the component's own page by default. A table view's tab declared with `navBadge` publishes through it; a component of your own calls it directly (the DMS's notifications, security and roles pages do). A count of zero shows no badge, and a page's static `MenuOptions.badge` wins. |
+| `navBadge({ count, page? })` | Publish a count as the navigation badge of a page (`NavBadgeSource`): `count(ctx, user)` answers it for the caller on each page visit with a number, drawn neutral, or `{ count, tone }` ([Navigation badges](#navigation-badges)). It throws to publish nothing for a caller who may not read it. `page` names the page controller the badge goes to, the component's own page by default. A table view's tab declared with `navBadge` publishes through it; a component of your own calls it directly (the DMS's notifications, security and roles pages do). A count of zero shows no badge, and a page's static `MenuOptions.badge` wins. |
 | `before(anchor)` | Place the component above `anchor` (a component key of the target page) when injecting it into another page. |
 | `after(anchor)` | Place it below `anchor`. |
 | `order(value)` | Break ties between components landing at the same spot. Defaults to 0. |
@@ -82,7 +81,7 @@ Assign the result to a static field of a page class and `@RegisterPage()` picks
 
 `count` answers a number, drawn as a neutral grey pill, or a `NavBadgeCount` that also gives the tone it is drawn in, with the colours of the dashboard's status pills:
 
-```typescript
+```typescript fragment
 interface NavBadgeCount {
   count: number;
   tone?: Tone; // from "@antelopejs/interface-dms/base/types/tone"
@@ -116,11 +115,11 @@ interface ComponentPlacement {
 const DEFAULT_PLACEMENT: ComponentPlacement = { side: "end", order: 0 };
 ```
 
-`anchor` is a component key of the target page: the name of the static field it declared the component under, passed as `.before("table")`, or a dotted path to a nested position, `.before("content.tasks")` — stored as the split path. The target page is never imported, so the key is a string. A component that declares no placement gets `DEFAULT_PLACEMENT` — appended after every component of the target page, with no ordering hint. Read the current value off `component.placement`, which is `undefined` until one of the three methods is called.
+`anchor` is a component key of the target page: the name of the static field it declared the component under, passed as `.before("table")`, or a dotted path to a nested position, `.before("content.tasks")`, stored as the split path. The target page is never imported, so the key is a string. A component that declares no placement gets `DEFAULT_PLACEMENT`: appended after every component of the target page, with no ordering hint. Read the current value off `component.placement`, which is `undefined` until one of the three methods is called.
 
 Lower `order` comes first, and equal orders fall back to the extension class name and then to declaration order, so the result never depends on module start order. [Pages and Modules](/docs/interfaces/core/pages-and-modules) covers the extension mechanism these describe placement for.
 
-### Children and Slots
+### Children and slots
 
 ```typescript
 import { ComponentBuilder } from "@antelopejs/interface-dms/component";
@@ -134,11 +133,11 @@ const panel = new ComponentBuilder<{ title: string }>("acme-panel")
 
 The `grow: true` above is an arbitrary extra prop: it lands on the serialized child alongside `id`, `component` and `slot`.
 
-## The `Component` Class
+## The `Component` class
 
 `ComponentBuilder` extends `Component<T>`, which is also usable directly when you already hold a `ComponentInfo`:
 
-```typescript
+```typescript fragment
 new Component<T>(
   componentInfo: ComponentInfoPromise<T>,
   metadata: ComponentMetadata,
@@ -159,7 +158,7 @@ new Component<T>(
 | `onPageCreated` | The callback run when the owning page registers. |
 | `onFilterCallback` | The per-caller options filter, when one is installed. |
 | `placement` | The `ComponentPlacement`, or `undefined` when none was declared. |
-| `serialize()` | `Promise<ComponentInfoSerialized<T>>` — awaits the component info and serializes every child. |
+| `serialize()` | `Promise<ComponentInfoSerialized<T>>`. Awaits the component info and serializes every child. |
 | `serializeSync()` | The same, for a component whose info is not a promise. |
 
 Both serialize methods normalize `children` to `[]` when the component has none.
@@ -168,7 +167,7 @@ Because `componentInfo` may be a promise, a builder can resolve data at registra
 
 ## Actions
 
-An action is a named capability of a component that carries its own permission — "add a row", "export", "restore". Declare one on the builder:
+An action is a named capability of a component that carries its own permission, such as "add a row", "export" or "restore". Declare one on the builder:
 
 ```typescript
 import { ComponentBuilder } from "@antelopejs/interface-dms/component";
@@ -195,13 +194,13 @@ An `Action` instance exposes:
 | `permissionId` | The component's permission id with `.<id>` appended, or `undefined` while the component has no permission id yet. |
 | `toPermission()` | A `Permission` built from the definition, or `undefined` when `permissionId` is. |
 
-The component's permission id only exists once the owning page has registered, so read `permissionId` from `onCreated` or later — not while the builder is still being assembled.
+The component's permission id only exists once the owning page has registered, so read `permissionId` from `onCreated` or later, not while the builder is still being assembled.
 
 An `Action` is accepted anywhere a permission is: as the `permission` option of a page ([Pages and Modules](/docs/interfaces/core/pages-and-modules)) and as the target of `AuthUserWithPermission` ([Permissions](/docs/interfaces/core/permissions)).
 
 `getPermissionIdRef` is the seam that lets `Action` resolve its component's permission id without importing the page module: it is an object with a single `get(component)` method, replaced by `dms/page` when that module loads. Consumers read `permissionId`; there is no reason to call or reassign the ref.
 
-## Per-Caller Filtering
+## Per-caller filtering
 
 `onFilter` rewrites a component's options for the caller who requested the page layout. It runs during layout resolution, after the component itself passed its permission check.
 
@@ -221,13 +220,13 @@ const list = new ComponentBuilder<ListOptions>("acme-list")
   }));
 ```
 
-The callback receives `(permissions: Set<string>, options: T, permissionId: string, context: ComponentFilterContext)` and returns the options — synchronously or as a promise. The third argument is the component position's own permission id, including the full parent path for a child, so a filter can derive the ids of the actions it needs to test. The fourth is the request the layout is built for: its `tenantId`, its `user` (undefined when unauthenticated), and `query`, the page URL's query when the request carries one (what a header button's `availability` reads; check its values like any input).
+The callback receives `(permissions: Set<string>, options: T, permissionId: string, context: ComponentFilterContext)` and returns the options, synchronously or as a promise. The third argument is the component position's own permission id, including the full parent path for a child, so a filter can derive the ids of the actions it needs to test. The fourth is the request the layout is built for: its `tenantId`, its `user` (undefined when unauthenticated), and `query`, the page URL's query when the request carries one (what a header button's `availability` reads; check its values like any input).
 
 ## Watches
 
 A watch binds an event on a component to a registered function. The backend only describes the binding.
 
-```typescript
+```typescript fragment
 watch<F extends string>(event: string, functionId: F, opts?: WatchOptions<F>): this
 watchOn<F extends string>(childId: string, event: string, functionId: F, opts?: WatchOptions<F>): this
 ```
@@ -263,7 +262,7 @@ const form = Form({ title: "Profile", fields: [] }).watch(
 
 `watchFilter(callback)` narrows the watch list per caller: it receives `(permissions, watches, permissionId)` and returns the watches to keep. It runs right after `onFilter` in the same filtering pass, and the `requirePermission` narrowing is applied to whatever it returns.
 
-## Component Events
+## Component events
 
 `ComponentEvents` holds the lifecycle event names:
 
@@ -276,12 +275,12 @@ Use them as the `event` argument of `watch` or `watchOn`, or as the event name i
 
 ## `RegisterComponentSlot`
 
-`RegisterComponentSlot(slotId: string, resolver: ComponentSlotResolver): () => void`, from `@antelopejs/interface-dms/component-slots`, claims a component slot. The resolver receives the options of each component declaring that `slotId`, once per layout request, and returns the replacement options. Returning the input unchanged contributes nothing.
+`RegisterComponentSlot(slotId: string, resolver: ComponentSlotResolver): () => void`, from `@antelopejs/interface-dms/component-slots`, claims a component slot. The resolver receives the options of each form declaring that `slotId`, once per layout request, and returns the replacement options. Returning the input unchanged contributes nothing. Only a form opens a slot: a `slotId` in the options of another component, or in a form whose options carry no `fields` array, is ignored.
 
-`SlotOptions` is `Record<string, unknown>`; `ComponentSlotResolver` is `(options: SlotOptions) => MaybePromise<SlotOptions>`. The latest claim for an id wins. The returned release function removes the claim only if that resolver still owns it, so releasing an older claim does not remove a newer one.
+`SlotOptions` is the serialized options of a form (`FormPropsSerialized` plus `watchActions`), so `options.fields` needs no cast; `ComponentSlotResolver` is `(options: SlotOptions) => MaybePromise<SlotOptions>`. The latest claim for an id wins. The returned release function removes the claim only if that resolver still owns it, so releasing an older claim does not remove a newer one.
 
 Use the returned function when the claiming module stops. [TableView form slots](/docs/components/tables#tableview-options) show how a controller exposes a slot; the controller still owns validation and persistence of contributed fields.
 
-## Next Steps
+## Next steps
 
 [Permissions](/docs/interfaces/core/permissions) covers the ids these components and actions register, and the guards that check them.

package/docs/1.core/4.permissions.md

@@ -1,15 +1,12 @@
 ---
 title: "Permissions"
-description: "Permission ids are hierarchical strings built from the page tree: a page's `fullId`, then every component id in the position's path, then the action id when present."
+description: "Permission ids are dot-separated strings built from the page tree. The registry, the permission computation, the resolvers that reshape a set, and the route guards that check it."
+mode: reference
 ---
 
-# Permissions
+A permission id is a dot-separated string built from the page tree: a page's `fullId`, then every component id in the position's path, then the action id when there is one. A role holds a flat list of granted ids, and a platform owner holds the wildcard `*`. `GetUserPermissions` returns the base set a user's roles grant. `GetEffectiveUserPermissions` runs that set through the registered resolvers, and every authorization surface uses the effective set.
 
-## Overview
-
-Permission ids are hierarchical strings built from the page tree: a page's `fullId`, then every component id in the position's path, then the action id when present. A role holds a flat list of granted ids; a platform owner holds the wildcard `*`. Two functions answer "what can this user do" — `GetUserPermissions` returns the base set from roles, `GetEffectiveUserPermissions` runs that set through the registered resolvers. Authorization surfaces use the effective set.
-
-The surface spans three subpaths:
+The API spans three subpaths:
 
 | Subpath | Contains |
 | ------- | -------- |
@@ -17,9 +14,9 @@ The surface spans three subpaths:
 | `@antelopejs/interface-dms/permissions-resolver` | Registering and running resolvers |
 | `@antelopejs/interface-dms/guards` | Route guards |
 
-## Register a Permission
+## Register a permission
 
-Pages, components and actions register their own permissions when the page registers ([Pages and Modules](/docs/interfaces/core/pages-and-modules)). Register a standalone one when a capability has no component behind it:
+Pages, components and actions register their own permissions when the page registers ([Pages and modules](/docs/interfaces/core/pages-and-modules)). Register a standalone permission for a capability that has no component behind it:
 
 ```typescript
 import { RegisterPermission } from "@antelopejs/interface-dms/permissions";
@@ -34,6 +31,8 @@ RegisterPermission("reports.export", {
 });
 ```
 
+`RegisterPermission(id, permission)` takes the id twice, once as the registry key and once inside the record. Keep the two equal.
+
 ### `Permission`
 
 | Field | Type | Description |
@@ -42,16 +41,14 @@ RegisterPermission("reports.export", {
 | `title` | `string` | Label shown in the roles editor. Required. |
 | `icon` | `string` | Icon name. |
 | `description` | `string` | Longer description. |
-| `dependencies` | `string[]` | Permission ids this one needs to be of any use. The roles editor grants them with it (and takes it away with them), and a role is saved with them and the ids they sit under. `HasPermission` requires them, like the ids above: a registered dependency the set lacks makes the permission count for nothing. An unregistered one counts as held. |
-| `defaultGranted` | `boolean` | Treat the permission as held by every caller, without a role grant. |
-
-A table view's actions declare their `dependencies` themselves: `edit` and `export` need `view`, and every action only reached from the rows — `delete`, `archive`, `viewArchived`, `export`, and `add`/`edit`/`view` when their form opens over the table — needs `list`; `restore` needs `viewArchived`. A form opening as its own page and `select` need no `list`.
+| `dependencies` | `string[]` | Permission ids this one needs to be of any use. The roles editor grants them with it and removes it with them, and a role is saved with them and the ids they sit under. `HasPermission` requires each registered dependency, so a missing one makes the permission count for nothing. An unregistered dependency counts as held. |
+| `defaultGranted` | `boolean` | Treats the permission as held by every caller, without a role grant. |
 
-`RegisterPermission(id, permission)` takes the id twice — once as the registry key, once inside the record — so keep them equal.
+A table view's actions declare their own `dependencies`. `edit` and `export` need `view`. Every action reached only from the rows needs `list`: `delete`, `archive`, `viewArchived`, `export`, and `add`, `edit` and `view` when their form opens over the table. `restore` needs `viewArchived`. A form that opens as its own page, and `select`, need no `list`.
 
-`UnregisterPermission(id)` drops a permission from the grantable tree again. It exists for registrations undone while the process keeps running — a page extension whose module stopped, for instance. A permission left behind after its surface is gone stays offered in the roles editor and stays grantable, so anything that registers a permission conditionally should unregister it on the same condition.
+`UnregisterPermission(id)` drops a permission from the grantable tree. It serves registrations undone while the process keeps running, such as a page extension whose module stopped. A permission left behind after its surface is gone stays offered in the roles editor and stays grantable, so code that registers a permission under a condition unregisters it under the same condition.
 
-## Read the Registry
+## Read the registry
 
 ```typescript
 import {
@@ -63,25 +60,26 @@ const permission = await GetPermission("reports.export");
 const tree = await GetPermissions();
 ```
 
-`GetPermission(id)` resolves to the `Permission` or `undefined`. `GetPermissions()` resolves to a `Record<string, PermissionTree>` keyed by the first id segment, where
+`GetPermission(id)` resolves to the `Permission` or `undefined`. `GetPermissions()` resolves to a `Record<string, PermissionTree>` keyed by the first id segment:
 
-```typescript
+```typescript fragment
 type PermissionTree = {
   data?: Permission;
   children: Record<string, PermissionTree>;
 };
 ```
 
-Each level keys its children by the next dot-separated segment. `data` is absent for a level that exists only to hold children.
+Each level keys its children by the next dot-separated segment. `data` is absent on a level that exists only to hold children.
 
-Both are interface functions and return promises even though the registry is in-process.
+Both are interface functions, so they return promises even though the registry is in the same process.
 
-## Compute a User's Permissions
+## Compute a user's permissions
 
 ```typescript
 import {
   GetEffectiveUserPermissions,
   GetUserPermissions,
+  HasAnyPermission,
   HasPermission,
 } from "@antelopejs/interface-dms/permissions";
 ```
@@ -89,22 +87,26 @@ import {
 | Function | Signature |
 | -------- | --------- |
 | `GetUserPermissions` | `(user: { owner?: boolean }, roleIds: string[], roleModel: RoleModel) => Promise<Set<string>>` |
-| `GetEffectiveUserPermissions` | `(user: { _id: string; owner?: boolean }, tenantId: string, roleIds: string[], roleModel: RoleModel) => Promise<Set<string>>` |
+| `GetEffectiveUserPermissions` | `(user: { _id: string; owner?: boolean }, tenantId: string, roleIds: string[], roleModel: RoleModel, context?: PermissionsResolverContext) => Promise<Set<string>>` |
 | `HasPermission` | `(permissions: Set<string>, permissionId: string) => Promise<boolean>` |
+| `HasAnyPermission` | `(permissions: Set<string>, permissionIds: string[]) => Promise<boolean>` |
 
-`GetUserPermissions` returns `Set(["*"])` for a user with `owner: true`, an empty set when `roleIds` is empty, and otherwise the union of the `permissions` arrays of the roles it loads through `roleModel`. This is the **base** set: it does not account for resolvers, so do not authorize against it.
+`GetUserPermissions` returns `Set(["*"])` for a user with `owner: true`, an empty set when `roleIds` is empty, and otherwise the union of the `permissions` arrays of the roles it loads through `roleModel`. That is the base set. It ignores resolvers, so never authorize against it.
 
-`GetEffectiveUserPermissions` composes that base set with `ApplyPermissionsResolvers` and is the set every authorization surface uses.
+`GetEffectiveUserPermissions` passes the base set through `ApplyPermissionsResolvers`, with `context` (default `{}`) handed to each resolver. Every authorization surface uses this set: route guards, page and menu visibility, table view action checks and search.
 
-`HasPermission` resolves in this order:
+`HasPermission` checks in this order:
 
 1. `true` when the set holds the wildcard `*`.
 2. `false` when the id is module-scoped.
 3. `true` when the registered permission carries `defaultGranted`.
 4. `false` when the set does not hold the id.
-5. `true` when the set also holds every id the permission sits under (`pages.sales` and `pages` for `pages.sales.orders`), `false` otherwise. An id above it that is not a registered permission, or that carries `defaultGranted`, counts as held.
+5. `false` when the set lacks an id the permission sits under (`pages.sales` and `pages` for `pages.sales.orders`). An id above it that is not a registered permission, or that carries `defaultGranted`, counts as held.
+6. `false` when a registered dependency fails the same check. Otherwise `true`.
+
+The wildcard comes first, so a platform owner passes even for a module-scoped id. Step 5 makes a grant worthless without its parents: a role that holds neither a table nor its page is refused the table's `delete` action. The roles editor and the role routes store each grant with every id above it, so only an older saved role, or a set a resolver reshaped, can miss one.
 
-The wildcard is checked first, so a platform owner passes even for a module-scoped id. Step 5 makes a grant worth nothing without its parents: a table's `delete` action is refused to a role that holds neither the table nor its page. The roles editor and the role routes store a grant with every id above it, so only a role saved before they did, or a set a resolver reshaped, can miss one.
+`HasAnyPermission` returns `true` when `HasPermission` passes for at least one of the ids.
 
 ```typescript
 import { GetModel } from "@antelopejs/interface-database-decorators";
@@ -130,11 +132,11 @@ async function canExport(user: User, tenantId: string): Promise<boolean> {
 }
 ```
 
-`RoleModel` and `TenantMemberModel` come from [Tenancy](/docs/interfaces/core/tenancy).
+`RoleModel` and `TenantMemberModel` are described in [Tenancy](/docs/interfaces/core/tenancy).
 
-## Module-Scoped Permissions
+## Module-scoped permissions
 
-Permissions belonging to a module page or category are never added to the grantable permission tree, and a role grant on such an id never grants anything. They are marked instead:
+The permissions of a module page or category never enter the grantable permission tree, and a role grant on such an id grants nothing. The ids are marked instead:
 
 ```typescript
 import {
@@ -144,19 +146,19 @@ import {
 } from "@antelopejs/interface-dms/permissions";
 
 MarkModuleScopedPermission("modules.automation.builder");
-IsModuleScopedPermission("modules.automation.builder.canvas.add"); // true
+const scoped = IsModuleScopedPermission("modules.automation.builder.canvas.add");
 UnmarkModuleScopedPermission("modules.automation.builder");
 ```
 
-`IsModuleScopedPermission(id)` walks the id upward one dot-separated segment at a time, so marking a page id also covers every component and action id derived from it. `UnmarkModuleScopedPermission(id)` removes the mark for that exact id only.
+`IsModuleScopedPermission(id)` checks the id and each id above it, one dot-separated segment at a time, so marking a page id also covers every component and action id derived from it. In the example, `scoped` is `true`. `UnmarkModuleScopedPermission(id)` removes the mark for that exact id only.
 
-Page registration calls `MarkModuleScopedPermission` for you whenever `isInsideModule` holds ([Pages and Modules](/docs/interfaces/core/pages-and-modules)); call it directly only for ids you build outside that path.
+Page and category registration calls `MarkModuleScopedPermission` whenever `isInsideModule` holds ([Modules and dynamic menus](/docs/interfaces/core/modules-and-dynamic-menus#module-urls-and-ids)). Call it directly only for ids you build outside that path.
 
-## Reshape the Effective Set
+## Reshape the effective set
 
 A permissions resolver receives a caller's current permission set for a tenant and returns the set to use instead.
 
-```typescript
+```typescript fragment
 import { RegisterPermissionsResolver } from "@antelopejs/interface-dms/permissions-resolver";
 
 export async function construct(): Promise<void> {
@@ -180,23 +182,33 @@ type PermissionsResolverFn = (
 ) => Promise<Set<string>> | Set<string>;
 
 interface PermissionsResolverContext {
-  /** Set when the call previews a role rather than computing a member's set. */
   preview?: PermissionsResolverPreview;
 }
 
 interface PermissionsResolverPreview {
-  /** The previewed role's permissions, before any resolver reshaped them. */
   rolePermissions: ReadonlySet<string>;
 }
 ```
 
-`PermissionsResolverInfo` carries `id`, `resolver` and `order`.
+`PermissionsResolverInfo` carries `id`, `resolver` and `order`. `context.preview` is set when the call previews a role instead of computing a member's set, and `rolePermissions` holds the previewed role's permissions before any resolver reshaped them.
+
+The interface guarantees these semantics:
+
+- Resolvers run in ascending `order`, each one receiving the previous one's result. Equal `order` runs in registration order, which is module load order.
+- Registering an id twice replaces the earlier resolver in its slot instead of adding a second one.
+- A resolver that throws aborts the computation and fails the request. It is never skipped.
+- The registration is removed when the registering module unloads. There is no unregister call.
+- Register in `construct()`, so the resolver is active before the API serves requests.
+
+`ApplyPermissionsResolvers(userId, tenantId, basePermissions, context)` runs the pipeline, hands `context` to every resolver, and resolves to the effective set. `GetEffectiveUserPermissions` computes the base set and calls it, so prefer that function.
+
+A resolver shapes a permission set. It cannot deny a surface that consults no permission set, and it cannot revoke a `defaultGranted` permission, which `HasPermission` grants after the resolvers ran. To cut a tenant off from the product entirely, register a tenant access gate instead ([Tenancy](/docs/interfaces/core/tenancy)).
 
 ### Role previews
 
-The roles editor's **Preview as role** runs the resolvers too, over the previewed role's set, and tells them so with `context.preview`. The `userId` of such a call is the person previewing. A resolver that grants or withholds by the user's standing (an owner handed every permission of the plan, a screen kept for owners) must check the flag, and shape the set as for a member holding only that role:
+**Preview as role** in the roles editor runs the resolvers too, over the previewed role's set, and sets `context.preview`. The `userId` of such a call is the person previewing. A resolver that grants or withholds by the user's standing, such as handing an owner every permission of the plan or keeping a screen for owners, checks the flag and shapes the set as for an ordinary member holding only that role:
 
-```typescript
+```typescript fragment
 RegisterPermissionsResolver({
   id: "my_app.plan-limits",
   order: 100,
@@ -210,29 +222,17 @@ RegisterPermissionsResolver({
 });
 ```
 
-The DMS always passes `context`: `{}` outside a preview.
-
-Semantics the interface guarantees:
+The DMS always passes `context`, and passes `{}` outside a preview.
 
-- Resolvers run in ascending `order`, each seeing the previous one's result; equal `order` runs in registration order, which is module load order.
-- Registering an id twice replaces the earlier resolver rather than adding a second one.
-- A resolver that throws aborts the computation and fails the request. It is never skipped.
-- The registration is removed when the registering module unloads; there is no unregister call.
-- Register in `construct()` so the resolver is active before the API serves requests.
-
-`ApplyPermissionsResolvers(userId, tenantId, basePermissions, context?)` runs the pipeline, handing `context` (`{}` when omitted) to every resolver, and resolves to the effective set. Prefer `GetEffectiveUserPermissions`, which computes the base set for you and calls it.
-
-A resolver shapes a permission set. It cannot deny a surface that consults no permission set, and it cannot revoke a `defaultGranted` permission, which `HasPermission` grants after the resolvers ran. To cut a tenant off from the product entirely, register a tenant access gate instead ([Tenancy](/docs/interfaces/core/tenancy)).
-
-## Guard a Route
+## Guard a route
 
 Three decorators from `@antelopejs/interface-dms/guards` gate a route on the caller.
 
 ### `AuthUserWithPermission`
 
-`AuthUserWithPermission(target, options?)` requires an authenticated user holding the exact registered permission of `target`, which is a `Component`, a page controller class, or an `Action` ([Components](/docs/interfaces/core/components)). A child component resolves to its full positional path. `options` is the same `TenantGuardOptions` the two tenant guards take, described below.
+`AuthUserWithPermission(target, options?)` requires an authenticated user who holds the registered permission of `target`. `target` is a `Component`, a child position, a page controller class, or an `Action` ([Components](/docs/interfaces/core/components)). A child component resolves to its full positional path. `options` is a `TenantGuardOptions`.
 
-```typescript
+```typescript fragment
 import { Controller, Get } from "@antelopejs/interface-api";
 import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
 import type { User } from "@antelopejs/interface-dms/auth/db";
@@ -240,17 +240,25 @@ import { InvoicesPage } from "../pages/invoices";
 
 export class InvoiceReportController extends Controller("/api/invoices") {
   @Get("/summary")
-  async summary(@AuthUserWithPermission(InvoicesPage) _user: User) {
-    // reachable only by a caller holding the InvoicesPage permission
+  async summary(@AuthUserWithPermission(InvoicesPage) user: User) {
+    return { requestedBy: user._id };
   }
 }
 ```
 
-The guard resolves the target's permission id, loads the caller's membership in the tenant carried by the token, computes their effective permissions and calls `HasPermission`. It answers `403` when the permission is missing, and also when the token carries no tenant claim — a permission can only be granted inside a tenant. A target that carries no permission id yet passes the authentication check only. The tenant access gate runs whenever the token carries a tenant claim, including for a target with no permission id, and it runs before the permission is resolved — unless `options.bypassTenantAccessGate` is set, which skips the gate while leaving the permission check in place.
+The guard runs these steps:
+
+1. It authenticates the token. A request without a valid user fails authentication.
+2. When the token carries a tenant claim, it runs the tenant access gate, unless `options.bypassTenantAccessGate` is set.
+3. It resolves the target's permission id. A target with no permission id passes with the authenticated user.
+4. When the token carries no tenant claim, it answers `403`, because a permission is granted only inside a tenant.
+5. It loads the caller's membership in that tenant, computes the effective permissions and calls `HasPermission`. A missing permission answers `403` with `Forbidden: missing permission <id>`.
+
+`bypassTenantAccessGate` skips step 2 and keeps the permission check.
 
 ### `AuthTenantOwner` and `AuthTenantMember`
 
-Both resolve the tenant from the request's JWT `tenantId` claim and check the caller's membership in it. `AuthTenantOwner` additionally requires `isTenantOwner`. Each answers `401` without a token and `403` when the requirement is not met, and each runs the tenant access gate before returning the user.
+`AuthTenantMember(options?)` requires a member of the request's tenant. `AuthTenantOwner(options?)` also requires `isTenantOwner` on that membership. The tenant comes from the verified credential: the JWT's `tenantId` claim, or `DEFAULT_TENANT_ID` (`"default"`) when the claim is empty. Each guard answers `401` without a valid token and `403` when the requirement fails, with the body `error.tenant_member_required` or `error.tenant_owner_required`. Each then runs the tenant access gate before it returns the user.
 
 ```typescript
 import { Controller, Post } from "@antelopejs/interface-api";
@@ -265,29 +273,42 @@ export class BillingController extends Controller("/api/billing") {
   async portalSession(
     @AuthTenantOwner({ bypassTenantAccessGate: true }) user: User,
   ) {
-    // stays reachable for a tenant a gate denies
+    return { owner: user._id };
   }
 
   @Post("/usage")
   async usage(@AuthTenantMember() user: User) {
-    // any member of the request's tenant
+    return { member: user._id };
   }
 }
 ```
 
+The portal route stays reachable for a tenant that a gate denies. The usage route admits any member of the request's tenant.
+
 `TenantGuardOptions` has one field, and all three guards accept it:
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
-| `bypassTenantAccessGate` | `boolean` | Skip the tenant access gate for this route. Reserved for routes that must stay reachable when a gate denies the tenant. |
+| `bypassTenantAccessGate` | `boolean` | Skips the tenant access gate for this route. Reserved for routes that must stay reachable when a gate denies the tenant, such as billing status, a payment portal or invoices. |
+
+The two tenant guards accept `TenantRequestGuardOptions`, which extends it:
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `authenticators` | `readonly RequestAuthenticator[]` | Credential handlers this route accepts before the JWT fallback. The handler whose `recognizes(token)` returns `true` authenticates the request. Two handlers that recognize the same token answer `401`. |
+| `requireOwner` | `boolean` | Requires tenant ownership, not platform ownership. `AuthTenantOwner` sets it. |
+
+`RequestAuthenticator` comes from `@antelopejs/interface-dms/auth` ([Authentication](/docs/interfaces/auth/introduction)).
+
+`authenticateTenantRequest(ctx, options?)` runs the same check as a function and resolves to the `User`. It authenticates the credential again, and checks membership and the tenant gate, on every call, so a long-lived request can call it repeatedly. Product permissions stay the caller's job.
 
-The opt-out has two mirrors elsewhere, for the surfaces a route guard does not cover: `MenuOptions.bypassTenantAccessGate` keeps a page and its menu entry reachable ([Pages and Modules](/docs/interfaces/core/pages-and-modules)), and `TableViewOptions.bypassTenantAccessGate` covers a table view's data routes, which belong to a controller rather than to any one page.
+The opt-out has two mirrors for the surfaces a route guard does not cover. `MenuOptions.bypassTenantAccessGate` keeps a page and its menu entry reachable ([Pages and modules](/docs/interfaces/core/pages-and-modules#reach-a-page-behind-a-tenant-gate)). `TableViewOptions.bypassTenantAccessGate` covers a table view's data routes, which belong to a controller and not to any one page.
 
-A denial from a gate surfaces as a `403` whose body is the gate's `code` ([Tenancy](/docs/interfaces/core/tenancy)).
+A denial from a gate answers `403` with the gate's `code` as its body ([Tenancy](/docs/interfaces/core/tenancy)).
 
-### Guards as Properties
+### Guards as properties
 
-All three are parameter *and* property decorators. Declared as a class property, a guard gates every route on that controller:
+All three guards are parameter and property decorators. Declared as a class property, a guard gates every route on that controller:
 
 ```typescript
 import { Controller, Post } from "@antelopejs/interface-api";
@@ -299,14 +320,14 @@ export class FilesController extends Controller("/api/files") {
   declare user: User;
 
   @Post("/presign")
-  async presign() {
-    // the guard already ran, whether or not this handler reads `this.user`
+  async presign(): Promise<{ ok: true }> {
+    return { ok: true };
   }
 }
 ```
 
-A property provider runs on every request to a route of the controller, independently of whether the handler body reads the property. That is what makes the property form a guard rather than a convenience: removing the read does not remove the check.
+The property provider runs on every request to a route of the controller, whether or not the handler reads the property. The `presign` route above never reads `this.user`, and the guard still runs. That makes the property form a guard: removing the read does not remove the check.
 
-## Next Steps
+## Next steps
 
 [Tenancy](/docs/interfaces/core/tenancy) covers the tenant the guards resolve, the roles the permission sets come from, and the access gates.