@antelopejs/interface-dms 0.10.4 → 0.13.0

package/dist/watch-actions.d.ts

@@ -13,7 +13,7 @@ export interface WatchAction {
     component: string;
     event: string;
     functionId: string;
-    params?: Record<string, unknown>;
+    params?: object;
     onParam?: WatchActionCondition | WatchActionCondition[];
     requirePermission?: string;
 }

package/docs/1.core/1.introduction.md

@@ -1,55 +1,68 @@
 ---
 title: "Introduction"
 description: "The core contract of the DMS: pages and modules, components, permissions, tenancy, invites, hooks, realtime, quick actions and layout banners."
+mode: explanation
 ---
 
-# Introduction
-
 ## Overview
 
-The root export of `@antelopejs/interface-dms` and the subpaths listed below are the core contract of the AntelopeJS DMS. It encodes one inversion: the backend declares the screen, as serializable data. A page is a controller class, its components are static fields holding builders, and the page's layout route returns the description a shared frontend renders. Adding an admin screen is a backend change.
+The root export of `@antelopejs/interface-dms` and the subpaths listed below are the core contract of the AntelopeJS DMS. The contract rests on one inversion. The backend declares the screen as serializable data. A page is a controller class, its components are static fields that hold builders, and the page's layout route returns the description that a shared frontend renders. To add an admin screen, you change the backend.
 
-Around that core the interface carries what an admin backend needs to be more than a renderer: hierarchical permissions derived from the page tree, multi-tenant data access scoped by the model handle, lifecycle hooks, realtime topics, and command-palette entries.
+Around that core, the interface carries what an admin backend needs beyond rendering. It derives hierarchical permissions from the page tree and scopes multi-tenant data access through the model handle. It also dispatches lifecycle hooks, carries realtime topics, and adds entries to the command palette.
 
-Everything here is imported from a subpath of `@antelopejs/interface-dms`. Two other domains of the same package complete the picture and are referenced throughout these pages: [Auth](/docs/interfaces/auth/introduction) (`/auth`) for authentication and the `User` table, and [Base](/docs/interfaces/base/introduction) (`/base`) for the concrete component vocabulary (`Form`, `TableView`, `Grid`, the chart family) built on the component types documented here.
+You import everything here from a subpath of `@antelopejs/interface-dms`. Two other domains of the same package complete the picture, and these pages refer to them throughout. [Auth](/docs/interfaces/auth/introduction) (`/auth`) covers authentication and the `User` table. [Base](/docs/interfaces/base/introduction) (`/base`) holds the concrete component vocabulary (`Form`, `TableView`, `Grid`, the chart family), built on the component types documented here.
 
-## Key Features
+## What the core provides
 
-- **Pages as controllers** — `PageController` builds a controller class bound to a URL; `@RegisterPage()` records it, registers its permissions, and serves its layout.
-- **Components that serialize** — a `ComponentBuilder` produces data, not a live component, so one frontend renders every module's screens.
-- **Categories and modules** — a sidebar tree of nested categories, plus modules that own a whole branch under `/modules`.
-- **Dynamic navigation** — providers that resolve extra menu entries per request, so one page can back an entry per project or workspace.
-- **Page extensions** — inject components into a page owned by another module, permissioned in that page's own tree.
-- **Hierarchical permissions** — ids derived from page, component and action, with a base set from roles and an effective set shaped by registered resolvers.
-- **Route guards** — permission, tenant-member and tenant-owner decorators usable as parameter or property decorators.
-- **Tenancy in the handle** — per-tenant schemas and model handles bound to one tenant, rather than a tenant column filtered on every query.
-- **Tenant access gates** — one binary check that denies a tenant at every authorization surface at once.
-- **Invites** — one call that either grants membership to an existing user or issues a token-bearing invite.
-- **Lifecycle hooks** — typed events for tenants, members, invites and registrations, dispatched either to notify or to collect contributions.
-- **Realtime topics** — bind a topic to a page, publish to whoever is on it, and subscribe from the backend to what others publish.
-- **Quick actions** — contribute grouped, permission-gated entries to the command palette.
+- **Pages as controllers.** `PageController` builds a controller class bound to a URL. `@RegisterPage()` records it, registers its permissions, and serves its layout.
+- **Components that serialize.** A `ComponentBuilder` produces data, not a live component, so one frontend renders the screens of every module.
+- **Categories and modules.** Nested categories form a sidebar tree, and a module owns a whole branch under `/modules`.
+- **Dynamic navigation.** Providers resolve extra menu entries for each request, so one page can back an entry per project or workspace.
+- **Page extensions.** A module injects components into a page that another module owns. The injected components get their permissions in that page's own tree.
+- **Hierarchical permissions.** Permission ids derive from the page, the component and the action. Roles grant a base set, and registered resolvers shape it into the effective set.
+- **Route guards.** The permission, tenant-member and tenant-owner decorators work as parameter decorators or as property decorators.
+- **Tenancy in the handle.** Each tenant has its own schemas, and a model handle is bound to one tenant. No query filters a tenant column.
+- **Tenant access gates.** One binary check denies a tenant at every authorization surface at once.
+- **Invites.** One call either grants membership to an existing user or issues an invite that carries a token.
+- **Lifecycle hooks.** Typed events for tenants, members, invites and registrations. The DMS dispatches each one either to notify handlers or to collect their contributions.
+- **Realtime topics.** You bind a topic to a page, publish to the sessions on that page, and subscribe from the backend to what others publish.
+- **Quick actions.** You contribute grouped entries to the command palette, each gated by a permission.
 
 ## Dependencies
 
 This interface relies on the following AntelopeJS packages:
 
-- [@antelopejs/interface-api](https://github.com/AntelopeJS/interface-api) - Controllers, route registration and request context.
-- [@antelopejs/interface-auth](https://github.com/AntelopeJS/interface-auth) - The authentication decorator machinery the guards build on.
-- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - Interface functions, registering proxies and decorator helpers.
-- [@antelopejs/interface-database-decorators](https://github.com/AntelopeJS/interface-database-decorators) - Table definitions, data models and model injection.
-- [@antelopejs/interface-data-api](https://github.com/AntelopeJS/interface-data-api) - Used by the `/data-controllers` subpath for the built-in members and roles controllers.
+- [`@antelopejs/interface-api`](https://github.com/AntelopeJS/interface-api): Controllers, route registration and the request context.
+- [`@antelopejs/interface-api-util`](https://github.com/AntelopeJS/interface-api-util): The `assert` helper that rejects a request with an HTTP status, used by invite resolution, tenant lifecycle admission and the table view routes.
+- [`@antelopejs/interface-core`](https://github.com/AntelopeJS/interface-core): Interface functions, registering proxies and decorator helpers.
+- [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database): Query value proxies and the `Schema` handle, used by the tenancy models and tenant provisioning.
+- [`@antelopejs/interface-database-decorators`](https://github.com/AntelopeJS/interface-database-decorators): Table definitions, data models and model injection.
+- [`@antelopejs/interface-data-api`](https://github.com/AntelopeJS/interface-data-api): The data controllers behind the table views of `/base` and the built-in members and roles controllers of `/data-controllers`.
+- [`@antelopejs/interface-file-storage`](https://github.com/AntelopeJS/interface-file-storage): File metadata and upload constraints, used by `/attachments` and the file data types.
+
+The route guards build on the [Auth](/docs/interfaces/auth/introduction) domain of this same package, not on a separate package.
 
-## Quick Start
+## Quick start
 
-Declare the application's table and model first. `BookModel` is not a DMS export; this example defines it with the stock flag used by the KPI query.
+The following file declares the application's table and model, a category, a page with a component, and the route that the component fetches from. `Book` and `BookModel` are not DMS exports. The example defines them with the stock flag that the KPI query reads.
 
-```typescript [db.ts]
+```typescript [books-page.ts]
+import { Get } from "@antelopejs/interface-api";
 import {
   BasicDataModel,
   Field,
+  GetModel,
   RegisterTable,
   Table,
 } from "@antelopejs/interface-database-decorators";
+import {
+  Category,
+  PageController,
+  RegisterPage,
+  pageRoutePath,
+  pagesCategory,
+} from "@antelopejs/interface-dms/page";
+import { KpiCard } from "@antelopejs/interface-dms/base";
 
 export const CATALOG_SCHEMA = "example_catalog";
 
@@ -61,21 +74,6 @@ export class Book extends Table {
 }
 
 export class BookModel extends BasicDataModel(Book, "books") {}
-```
-
-Then declare a category, a page with a component, and the route that component fetches from:
-
-```typescript [books-page.ts]
-import { Get } from "@antelopejs/interface-api";
-import { GetModel } from "@antelopejs/interface-database-decorators";
-import {
-  Category,
-  PageController,
-  RegisterPage,
-  pagesCategory,
-} from "@antelopejs/interface-dms/page";
-import { KpiCard } from "@antelopejs/interface-dms/base";
-import { BookModel } from "./db";
 
 export const catalog = Category("catalog", {
   displayName: "Catalog",
@@ -94,7 +92,7 @@ export class BooksPage extends PageController("books", {
   static inStockKpi = KpiCard({
     title: "In stock",
     icon: "i-ph-package",
-    fetchUrl: "/catalog/books/stats/in-stock",
+    fetchUrl: pageRoutePath("/catalog/books", "/stats/in-stock"),
     valueFormat: "number",
   });
 
@@ -107,63 +105,70 @@ export class BooksPage extends PageController("books", {
 }
 ```
 
-Import the page and register the schema from your module's entry file, merging this into an existing `start()` if necessary:
+Import the page and register the schema from the entry file of your module. If the module already has a `start()`, add these lines to it.
 
-```typescript [index.ts]
+```typescript fragment [index.ts]
 import "./books-page";
 import { RegisterSchema } from "@antelopejs/interface-database-decorators";
-import { CATALOG_SCHEMA } from "./db";
+import { CATALOG_SCHEMA } from "./books-page";
 
 export async function start(): Promise<void> {
   await RegisterSchema(CATALOG_SCHEMA);
 }
 ```
 
-The page resolves at `/catalog/books` and its layout at `/dms/pages/catalog/books/pagelayout`: a page controller's routes live under `/dms/pages` (`pageRoutePath`), a prefix the frontend server proxies to the backend, since the page's own path is the page. Its permission id is the chain of ids down from the root category — `pages.catalog.books` — with `pages.catalog.books.inStockKpi` registered underneath it.
+The page resolves at `/catalog/books`. Its layout resolves at `/dms/pages/catalog/books/pagelayout`, and its `/stats/in-stock` route at `/dms/pages/catalog/books/stats/in-stock`. The routes of a page controller live under the `/dms/pages` prefix (`PAGE_ROUTE_PREFIX`), because the frontend server answers the page's own path with the page and proxies only `/api` and `/dms` to the backend. `pageRoutePath` builds the path under that prefix, so the component's `fetchUrl` reaches the route.
+
+The page's permission id is the chain of ids down from the root category, `pages.catalog.books`. The DMS registers `pages.catalog.books.inStockKpi` underneath it.
 
-## Subpath Map
+## Subpath map
 
 | Subpath | Contains | Documented in |
 | ------- | -------- | ------------- |
-| `/page` | Pages, categories, modules, layouts, page extensions, dynamic menus, frontend modules | [Pages and Modules](/docs/interfaces/core/pages-and-modules) |
+| `/page` | Pages, categories, layouts, page extensions | [Pages and modules](/docs/interfaces/core/pages-and-modules) |
+| `/page` | Modules, the modules catalog, dynamic menus | [Modules and dynamic menus](/docs/interfaces/core/modules-and-dynamic-menus) |
+| `/page` | Frontend modules | [Frontend modules and request helpers](/docs/interfaces/core/frontend-modules-and-request-helpers#ship-a-frontend-module) |
 | `/component` | `Component`, `ComponentBuilder`, actions, watches | [Components](/docs/interfaces/core/components) |
 | `/component-slots` | `RegisterComponentSlot`, `ComponentSlotResolver`, `SlotOptions` | [Components](/docs/interfaces/core/components#registercomponentslot) |
-| `/attachments` | `SaveComponentFiles` and its request, field and result types | [Pages and Modules](/docs/interfaces/core/pages-and-modules#savecomponentfiles) |
+| `/attachments` | `SaveComponentFiles` and its request, field and result types | [Frontend modules and request helpers](/docs/interfaces/core/frontend-modules-and-request-helpers#savecomponentfiles) |
 | `/permission-gate` | Shared `PermissionGate` fields | [Base types](/docs/interfaces/base/types#permissiongate) |
 | `/permissions` | The permission registry and the permission computation | [Permissions](/docs/interfaces/core/permissions) |
-| `/permissions-resolver` | Registering and running permission resolvers | [Permissions](/docs/interfaces/core/permissions) |
-| `/guards` | `AuthUserWithPermission`, `AuthTenantOwner`, `AuthTenantMember` | [Permissions](/docs/interfaces/core/permissions) |
-| `/constants` | Schema names and the default tenant | [Tenancy](/docs/interfaces/core/tenancy) |
-| `/db` | The `Tenant`, `TenantMember`, `Role` and `UserInvite` tables and models | [Tenancy](/docs/interfaces/core/tenancy), [Invites](/docs/interfaces/core/invites) |
-| `/request-tenant` | `getRequestTenantId` | [Tenancy](/docs/interfaces/core/tenancy) |
-| `/tenant-scoped-model` | `TenantScopedModel` | [Tenancy](/docs/interfaces/core/tenancy) |
-| `/tenant-access` | Tenant access gates | [Tenancy](/docs/interfaces/core/tenancy) |
-| `/tenant-ownership` | Membership and ownership writes | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/permissions-resolver` | Registering and running permission resolvers | [Permissions](/docs/interfaces/core/permissions#reshape-the-effective-set) |
+| `/guards` | `AuthUserWithPermission`, `AuthTenantOwner`, `AuthTenantMember` | [Permissions](/docs/interfaces/core/permissions#guard-a-route) |
+| `/constants` | Schema names and the default tenant | [Tenancy](/docs/interfaces/core/tenancy#constants) |
+| `/db` | The `Tenant`, `TenantMember`, `Role` and `UserInvite` tables and models | [Tenancy](/docs/interfaces/core/tenancy#the-tenancy-tables), [Invites](/docs/interfaces/core/invites#the-userinvite-table) |
+| `/request-tenant` | `getRequestTenantId` | [Tenancy](/docs/interfaces/core/tenancy#resolve-the-requests-tenant) |
+| `/tenant-scoped-model` | `TenantScopedModel` | [Tenancy](/docs/interfaces/core/tenancy#scope-a-model-to-the-requests-tenant) |
+| `/tenant-access` | Tenant access gates | [Tenancy](/docs/interfaces/core/tenancy#tenant-access-gates) |
+| `/tenant-ownership` | Membership and ownership writes | [Tenancy](/docs/interfaces/core/tenancy#memberships-and-ownership) |
 | `/tenant-lifecycle` | Producer admission and closure before tenant deletion | [Tenancy](/docs/interfaces/core/tenancy#tenant-lifecycle-admission) |
-| `/data-controllers` | The built-in members and roles data controllers | [Tenancy](/docs/interfaces/core/tenancy) |
+| `/data-controllers` | The built-in members and roles data controllers | [Tenancy](/docs/interfaces/core/tenancy#built-in-data-controllers) |
 | `/invites` | Inviting a user into a tenant | [Invites](/docs/interfaces/core/invites) |
 | `/invite-extensions` | Invite form contributions, callbacks and availability | [Invites](/docs/interfaces/core/invites#registerinviteextension) |
 | `/invite-resolution` | Durable terminal decisions and retryable effects | [Invites](/docs/interfaces/core/invites#durable-invite-resolution) |
 | `/hooks` | The `Hook` enum, handlers and dispatch | [Hooks](/docs/interfaces/core/hooks) |
-| `/tenant-export` | The tenant data export archive, contribution and manifest types, re-exported from `/hooks` | [Hooks](/docs/interfaces/core/hooks) |
+| `/tenant-export` | The tenant data export archive, contribution and manifest types, re-exported from `/hooks` | [Tenant data export](/docs/interfaces/core/tenant-data-export) |
 | `/realtime` | Page topics, publishing and backend subscription | [Realtime](/docs/interfaces/core/realtime) |
-| `/quick-actions` | Command-palette entries | [Quick Actions](/docs/interfaces/core/quick-actions) |
-| `/layout-banners` | Global banners under the dashboard header | [Layout Banners](/docs/interfaces/core/layout-banners) |
-| `/uploads` | Signed upload tokens for the file and image fields of a serialized component | [Pages and Modules](/docs/interfaces/core/pages-and-modules) |
-| `/types` | `MaybePromise`, the one shared type alias | [Pages and Modules](/docs/interfaces/core/pages-and-modules) |
-| `/api-base-url`, `/client-base-url` | `GetApiBaseUrl`, `GetClientBaseUrl`: the public origins of the API and the dashboard | [Pages and Modules](/docs/interfaces/core/pages-and-modules#public-urls) |
-| `/client-ip` | `getClientIp`, `ResolveClientIp`: a request's client address behind the trusted proxies | [Pages and Modules](/docs/interfaces/core/pages-and-modules#client-address) |
+| `/quick-actions` | Command-palette entries | [Quick actions](/docs/interfaces/core/quick-actions) |
+| `/layout-banners` | Global banners under the dashboard header | [Layout banners](/docs/interfaces/core/layout-banners) |
+| `/uploads` | Signed upload tokens for the file and image fields of a serialized component | [Frontend modules and request helpers](/docs/interfaces/core/frontend-modules-and-request-helpers#stamp-upload-tokens) |
+| `/types` | `MaybePromise`, the one shared type alias | [Pages and modules](/docs/interfaces/core/pages-and-modules#page-setup-functions) |
+| `/api-base-url`, `/client-base-url` | `GetApiBaseUrl` and `GetClientBaseUrl`, the public origins of the API and the dashboard | [Frontend modules and request helpers](/docs/interfaces/core/frontend-modules-and-request-helpers#public-urls) |
+| `/client-ip` | `getClientIp` and `ResolveClientIp`, the client address of a request behind the trusted proxies | [Frontend modules and request helpers](/docs/interfaces/core/frontend-modules-and-request-helpers#client-address) |
 
 Paths under `internal/`, symbols tagged `@internal`, and `internal` namespaces are implementation wiring, not supported consumer APIs. The wildcard export does not change that boundary.
 
-## Documentation Sections
-
-- [Pages and Modules](/docs/interfaces/core/pages-and-modules) - Declare pages, group them into categories, own a branch of the sidebar with a module, and extend a page from another one
-- [Components](/docs/interfaces/core/components) - Build serializable components, declare actions and watches
-- [Permissions](/docs/interfaces/core/permissions) - Register permissions, compute a user's effective set, guard routes
-- [Tenancy](/docs/interfaces/core/tenancy) - Schemas, the tenancy tables, tenant-scoped models and access gates
-- [Invites](/docs/interfaces/core/invites) - Bring a user into a tenant by email
-- [Hooks](/docs/interfaces/core/hooks) - React to platform events and contribute to the tenant data export
-- [Realtime](/docs/interfaces/core/realtime) - Bind topics to pages, publish messages and subscribe to them
-- [Quick Actions](/docs/interfaces/core/quick-actions) - Contribute entries to the command palette
-- [Layout Banners](/docs/interfaces/core/layout-banners) - Show a global banner under the dashboard header, decided per request
+## Pages in this section
+
+- [Pages and modules](/docs/interfaces/core/pages-and-modules): Declare pages, group them into categories, and extend a page from another module.
+- [Modules and dynamic menus](/docs/interfaces/core/modules-and-dynamic-menus): Own a branch of the sidebar with a module, report its state on the modules catalog, and add menu entries resolved per request.
+- [Frontend modules and request helpers](/docs/interfaces/core/frontend-modules-and-request-helpers): Ship a frontend module, sign upload fields, build public links, read the client address, and save native files.
+- [Components](/docs/interfaces/core/components): Build serializable components, and declare actions and watches.
+- [Permissions](/docs/interfaces/core/permissions): Register permissions, compute the effective set of a user, and guard routes.
+- [Tenancy](/docs/interfaces/core/tenancy): Schemas, the tenancy tables, tenant-scoped models and access gates.
+- [Invites](/docs/interfaces/core/invites): Bring a user into a tenant by email.
+- [Hooks](/docs/interfaces/core/hooks): React to platform events.
+- [Tenant data export](/docs/interfaces/core/tenant-data-export): Contribute the data of a module to the tenant data export.
+- [Realtime](/docs/interfaces/core/realtime): Bind topics to pages, publish messages and subscribe to them.
+- [Quick actions](/docs/interfaces/core/quick-actions): Contribute entries to the command palette.
+- [Layout banners](/docs/interfaces/core/layout-banners): Show a global banner under the dashboard header, decided per request.

package/docs/1.core/10.layout-banners.md

@@ -1,23 +1,20 @@
 ---
-title: "Layout Banners"
-description: "A layout banner is a global message the backend adds under the dashboard header: a colored strip carrying a line of text and its link buttons, or a component of your frontend layer."
+title: "Layout banners"
+description: "A layout banner is a global message the backend adds under the dashboard header: a colored strip with a line of text and its link buttons, or a component of your frontend layer."
+mode: reference
 ---
 
-# Layout Banners
+A layout banner is a global message that the backend adds under the dashboard header. It is a colored strip with a line of text and its link buttons, or a component of your frontend layer. A banner renders on the pages its [`scope`](#scope) selects. By default those are the application's pages, without the module area under `/modules`. Banners stack by `order`.
 
-## Overview
+The server decides per request whether a banner shows, while it builds the site layout. The answer is part of the server-rendered page, so a banner never flashes in or out after hydration.
 
-A layout banner is a global message the backend adds under the dashboard header: a colored strip carrying a line of text and its link buttons, or a component of your frontend layer. It renders on the pages its [`scope`](#scope) selects — by default the application's pages, leaving the module area under `/modules` out — and banners stack by `order`.
+Everything on this page lives in `@antelopejs/interface-dms/layout-banners`.
 
-Whether a banner shows is decided per request, on the server, while the site layout is built. The answer is part of the server-rendered page, so a banner never flashes in or out after hydration.
+## Register a banner
 
-Everything lives in `@antelopejs/interface-dms/layout-banners`.
+`RegisterLayoutBanner(info)` registers the banner and returns a function that removes it. Register at import time, next to the state the banner reports on. The DMS drops the registration when your module stops.
 
-## Register a Banner
-
-`RegisterLayoutBanner(info)` registers the banner and returns a function removing it. Register at import time, next to the state the banner reports on; the registration is dropped automatically when your module stops.
-
-```typescript
+```typescript fragment
 import {
   LayoutBannerVariant,
   RegisterLayoutBanner,
@@ -34,9 +31,11 @@ RegisterLayoutBanner({
 });
 ```
 
-The text can be a [composed text](/docs/components/block-fundamentals#composed-texts) — an i18n key and the raw values it names, written in the reader's language — and `actions` adds link buttons after it, the last one leading:
+The text can be a [composed text](/docs/components/block-fundamentals#composed-texts). A composed text is an i18n key and the raw values it names, written in the reader's language. `actions` adds link buttons after the text, and the last button is the main action:
 
 ```typescript
+import { LayoutBannerVariant, RegisterLayoutBanner } from "@antelopejs/interface-dms/layout-banners";
+
 RegisterLayoutBanner({
   key: "my-app:maintenance",
   variant: LayoutBannerVariant.WARNING,
@@ -48,11 +47,13 @@ RegisterLayoutBanner({
 });
 ```
 
-## Resolve the Content per Request
+A banner with no `text`, no `component` and no `resolve` is skipped, and the server logs a warning once for it.
 
-When the message names the state that makes the banner show — the invoice that failed, its amount, the day the workspace is suspended — `resolve(context)` builds the text and the buttons for each request, or answers `undefined` to hide the banner. It replaces `visible`: one read decides both.
+## Resolve the content per request
 
-```typescript
+Some messages name the state that makes the banner show, such as the invoice that failed, its amount, or the day the workspace is suspended. For those, `resolve(context)` builds the text and the buttons for each request, or answers `undefined` to hide the banner. It replaces `visible`, so one read decides both.
+
+```typescript fragment
 RegisterLayoutBanner({
   key: "saas:past-due",
   variant: LayoutBannerVariant.ERROR,
@@ -74,13 +75,15 @@ RegisterLayoutBanner({
 });
 ```
 
-The server sends the raw values; the browser formats them for the reader's language, time zone and clock, so the resolver never formats text. A banner like this one needs no frontend component.
+The server sends the raw values, and the browser formats them for the reader's language, time zone and clock. The resolver never formats text. A banner like this one needs no frontend component.
 
-## Mount a Component
+## Mount a component
 
-A banner can mount a global component of your [frontend layer](/docs/building/frontend-layer) instead of a text. The DMS still draws the chrome around it — color, icon, close button and ARIA role — and passes `props` to the component:
+A banner can mount a global component of your [frontend layer](/docs/building/frontend-layer) in place of a text. The DMS still draws the chrome around it (the color, the icon, the close button and the ARIA role) and passes `props` to the component:
 
 ```typescript
+import { LayoutBannerVariant, RegisterLayoutBanner } from "@antelopejs/interface-dms/layout-banners";
+
 RegisterLayoutBanner({
   key: "my-app:trial",
   variant: LayoutBannerVariant.INFO,
@@ -90,15 +93,15 @@ RegisterLayoutBanner({
 });
 ```
 
-Re-registering a `key` replaces the banner.
+A second registration with the same `key` replaces the banner.
 
 ## Scope
 
-A banner is about the application being built — eighteen overdue invoices, a stock alert — so by default it shows on the application's pages only, and stays out of the **module area**: every page under `MODULE_URL_PREFIX` (`/modules`), that is the modules page, the module store and each module's own back-office pages. A banner about the workspace itself, which must follow the user into a module — billing past due, a suspended workspace, a maintenance window — sets `scope: LayoutBannerScope.EVERYWHERE`.
+By default, a banner shows on the application's pages only and stays out of the **module area**. A banner about the application being built, such as eighteen overdue invoices or a stock alert, has no place there. The module area is every page under `MODULE_URL_PREFIX` (`/modules`): the modules page, the module store and the back-office pages of each module. A banner about the workspace itself must follow the user into a module. Billing past due, a suspended workspace and a maintenance window are examples. Such a banner sets `scope: LayoutBannerScope.EVERYWHERE`.
 
-`scope` is a plain option of the banner declaration, the same on the three kinds of banner — a text banner, a resolved banner and a component banner — with the same values and the same `"app"` default:
+`scope` is a plain option of the banner declaration. It is the same on the three kinds of banner (a text banner, a resolved banner and a component banner), with the same values and the same `"app"` default:
 
-```typescript
+```typescript fragment
 import {
   LayoutBannerScope,
   LayoutBannerVariant,
@@ -140,49 +143,58 @@ RegisterLayoutBanner({
 | `"everywhere"` | Every page of the dashboard layout, module area included. |
 | `"modules"` | The module area only. |
 
-The scope is decided by the page, not by the request: the site layout is fetched once and shared by every page, so each banner carries its scope and the dashboard applies it against the current route — in the server-rendered page, so a banner never flashes in or out after hydration, and again on each client-side navigation, so moving in or out of `/modules` adds or removes it without re-fetching anything. A banner's `visible` or `resolve` therefore does not see the route; the scope is the only per-page filter. A dismissal is per key, whatever page the banner was closed on.
+The page decides the scope, not the request. The client fetches the site layout once and every page shares it, so each banner carries its scope, and the dashboard applies the scope against the current route. The dashboard applies it in the server-rendered page, so a banner never flashes in or out after hydration. It applies it again on each client-side navigation, so moving in or out of `/modules` adds or removes the banner without a new fetch. A banner's `visible` or `resolve` does not see the route, and the scope is the only filter per page. The server falls back to `"app"` for a `scope` value outside the three listed.
+
+A dismissal applies to the key, whatever page the user closed the banner on.
 
 ::warning
-**Behaviour change.** Before `scope` existed every banner showed on every page, module area included. A banner registered without `scope` now stays out of `/modules`: give `scope: LayoutBannerScope.EVERYWHERE` to the ones reporting a workspace-wide state.
+A banner registered without `scope` stays out of `/modules`. Give `scope: LayoutBannerScope.EVERYWHERE` to the banners that report a state of the whole workspace.
 ::
 
 ## `LayoutBannerInfo`
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `key` | `string` | Unique across the deployment. Required. Also what a dismissal remembers: give a banner a new key when it must show again to users who dismissed it. |
-| `variant` | `LayoutBannerVariant` | `"info"`, `"warning"` or `"error"`. Required. Picks the color, the default icon and the ARIA role. |
-| `text` | `string \| ComposedText` | The message. A `$`-prefixed value resolves as an i18n key; a `ComposedText` is written in the reader's language. Exclusive with `component` and `resolve`; one of the three is required. |
-| `actions` | `BlockLinkAction[]` | Link buttons after `text`, the last one leading. Labels follow the `$` convention. |
-| `component` | `string` | Name of a global component rendered as the banner's content. Exclusive with `text` and `resolve`. |
-| `props` | `Record<string, unknown>` | Props passed to `component`. Must be serializable. |
-| `order` | `number` | Stack order, ascending from the top. Defaults to `0`; ties keep the registration order. |
-| `icon` | `string` | Leading icon. Defaults to one matching the variant. |
+| `key` | `string` | Required. Unique across the deployment. A dismissal also remembers the key, so give a banner a new key when it must show again to users who dismissed it. |
+| `variant` | `LayoutBannerVariant` | Required. `"info"`, `"warning"` or `"error"`. Picks the color, the default icon and the ARIA role. |
+| `text` | `string \| ComposedText` | The message. A value with the `$` prefix resolves as an i18n key. A `ComposedText` is written in the reader's language. Exclusive with `component` and `resolve`, and one of the three is required. |
+| `actions` | `BlockLinkAction[]` | Link buttons after `text`. The last one is the main action. Labels follow the `$` convention. |
+| `component` | `string` | The name of a global component rendered as the banner's content. Exclusive with `text` and `resolve`. |
+| `props` | `{ readonly [prop: string]: JsonValue }` | Props passed to `component`, as JSON. |
+| `order` | `number` | Stack order, ascending from the top. Defaults to `0`. Ties keep the registration order. |
+| `icon` | `string` | Leading icon. Defaults to one that matches the variant. |
 | `dismissible` | `boolean` | Whether the user can close the banner. Defaults to `false`. |
-| `scope` | `LayoutBannerScope` | `"app"`, `"everywhere"` or `"modules"`: the pages the banner shows on. Defaults to `"app"`, every page outside `/modules`. See [Scope](#scope). |
-| `visible` | `LayoutBannerVisibility` | Decides per request whether a `text` or `component` banner shows. Absent means always. |
-| `resolve` | `LayoutBannerResolver` | Builds `{ text, actions? }` per request, or `undefined` to hide the banner. Exclusive with `text`, `component` and `visible`. |
+| `scope` | `LayoutBannerScope` | `"app"`, `"everywhere"` or `"modules"`, the pages the banner shows on. Defaults to `"app"`, every page outside `/modules`. See [Scope](#scope). |
+| `visible` | `LayoutBannerVisibility` | Decides per request whether a `text` or `component` banner shows. Without it, the banner always shows. |
+| `resolve` | `LayoutBannerResolver` | Builds `{ text, actions? }` per request, or answers `undefined` to hide the banner. Exclusive with `text`, `component` and `visible`. |
 
 ## Visibility
 
-`visible(context)` returns a boolean, or a promise of one; `resolve(context)` returns a `LayoutBannerContent` (`{ text, actions? }`), `undefined`, or a promise of either. They run server-side for every site layout request, all resolvers together, so the request waits for the slowest one rather than for their sum. A resolver that throws or does not answer within two seconds hides its banner for that request, as does a `visible` returning anything but `true` or a `resolve` answering no text; the other banners are unaffected.
+`visible(context)` returns a boolean, or a promise of one. `resolve(context)` returns a `LayoutBannerContent` (`{ text, actions? }`), `undefined`, or a promise of either. The server runs them for every site layout request, all resolvers at once, so the request waits for the slowest one and not for their sum. A banner is hidden for that request in four cases:
+
+- Its resolver throws.
+- Its resolver does not answer within two seconds.
+- Its `visible` returns anything other than `true`.
+- Its `resolve` answers no text.
+
+The other banners are unaffected.
 
 ### `LayoutBannerContext`
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `user` | `User \| undefined` | The caller; `undefined` for an unauthenticated request. |
+| `user` | `User \| undefined` | The caller. `undefined` for an unauthenticated request. |
 | `tenantId` | `string` | The tenant the site layout is built for. |
-| `permissions` | `Set<string>` | The caller's effective permissions in the tenant. |
-| `isOwner` | `boolean` | Whether the caller holds the wildcard permission. |
-| `isTenantAccessDenied` | `boolean` | Whether a [tenant access gate](/docs/interfaces/core/tenancy) currently refuses the caller. |
+| `permissions` | `Set<string>` | The caller's effective permissions in the tenant, with no tenant access gate applied. |
+| `isOwner` | `boolean` | Whether the caller holds the wildcard permission, with no tenant access gate applied. |
+| `isTenantAccessDenied` | `boolean` | Whether a [tenant access gate](/docs/interfaces/core/tenancy#tenant-access-gates) refuses the caller. |
 
-Unlike product surfaces, a banner reads the permissions a denying access gate would hide: telling a suspended or past-due workspace why is exactly what a banner is for. Check `isTenantAccessDenied` when the two situations call for different banners.
+The other product surfaces lose the permissions that a denying access gate hides, but a banner still reads them. A banner is how a suspended or past-due workspace learns why. Check `isTenantAccessDenied` when the two situations call for different banners.
 
-The resolvers run whenever a client fetches its site layout — on a full page load and after a menu invalidation. When the state a resolver reads changes, call `NotifyMenuChanged(tenantId)` from `@antelopejs/interface-dms/page` so the connected clients of that tenant re-fetch it and the banner appears or goes without a reload.
+The resolvers run each time a client fetches its site layout, which happens on a full page load and after a menu invalidation. When the state a resolver reads changes, call `NotifyMenuChanged(tenantId)` from `@antelopejs/interface-dms/page`. The connected clients of that tenant then fetch the site layout again, and the banner appears or goes away without a reload.
 
 ## Rendering
 
-Banners render under the header of the dashboard layout, on the pages their scope covers, full width, in `order`, a text banner's `actions` on its right. Each one is its own live region: `error` banners carry `role="alert"`, `info` and `warning` banners `role="status"`.
+Banners render under the header of the dashboard layout, on the pages their scope covers, at full width, in `order`. The `actions` of a text banner sit on its right. Each banner is its own live region. An `error` banner carries `role="alert"`, and an `info` or `warning` banner carries `role="status"`.
 
-A dismissible banner shows a close button. The dismissal lasts for the browser session and is kept in the `dms-dismissed-banners` cookie, which the server reads too, so a dismissed banner is already absent from the server-rendered page. A banner that is not dismissible ignores any dismissal recorded under its key.
+A dismissible banner shows a close button. The dismissal lasts for the browser session and is stored in the `dms-dismissed-banners` cookie. The server reads that cookie too, so a dismissed banner is already absent from the server-rendered page. A banner that is not dismissible ignores any dismissal recorded under its key.