@antelopejs/interface-dms 0.7.4 → 0.9.0

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

@@ -7,7 +7,7 @@ description: "A layout banner is a global message the backend adds under the das
 
 ## Overview
 
-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 every page of the dashboard layout — tenant pages and the module back-office pages under `/modules` alike — and banners stack by `order`.
+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`.
 
 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.
 
@@ -92,6 +92,60 @@ RegisterLayoutBanner({
 
 Re-registering a `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`.
+
+`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:
+
+```typescript
+import {
+  LayoutBannerScope,
+  LayoutBannerVariant,
+  RegisterLayoutBanner,
+} from "@antelopejs/interface-dms/layout-banners";
+
+// A text banner about the application: the default scope, written out.
+RegisterLayoutBanner({
+  key: "my-app:overdue-invoices",
+  variant: LayoutBannerVariant.WARNING,
+  scope: LayoutBannerScope.APP,
+  text: "$my_app.banners.overdue_invoices",
+  actions: [{ label: "$my_app.banners.review", to: "/finance/invoices" }],
+  visible: async ({ tenantId }) => hasOverdueInvoices(tenantId),
+});
+
+// A resolved banner about the workspace: it follows the user into /modules.
+RegisterLayoutBanner({
+  key: "saas:past-due",
+  variant: LayoutBannerVariant.ERROR,
+  scope: LayoutBannerScope.EVERYWHERE,
+  resolve: pastDueContent,
+});
+
+// A component banner about the workspace, also shown inside /modules.
+RegisterLayoutBanner({
+  key: "my-app:maintenance",
+  variant: LayoutBannerVariant.INFO,
+  scope: LayoutBannerScope.EVERYWHERE,
+  component: "MyAppMaintenanceBanner",
+  props: { statusUrl: "https://status.example.com" },
+  visible: async () => isMaintenanceScheduled(),
+});
+```
+
+| `scope` | Shows on |
+| ------- | -------- |
+| `"app"` (default) | Every page outside the module area. |
+| `"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.
+
+::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.
+::
+
 ## `LayoutBannerInfo`
 
 | Field | Type | Description |
@@ -105,6 +159,7 @@ Re-registering a `key` replaces the banner.
 | `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. |
 | `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`. |
 
@@ -128,6 +183,6 @@ The resolvers run whenever a client fetches its site layout — on a full page l
 
 ## Rendering
 
-Banners render under the header of the dashboard layout, 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, 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"`.
 
 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.

package/docs/1.core/2.pages-and-modules.md

@@ -62,6 +62,7 @@ The third argument is the page layout, a `ComponentInfo` produced by a layout bu
 | `order` | `number` | Sort order among siblings. |
 | `icon` | `string` | Icon name. |
 | `hidden` | `boolean` | Keep the entry out of the menu. Inherited from the resolved category when that category is hidden. |
+| `parent` | `ControllerClass` | The page this one is a detail of: the breadcrumb shows it before this page ("Operations / Projects / <record>"), its route parameters filled from this page's own. Resolved at registration, served as `parentSlug`. Pages only. |
 | `permission` | `Partial<Permission> \| Action` | Override the auto-derived page permission, or bind the page to an existing component `Action`. See [Permissions](/docs/interfaces/core/permissions). |
 | `publicAccess` | `boolean` | Serve the page without authentication. Inherited from the resolved category. |
 | `authOnly` | `boolean` | Require a logged-in user but no permission check. Inherited from the resolved category. |
@@ -212,7 +213,7 @@ Call `RegisterModule` before any page that references the module id: a page reso
 | `description` | `string` | Description carried on the module root. |
 | `icon` | `string` | Icon name. |
 | `landingPage` | `string` | Id of the page the module opens on; `/modules/<id>` redirects to it, query and hash kept. Defaults to the first page by `order`. |
-| `catalogCategory` | `string` | Category the module is filed under in the module catalog (`"Content"`, `"Developer"`…), may be a `$` i18n key; without one it goes under "Other". Unrelated to menu categories (`MenuOptions.category`, `defaultCategory`). Formerly `category`. |
+| `catalogCategory` | `string` | Category the module is filed under in the module catalog (`"Content"`, `"Developer"`…), may be a `$` i18n key. The Modules page and the store both file the module under it; without one, a store module takes the category of the store catalog, and any other goes under "Other". Unrelated to menu categories (`MenuOptions.category`, `defaultCategory`). Formerly `category`. |
 | `defaultCategory` | `{ displayName?, icon?, order?, urlSlug? }` | Groups the module's pages that declare `module` without an explicit `category`. Without it, those pages attach directly to the module root. |
 
 The generated default category uses `urlSlug` `"pages"` unless you override it, and falls back to the label `"$menu.section.pages"` when `displayName` is empty or omitted.
@@ -388,12 +389,20 @@ interface PageLayout<T = unknown> {
 Registering a page installs a `PageLayoutHandler` for its `fullSlug`:
 
 ```typescript
-type PageLayoutHandler = (
-  user: User | undefined,
-  memberModel: TenantMemberModel,
-  roleModel: RoleModel,
-  tenantId: string,
-) => Promise<PageLayout>;
+interface PageLayoutRequest {
+  user: User | undefined;
+  memberModel: TenantMemberModel;
+  roleModel: RoleModel;
+  tenantId: string;
+  /** The page URL's query, for header-button availability. */
+  query?: Readonly<Record<string, string>>;
+  /** The page URL's route parameters (`:id`), likewise. */
+  params?: Readonly<Record<string, string>>;
+  /** Passed to the permissions resolvers: `{ preview }` when a role preview reads the layout. */
+  resolverContext?: PermissionsResolverContext;
+}
+
+type PageLayoutHandler = (request: PageLayoutRequest) => Promise<PageLayout>;
 ```
 
 The handler drops the components the caller has no permission for and applies each component's own filter. Native upload tokens are bound to the exact page/component mount during page registration, not stamped by this handler; upload and metadata requests still check live authorization ([File storage](/docs/components/file-storage)). A page with `publicAccess`, `authOnly` or `noComponentPermissions` skips the filtering step and returns every component. Look a handler up with `GetPageLayoutBySlug(slug)`, which returns `undefined` for an unknown slug:
@@ -416,12 +425,12 @@ async function renderLayout(
   tenantId: string,
 ): Promise<PageLayout | undefined> {
   const handler = GetPageLayoutBySlug(slug);
-  return handler?.(
+  return handler?.({
     user,
-    GetModel(TenantMemberModel, tenantId),
-    GetModel(RoleModel, tenantId),
+    memberModel: GetModel(TenantMemberModel, tenantId),
+    roleModel: GetModel(RoleModel, tenantId),
     tenantId,
-  );
+  });
 }
 ```
 

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

@@ -45,6 +45,8 @@ RegisterPermission("reports.export", {
 | `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`.
+
 `RegisterPermission(id, permission)` takes the id twice — once as the registry key, once inside the record — so keep them equal.
 
 `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.
@@ -174,11 +176,42 @@ type PermissionsResolverFn = (
   userId: string,
   tenantId: string,
   currentPermissions: Set<string>,
+  context: PermissionsResolverContext,
 ) => 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`.
 
+### 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:
+
+```typescript
+RegisterPermissionsResolver({
+  id: "my_app.plan-limits",
+  order: 100,
+  resolver: async (userId, tenantId, currentPermissions, context) => {
+    const allowed = await loadPlanPermissions(tenantId);
+    if (!context.preview && (await isWorkspaceOwner(userId, tenantId))) {
+      return allowed;
+    }
+    return new Set([...currentPermissions].filter((p) => allowed.has(p)));
+  },
+});
+```
+
+The DMS always passes `context`: `{}` outside a preview.
+
 Semantics the interface guarantees:
 
 - Resolvers run in ascending `order`, each seeing the previous one's result; equal `order` runs in registration order, which is module load order.
@@ -187,7 +220,7 @@ Semantics the interface guarantees:
 - 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)` runs the pipeline and resolves to the effective set. Prefer `GetEffectiveUserPermissions`, which computes the base set for you and calls it.
+`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)).
 

package/docs/1.core/5.tenancy.md

@@ -127,7 +127,7 @@ Table `roles` in `dms-tenant` — the tenant's roles.
 
 ## Resolve the Request's Tenant
 
-`getRequestTenantId(ctx)` reads the `tenantId` claim of the request's bearer token and returns `DEFAULT_TENANT_ID` when there is no token or no claim.
+`getRequestTenantId(ctx)` returns the tenant of the request's **verified** credential, bound by the DMS auth decorators (`AuthUser`, `AuthRawUser`, `IfAuthUser` with a valid token, `AuthOwnerOnly`, `AuthUserWithPermission`, the auth a `PageController` installs), the tenant guards or `authenticateRequestUser`. Without a verified credential (anonymous request, invalid or forged token) it returns `DEFAULT_TENANT_ID`; a token is never read for its tenant before its signature, user and session are checked.
 
 ```typescript
 import {
@@ -148,11 +148,11 @@ export class WorkspaceController extends Controller("/api/workspace") {
 }
 ```
 
-The returned id is **decoded, not verified**: the function does not check the token's signature. It is safe behind a decorator that already authenticated the request — the guards from [Permissions](/docs/interfaces/core/permissions), `AuthUser` from `@antelopejs/interface-dms/auth`, or the auth a `PageController` installs. Do not authorize on the id in a route that no such decorator gates.
+Call it in the handler, after the route's auth decorator ran. A parameter or property provider that may run before it uses `resolveRequestTenantId(ctx)` (async), which verifies a bearer token itself and binds its tenant; `TenantScopedModel` does. Resolving a tenant is still not authorization: check membership and permissions for the operation.
 
 ## Scope a Model to the Request's Tenant
 
-`TenantScopedModel(ModelClass)` is a parameter and property decorator that injects `GetModel(ModelClass, getRequestTenantId(ctx))`.
+`TenantScopedModel(ModelClass)` is a parameter and property decorator that injects `GetModel(ModelClass, await resolveRequestTenantId(ctx))`: the tenant of the verified credential, `DEFAULT_TENANT_ID` without one.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -279,7 +279,7 @@ await applyTenantOwnership(GetModel(UserModel), userId, tenantId, {
 | `isTenantOwner` | `boolean` | Ownership flag after the write. |
 | `invitedBy` | `string \| null` | Recorded on insert. Ignored when the membership row already exists. |
 
-`applyTenantOwnership` fires `Hook.MEMBER_BEING_CHANGED` before any write, so a module can veto it. When the user is not yet a member, it also fires `Hook.MEMBER_BEING_ADDED` before the write and `Hook.MEMBER_ADDED` after it. For an existing member it updates `roleIds` and `isTenantOwner` and fires neither of those two ([Hooks](/docs/interfaces/core/hooks)).
+`applyTenantOwnership` goes through [`changeTenantMembers`](#changetenantmembers), which fires `Hook.MEMBER_BEING_CHANGED` before any write, so a module can veto it. When the user is not yet a member, it also fires `Hook.MEMBER_BEING_ADDED` before the write and `Hook.MEMBER_ADDED` after it. For an existing member it updates `roleIds` and `isTenantOwner` and fires neither of those two ([Hooks](/docs/interfaces/core/hooks)).
 
 Two helpers keep the legacy platform-owner flag on the user row aligned with tenant ownership:
 
@@ -313,9 +313,40 @@ The registration is removed when the registering module unloads, and the mode st
 
 Membership and invite producers coordinate with tenant deletion through `@antelopejs/interface-dms/tenant-lifecycle`. This is a write-lifecycle contract, not an authorization check or a transaction: authorize the caller separately.
 
+### `changeTenantMembers`
+
+Every insert, update or delete of a `TenantMemberModel` or `UserInviteModel` row goes through one entry point, `changeTenantMembers` from `@antelopejs/interface-dms/tenant-members`. The DMS uses it for every membership and invitation write it makes: adding a member, changing a member's roles or ownership (from the members table or the owner route), removing a member, moving the holders of a deleted role, leaving each tenant when an account is deleted, and creating, editing, resending, cancelling, expiring and accepting invitations. A module writing these rows itself must use it too; there is no other supported write path, and a raw `GetModel(...).insert/update/delete` on them skips both the barrier and the policy hook.
+
+```typescript
+changeTenantMembers<T>(
+  tenantId: string,
+  plan: () => Promise<{ changes: MemberChange[]; write: () => Promise<T> }>,
+): Promise<T>
+```
+
+It runs, in order:
+
+1. `runTenantLifecycleOperation(tenantId, ...)`: refused at once, before anything is read, while a [barrier](#pausing-admission) is held or once admission is closed;
+2. `plan()`, inside the admission, which reads the current rows and describes the change;
+3. `Hook.MEMBER_BEING_CHANGED` once per `MemberChange`, with `{ tenantId, ...change }`. A throwing handler refuses the write, replays of an invitation acceptance included;
+4. `write()`, then the admission is released as `runTenantLifecycleOperation` describes.
+
+A `MemberChange` has a `kind`:
+
+| `kind` | Fields | When |
+| ------ | ------ | ---- |
+| `added` | `userId`, `isTenantOwner`, `roleIds`, `deliveryId?` | A user joins: direct add, or an invitation accepted (`deliveryId` set) |
+| `removed` | `userId`, `isTenantOwner` | A member is removed, or leaves by deleting their account |
+| `roles` | `userId`, `roleIds`, `previousRoleIds` | A member's roles change, including when a deleted role is reassigned |
+| `ownership` | `userId`, `isTenantOwner`, `previousIsTenantOwner` | A member is given or loses the owner role |
+
+One edit setting both roles and ownership announces two changes. A write that changes no membership (an invitation created, edited or retired) passes `changes: []`: it is still admitted, and invitation creation keeps its own `Hook.INVITE_BEING_CREATED`. Do not call `changeTenantMembers` from inside another `changeTenantMembers` or `runTenantLifecycleOperation` callback.
+
+Deleting an account makes one call per tenant the user belongs to, in turn. A tenant holding a barrier refuses its call, which stops the deletion there: the account and its remaining memberships stay, and the user can retry once the barrier is released.
+
 ### `runTenantLifecycleOperation`
 
-`runTenantLifecycleOperation<T>(tenantId: string, work: () => Promise<T>): Promise<T>` admits one invocation before calling `work`, then returns its result after releasing that invocation's admission. Closed admission rejects without running `work`. Built-in membership and invite entry points already participate; custom producers must use this entry point and await every effect, with no detached writer.
+`runTenantLifecycleOperation<T>(tenantId: string, work: () => Promise<T>): Promise<T>` admits one invocation before calling `work`, then returns its result after releasing that invocation's admission. Closed admission rejects without running `work`. Membership and invitation writes use it through `changeTenantMembers`; call it directly only for other work that must coordinate with tenant deletion, and await every effect, with no detached writer.
 
 A successful callback releases its admission. A deliberate HTTP 4xx refusal also attempts release and rethrows the original refusal; other failures retain admission because their effects may be indeterminate. Retrying is a new invocation and never retires the failed one's identity. There is no automatic expiry or reconciliation API.
 
@@ -329,7 +360,7 @@ A module that must validate a tenant's inventory with no membership writer in fl
 | `pauseTenantLifecycleAdmission(tenantId, barrierId, expectedRevision)` | Publishes the barrier with one compare-and-set on `expectedRevision`. Resolves `false` when the revision moved, a barrier is held or admission is closed. |
 | `resumeTenantLifecycleAdmission(tenantId, barrierId)` | Releases this barrier; with no barrier held, it invalidates the revision so a delayed `pause` fails. Resolves `false` for another owner's barrier or closed admission. |
 
-While a barrier is held, `runTenantLifecycleOperation` rejects new work without running it; admitted work keeps running. Observe the revision before checking your own business intent, pause with that revision, recheck the intent, then wait for an observation with no active attempt before validating. A `false` from `pause` needs a new observation, not a blind retry. Use a unique `barrierId` per phase, and do not observe or pause from inside a `runTenantLifecycleOperation` callback: the caller would wait for itself.
+While a barrier is held, `runTenantLifecycleOperation` rejects new work without running it, with an `HTTPResult` 409 (`Tenant lifecycle admission is paused`): a deliberate refusal with nothing written and no admission retained, which the caller may retry once the barrier is released. Admitted work keeps running. Observe the revision before checking your own business intent, pause with that revision, recheck the intent, then wait for an observation with no active attempt before validating. A `false` from `pause` needs a new observation, not a blind retry. Use a unique `barrierId` per phase, and do not observe or pause from inside a `runTenantLifecycleOperation` callback: the caller would wait for itself.
 
 ### `closeTenantLifecycleAdmission`
 

package/docs/1.core/7.hooks.md

@@ -76,7 +76,7 @@ UnregisterHook(Hook.MEMBER_ADDED, onMemberAdded);
 | `Hook.INVITE_CREATED` | `"invite:created"` | `InviteCreatedHookPayload` | `undefined` |
 | `Hook.INVITE_DELETED` | `"invite:deleted"` | `InviteDeletedHookPayload` | `undefined` |
 | `Hook.MEMBER_BEING_ADDED` | `"member:being-added"` | `MemberHookPayload` | `undefined` |
-| `Hook.MEMBER_BEING_CHANGED` | `"member:being-changed"` | `MemberChangeHookPayload` | `undefined` — fires under tenant lifecycle admission before a membership is created or its ownership changes; throwing vetoes the write |
+| `Hook.MEMBER_BEING_CHANGED` | `"member:being-changed"` | `MemberChangeHookPayload` | `undefined` — fired by `changeTenantMembers` under tenant lifecycle admission before every membership write (`kind`: `added`, `removed`, `roles`, `ownership`); throwing vetoes the write |
 | `Hook.MEMBER_ADDED` | `"member:added"` | `MemberHookPayload` | `undefined` |
 | `Hook.MEMBER_REMOVED` | `"member:removed"` | `MemberRemovedHookPayload` | `undefined` |
 | `Hook.USER_REGISTERED` | `"user:registered"` | `UserRegisteredHookPayload` | `undefined` |
@@ -89,7 +89,7 @@ The `*_BEING_*` members fire before the write they precede; the past-tense membe
 ```typescript
 interface TenantProvisioningHookPayload {
   tenantId: string;
-  userId: string;
+  userId?: string; // absent for the `default` tenant
   extras: Record<string, unknown>;
 }
 
@@ -141,7 +141,17 @@ interface UserDeletedHookPayload {
 
 The shapes are not uniform, and the difference between the addition and removal payloads is deliberate: `MEMBER_BEING_ADDED` and `MEMBER_ADDED` describe one member with `userId`, while `MEMBER_REMOVED` carries `userIds`, because a removal can cover several members at once. Let the handler's inferred parameter type guide you.
 
-`MemberChangeHookPayload` extends `MemberHookPayload` with `previousIsTenantOwner`, `null` for a new membership. An invitation acceptance carries its `deliveryId` and is vetoed before the acceptance is persisted, including on replay: a `deliveryId` is not a policy exemption.
+`MemberChangeHookPayload` is `{ tenantId } & MemberChange`, a union discriminated by `kind`:
+
+```typescript
+type MemberChange =
+  | { kind: "added"; userId: string; isTenantOwner: boolean; roleIds: string[]; deliveryId?: string }
+  | { kind: "removed"; userId: string; isTenantOwner: boolean }
+  | { kind: "roles"; userId: string; roleIds: string[]; previousRoleIds: string[] }
+  | { kind: "ownership"; userId: string; isTenantOwner: boolean; previousIsTenantOwner: boolean };
+```
+
+Read `kind` first and return early for the kinds your policy does not limit. An invitation acceptance is an `added` change carrying its `deliveryId`, vetoed before the acceptance is persisted, including on replay: a `deliveryId` is not a policy exemption. See [`changeTenantMembers`](/docs/interfaces/core/tenancy#changetenantmembers) for which writes announce which kind.
 
 `UserDeletedHookPayload.tenantIds` lists the workspaces the user was a member of, all left before the deletion; delete the per-user rows your module keeps in them. `reason` is `"self"` today, the user deleting their own account.
 
@@ -253,7 +263,17 @@ The flip side is the usual one for a `*_BEING_*` hook: a handler that throws for
 
 `extras` is opaque by design. The DMS reads no key of it, validates nothing, and stores nothing — it carries the object from the caller of the provisioning flow to the handlers, and each handler writes what it recognises. The shape is a contract between that caller and that handler, one the DMS is deliberately not a party to, so a product can start collecting a new field without waiting on a DMS release.
 
-No DMS code fires this hook: provisioning belongs to the signup flow of a SaaS module such as **`dms-saas`**. The DMS declares the contract; the emitter honours it. Without such a module, nothing invokes it.
+It fires once per tenant, when the tenant is created, and never again on a later start. The DMS fires it for the `default` tenant, on the start that creates it, once every `DATABASE_INITIALIZED` handler has finished, so a module's tables and settings are ready; that payload has no `userId`, since the `default` tenant has no owner until onboarding. A SaaS module such as **`dms-saas`** fires it for each workspace its signup flow creates.
+
+This is where a module writes the **default data** a tenant starts with — templates, folders, a sender, a demo history. Written once, that data belongs to the tenant: the module does not write it again on a later start, does not compare it with what members changed since, and does not wait for the tenant from `start()` or `DATABASE_INITIALIZED`.
+
+```typescript
+RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
+  await writeDefaultFolders(tenantId);
+});
+```
+
+An emitter fires the hook through `ProvisionTenant` from `@antelopejs/interface-dms/tenant-provisioning`, never with a bare `ExecuteHooks`. It registers the tenant as an instance of the `dms-tenant` schema first, then runs the handlers, so no handler runs before the instance exists, whatever order the modules registered in.
 
 ## Contribute to a Tenant Data Export
 

package/docs/1.core/8.realtime.md

@@ -17,7 +17,7 @@ Subscription is derived, not requested by the publisher:
 
 1. A page — or a component on it — calls `RegisterPageTopic(pageId, topic)` at registration time. `pageId` is the page's `fullId` ([Pages and Modules](/docs/interfaces/core/pages-and-modules)), not its slug.
 2. A client opens a realtime session and reports which page it is on. The backend checks that the user may access that page, then subscribes the session to every topic registered for that page id, and drops the topics that are no longer wanted.
-3. `PublishMessage(topic, type)` delivers to the sessions currently subscribed to `topic`.
+3. `PublishMessage(topic, type)` delivers to the sessions currently subscribed to `topic` — with a `tenantId`, only to those of that tenant (see [Tenant-scoped messages](#tenant-scoped-messages)).
 
 So a publisher never addresses a page or a user. It addresses a topic, and the page-topic registry decides who is listening.
 
@@ -86,7 +86,7 @@ PublishMessage(
 | --------- | ----------- |
 | `topic` | The topic to publish on. Subscribers are the sessions on a page that registered this topic. |
 | `type` | The event type carried with the message, for subscribers that distinguish several kinds of event on one topic. |
-| `options` | Optional payload and actor. |
+| `options` | Optional payload, actor and tenant. |
 
 ### `PublishMessageOptions`
 
@@ -94,12 +94,32 @@ PublishMessage(
 | ------ | ---- | ----------- |
 | `payload` | `Record<string, unknown>` | Data carried with the event. |
 | `actorId` | `string` | Identifies who caused the event, so a client can ignore an event it triggered itself. |
+| `tenantId` | `string` | The tenant the event is about: only the sessions of that tenant receive it. Omitted, the message is global and reaches every tenant. |
 
 `PublishMessage` resolves once the message has been handed to the broker. It does not report how many sessions received it, and publishing on a topic no page registered is not an error — it simply reaches nobody.
 
+### Tenant-scoped messages
+
+Page topics are shared by every tenant: a page registers the same topic whichever workspace views it. A message published without a `tenantId` therefore reaches the sessions of **every** workspace on that page — each one refetches, and a paused live page counts the message in its "N new" banner. Publish a workspace's data with the tenant it belongs to:
+
+```typescript
+import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
+
+await PublishMessage(CAMPAIGN_TOPIC, "campaign.sent", {
+  payload: { count: sent.length },
+  tenantId: getRequestTenantId(ctx), // or the tenant a job runs for
+});
+```
+
+A session is bound to the tenant of the request that opened it, and receives the messages of that tenant plus the global ones. When the browser switches workspace (or account), the client opens a new session in the new one, and the server ends a session whose page requests come from a workspace or account other than its own, so the previous workspace's messages stop with it. A session on the connection a browser's tabs share is ended alone: the other tabs' sessions on it stay. Keep messages without a tenant for what is the same for every workspace: a platform-wide setting, a catalogue shared by all tenants.
+
+A session on a platform page (a page of a module, which only the platform owner opens) receives the messages of **every** tenant on that page's topics, whichever workspace the owner has open: such a page lists the data of all of them.
+
+The table views of the [Base](/docs/interfaces/base/tables#realtime) domain publish their row changes and presence for the writer's tenant, or for every tenant when their rows live in the shared schema. Messages to one user (notifications) and the menu invalidations already name their audience in the topic.
+
 ## Subscribe from the Backend
 
-`SubscribeMessage` receives every message published on a topic, whichever instance published it: the subscription rides the same broker as `PublishMessage`, so what one instance publishes reaches subscribers on every other.
+`SubscribeMessage` receives every message published on a topic, whichever instance and whichever tenant published it (a handler serving one tenant filters on `message.tenantId` itself): the subscription rides the same broker as `PublishMessage`, so what one instance publishes reaches subscribers on every other.
 
 ```typescript
 import { SubscribeMessage } from "@antelopejs/interface-dms/realtime";
@@ -132,6 +152,7 @@ type UnsubscribeMessage = () => void;
 | `type` | `string` | Event type given to `PublishMessage`. |
 | `payload` | `Record<string, unknown>` | Data carried with the event, when the publisher sent any. |
 | `actorId` | `string` | Who caused the event, when the publisher named an actor. |
+| `tenantId` | `string` | The tenant the message was published for; absent on a global message. |
 | `ts` | `number` | Publication timestamp. |
 
 Paired with `PublishMessage`, this turns the DMS's broker into one a module can use for realtime channels of its own — its own endpoint subscribes here and the DMS carries the messages — instead of bringing a second broker to do the same job.

package/docs/2.auth/2.authentication.md

@@ -7,7 +7,7 @@ description: "Authentication turns an incoming HTTP request into a `User` row."
 
 ## Overview
 
-Authentication turns an incoming HTTP request into a `User` row. The interface exposes one plain function, `authenticateRequestUser`, and four decorators built with `CreateAuthDecorator` from `@antelopejs/interface-auth`: `AuthRawUser`, `AuthUser`, `IfAuthUser` and `AuthOwnerOnly`.
+Authentication turns an incoming HTTP request into a `User` row. The interface exposes one plain function, `authenticateRequestUser`, and four decorators with the `CreateAuthDecorator` contract of `@antelopejs/interface-auth`: `AuthRawUser`, `AuthUser`, `IfAuthUser` and `AuthOwnerOnly`. Each of them, and `authenticateRequestUser`, binds the verified user and tenant to the request, which [`getRequestTenantId`](/docs/interfaces/core/tenancy#resolve-the-requests-tenant) then answers.
 
 All of them read the bearer token from the request's `Authorization` header (`Authorization: Bearer <token>`) and run the same two steps:
 
@@ -113,7 +113,7 @@ export class MaintenanceController extends Controller("/api/maintenance") {
 
 ## Gate Every Route on a Controller
 
-`AuthRawUser`, `AuthUser` and `IfAuthUser` are built with `CreateAuthDecorator`, so they apply to a parameter, to a property, or to the controller class itself. A property provider is a computed property of the controller, resolved on every request the controller handles whether or not the handler reads it — so a decorated property gates the whole controller and gives the handlers a typed `this.user`.
+`AuthRawUser`, `AuthUser` and `IfAuthUser` follow the `CreateAuthDecorator` contract, so they apply to a parameter, to a property, or to the controller class itself. A property provider is a computed property of the controller, resolved on every request the controller handles whether or not the handler reads it — so a decorated property gates the whole controller and gives the handlers a typed `this.user`.
 
 ```typescript
 import { Controller, Get, JSONBody, Post } from "@antelopejs/interface-api";
@@ -206,7 +206,7 @@ export const AuthBetaTester = MakeParameterAndPropertyDecorator(
 
 This is how the DMS builds its tenant guards: `AuthTenantOwner` and `AuthTenantMember` in `@antelopejs/interface-dms/guards` both start from `authenticateRequestUser`, then resolve the request's tenant and check the caller's membership on top of it.
 
-A provider is also the way to add a requirement without losing the built-in one. The `CreateAuthDecorator` contract lets a call site pass a replacement validator — `@AuthUser(callback)` — but that callback replaces the whole validation step, signature check included, and its return type is constrained to `boolean | User`. This interface exports no token-verification primitive, so a replacement validator cannot redo the signature check it removes.
+A provider is also the way to add a requirement without losing the built-in one. The `CreateAuthDecorator` contract lets a call site pass a replacement validator — `@AuthUser(callback)` — but that callback replaces the whole validation step, signature check included, and its return type is constrained to `boolean | User`; such a call binds no tenant to the request. This interface exports no token-verification primitive, so a replacement validator cannot redo the signature check it removes.
 
 ## Decorator Reference
 

package/docs/3.base/1.introduction.md

@@ -30,6 +30,7 @@ The DMS documentation carries task-shaped chapters on the same components, organ
 | `top-list-card` | `TopListCard` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
 | `period-selector` | `PeriodSelector` | yes | [Charts and Widgets](/docs/interfaces/base/charts-and-widgets) |
 | `live-toggle` | `LiveToggle` | yes | [Display Blocks](/docs/interfaces/base/display-blocks#live-toggle) |
+| `page-toolbar` | `PageToolbar`, `pageToolbar` | yes | [Display Blocks](/docs/interfaces/base/display-blocks#page-toolbar) |
 | `grid` | `Grid`, `GridRow` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
 | `stack` | `HStack`, `VStack`, `Spacer` | yes | [Layout and Containers](/docs/interfaces/base/layout) |
 | `tab` | `Tab` | yes | [Layout and Containers](/docs/interfaces/base/layout) |

package/docs/3.base/10.display-blocks.md

@@ -72,7 +72,7 @@ A block that can drop its frame does so with `card?: boolean` (`KeyValueList`, `
 
 | Props               | Own options                                               |
 | ------------------- | --------------------------------------------------------- |
-| `StatGroupProps`    | `items`, `layout` (`StatGroupLayout`), `columns`, `label` |
+| `StatGroupProps`    | `items`, `layout` (`StatGroupLayout`), `columns`, `columnsFrom` (`StatGroupColumnsFrom`: `sm` / `md` / `lg` / `xl`, the group width from which all `columns` sit side by side), `label` |
 | `KeyValueListProps` | `items`, `title`, `card`, `dense`, `columns`, `currency`  |
 | `NavCardGridProps`  | `items`, `title`, `description`, `columns`                |
 
@@ -127,10 +127,28 @@ Card({ title: "Connectors", count: 4 })
 
 ## Live Toggle
 
-`LiveToggle(options?)` (subpath `live-toggle`, block type `LiveToggle`, component `dms-live-toggle-block`, group `data`) is the Live / Pause switch of a page declared with `live` (`PageLiveOptions` from `@antelopejs/interface-dms/page`). `LiveToggleProps` extends `BaseComponentProps`: `align` (`LIVE_TOGGLE_ALIGNS`: `left`, `center`, `right`; default `right`) `showUpdatedAt` (default `true`), the time since the page last read its data, counted in the browser, `variant` (`LIVE_TOGGLE_VARIANTS`: `segmented`, `pill`; default `segmented`) and `missedLabel`, an i18n key or text given `{count}` naming the missed events while paused. The state belongs to the page, not to the block; on a page without `live` the block renders nothing.
+`LiveToggle(options?)` (subpath `live-toggle`, block type `LiveToggle`, component `dms-live-toggle-block`, group `data`) is the Live / Pause switch of a page declared with `live` (`PageLiveOptions` from `@antelopejs/interface-dms/page`). `LiveToggleProps` extends `BaseComponentProps`: `align` (`LIVE_TOGGLE_ALIGNS`: `left`, `center`, `right`; default `right`) `showUpdatedAt` (default `true`), the time since the page last read its data, counted in the browser, `variant` (`LIVE_TOGGLE_VARIANTS`: `segmented`, `pill`; default `segmented`), `size` (`LIVE_TOGGLE_SIZES`: `xs`, `sm`, `md`; default the holding `PageToolbar`'s, else `sm`) and `missedLabel`, an i18n key or text given `{count}` naming the missed events while paused. The state belongs to the page, not to the block; on a page without `live` the block renders nothing.
 
 ```typescript
 import { LiveToggle } from "@antelopejs/interface-dms/base/live-toggle";
 
 static toolbar = HStack().child("spacer", Spacer()).child("live", LiveToggle());
 ```
+
+## Page Toolbar
+
+`PageToolbar(options?)` (subpath `page-toolbar`, block type `PageToolbar`, component `dms-page-toolbar-block`, group `data`, a container) is the context bar of a page with a period or live data, first in its body. `PageToolbarProps` extends `BaseComponentProps`: `size` (`PAGE_TOOLBAR_SIZES`: `xs`, `sm`, `md`; default `sm`), the size of the `LiveToggle` and `PeriodSelector` it holds unless they set one, and `showUpdatedAt` and `refresh` (both default `true`), the "updated N s ago" label and the refresh button it shows where no `LiveToggle` is on screen — a page without `live` — counted from the page's last read. Its children render in one order whatever order they were added in: the other blocks, a spacer, the updated label or the `LiveToggle`, then the `PeriodSelector`.
+
+`pageToolbar(options?)` builds one: `PageToolbarOptions` extends `PageToolbarProps` with `leading` (`Record<string, Component>`, the blocks on the left by child id), `live` (`LiveToggleProps | false`, child `live`, over `PAGE_TOOLBAR_LIVE_DEFAULTS`) and `period` (`PeriodSelectorProps | false`, child `period`, over `PAGE_TOOLBAR_PERIOD_DEFAULTS`: segmented `last-hour` / `last-24h` / `last-7-days` / `last-30-days`, `defaultPreset: "last-24h"`, `rangeLabel: "relative"`, right aligned). Unless `period` sets `comparisonControl`, it is `"menu"` when the period offers more than one comparison (`none` included; the selector's default list when `comparisons` is unset), on `defaultComparison` or else the first one besides `none`, and `"hidden"` with a single comparison or none.
+
+```typescript
+import { pageToolbar } from "@antelopejs/interface-dms/base/page-toolbar";
+
+static toolbar = pageToolbar({
+  leading: { scope: scopeChip },
+  live: { missedLabel: "$api.live.new_requests" },
+  period: { id: "api", rememberKey: "api", comparisons: ["previous-period"] },
+});
+```
+
+A module's Vue component may also draw the toolbar itself, around controls of its own, as `<DmsPageToolbarBlock>` holding a `<DmsLiveToggleBlock>`: outside the page's block tree, neither needs a `componentId` or `pageId`.

package/docs/3.base/2.types.md

@@ -90,7 +90,7 @@ import {
 
 `Size` maps readable names onto the scale tokens: `tiny` → `"xs"`, `small` → `"sm"`, `medium` → `"md"`, `large` → `"lg"`, `huge` → `"xl"`. `SizeValue` widens it the same way `ColorValue` widens `Color`.
 
-`ModalSize` is a separate, wider union used only for modal action targets: `"sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl"`.
+`ModalSize` is a separate, wider union for modal and drawer action targets: `"sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl" | "full"`: a modal's width, and the width of a side drawer given that size, `full` the whole window.
 
 ## Buttons
 
@@ -145,9 +145,9 @@ import type { ActionTarget } from "@antelopejs/interface-dms/base/types/action-t
 
 | `type` | Fields |
 | --- | --- |
-| `"drawer"` | `component: Component`, `title?`, `description?`, `direction?: DrawerDirection` |
+| `"drawer"` | `component: Component`, `title?`, `description?`, `direction?: DrawerDirection`, plus `DrawerTargetOptions`: `size?: ModalSize`, `rowHeader?`, `rowTitle?`, `positionLabel?`, `deepLink?`, `notFound?` |
 | `"modal"` | `component: Component`, `size?: ModalSize`, `title?`, `description?` |
-| `"sidePanel"` | `component: Component`, plus `SidePanelTargetOptions`: `title?`, `rowTitle?`, `positionLabel?`, `deepLink?`, `notFound?` |
+| `"sidePanel"` | `component: Component`, plus `SidePanelTargetOptions`: `title?`, `rowTitle?`, `positionLabel?`, `deepLink?`, `notFound?` — for global, page-independent panels; a detail panel is a `drawer` |
 | `"page"` | `url: string`: the page URL's `{{params.X}}` / `{{query.X}}` (a query pair without a value left out), then on a row action the row's `{{row.field}}`; see [Template tokens](/docs/building/pages-and-components#template-tokens) |
 | `"external"` | `url: string`, `newTab?: boolean`; the same tokens as `page` |
 | `"download"` | `url: string`, `filename?: string` (`DownloadActionTarget`); the same tokens as `page`, the file name taking them as written. Fetched with the user's session and saved under `filename`, else the server's `Content-Disposition` name, else the URL's last segment; a failure is toasted |
@@ -155,9 +155,11 @@ import type { ActionTarget } from "@antelopejs/interface-dms/base/types/action-t
 | `"api"` | `url: string`, `method?: "GET" \| "POST" \| "PUT" \| "DELETE" \| "PATCH"`, `body?`, `copy?`, `successMessage: string`; the same tokens as `page` |
 | `"exportJob"` | `url: string`, `method?: "GET" \| "POST"`, `statusUrl?`, `downloadUrl?`, `labels?`; the same tokens as `page`, plus `{{job.id}}` in `statusUrl` and `downloadUrl` |
 
-`SidePanelTargetOptions` sets the header the DMS draws above a `sidePanel` target's component: `title` (the action's label by default; `$`: an i18n key), `rowTitle`, the title while a row is open, an i18n key or a literal receiving the row's fields (`"{method} {path}"`), `positionLabel`, an i18n key receiving `{ index }` (from 1) and `{ total }` for the row's position among the rows the table shows (the DMS's "{index} of {total}" by default), and `deepLink`, which keeps the open row in the URL like the action's own `deepLink` — on by default for a side panel, `false` opting out (the action's own `deepLink` wins when set), and `notFound` (`SidePanelNotFoundTexts`: `title?`, `description?`), the state the panel draws with a close button when the row a link names answers 404. The panel is non-modal and docked on the right, one at a time with a module's side panels.
+`SidePanelTargetOptions` sets the header the DMS draws above a `sidePanel` target's component: `title` (the action's label by default; `$`: an i18n key), `rowTitle`, the title while a row is open, an i18n key or a literal receiving the row's fields (`"{method} {path}"`), `positionLabel`, an i18n key receiving `{ index }` (from 1) and `{ total }` for the row's position among all the rows the table lists, its count rather than the page loaded (the DMS's "{index} of {total}" by default), and `deepLink`, which keeps the open row in the URL like the action's own `deepLink` — on by default for a side panel, `false` opting out (the action's own `deepLink` wins when set), and `notFound` (`SidePanelNotFoundTexts`: `title?`, `description?`), the state the panel draws with a close button when the row a link names answers 404. The panel is non-modal and docked on the right, one at a time with a module's side panels. It is meant for global, page-independent panels (an assistant dock): a detail or record panel opens in a `drawer`.
 
-`DrawerDirection` is `"top" | "right" | "bottom" | "left"`, the edge the drawer slides in from: `bottom` by default, while `left` and `right` open a side sheet 440px wide (a side panel's default width) spanning the window's height.
+`DrawerTargetOptions` gives a `drawer` target opened on a row the same options, so a detail panel moves from `sidePanel` to `drawer` without losing any: `rowTitle`, `positionLabel` and `notFound` as above; `rowHeader`, the DMS drawing the row header (the title naming the row, its position, previous and next buttons next to the close button) — on when `rowTitle` or `positionLabel` is set, `false` leaving the drawer's own title, `true` drawing it with the defaults; `deepLink`, off by default for a drawer (the action's own `deepLink` wins when set); and `size` (`ModalSize`), the width a `left` / `right` drawer opens at from `lg`, a modal's width at that size. J and K step through the rows in place whatever the header. A drawer shows its not-found state only once its target sets `notFound`; otherwise a deep link to a missing row is a toast, as before.
+
+`DrawerDirection` is `"top" | "right" | "bottom" | "left"`, the edge the drawer slides in from: `bottom` by default, while `left` and `right` open a side sheet spanning the window's height, 600px wide from `lg` without a `size` (capped to the window) and 440px below it. From `lg` the user resizes every drawer by its inner edge (width or height), and the drawer opens again at the size it was left at.
 
 A target carries no confirmation: the action does (`CustomButton.confirm`, `CustomRowAction.confirm`, `RowActionConfig.confirm`), with one type, `ActionConfirm = ConfirmDialog | ConfirmDialogFrom` (see below). The `labels` object on `exportJob` accepts `title`, `exporting`, `downloading`, `successTitle`, `successMessage`, `errorTitle` and `retry`, all optional strings.