@antelopejs/interface-dms 0.10.3 → 0.12.0

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

@@ -1,25 +1,20 @@
 ---
-title: "Pages and Modules"
-description: "Pages are controller classes registered into a navigation tree of modules and categories, with their own routes, layouts and extensions."
+title: "Pages and modules"
+description: "Pages are controller classes registered into a navigation tree of categories, with their own routes, layouts, access rules and extensions."
+mode: reference
 ---
 
-# Pages and Modules
+A page is a controller class. `PageController(id, options, layout?)` builds a base class bound to a URL, `@RegisterPage()` records it, and the components declared as static fields on the class become the page's serialized layout. Categories group pages into the sidebar tree. Modules, which own a branch of that tree, and dynamic menu entries are described in [Modules and dynamic menus](/docs/interfaces/core/modules-and-dynamic-menus).
 
-## Overview
+To build a first screen, follow [Pages & components](/docs/building/pages-and-components). That guide also shows [page extension placement](/docs/building/pages-and-components#extending-another-modules-page) in the running playground. Everything on this page lives in `@antelopejs/interface-dms/page`.
 
-A page is a controller class. `PageController(id, options, layout?)` builds a base class bound to a URL, `@RegisterPage()` records it, and the components declared as static fields on the class become the page's serialized layout. Categories group pages into the sidebar tree, and modules group a whole set of pages and categories under their own root.
+Registration happens at import time. The `@RegisterPage()` decorator runs when the file loads, so the order in which you import page files sets the order in which pages, categories and their permissions register.
 
-Building your first screen? Follow [Pages & components](/docs/building/pages-and-components) first. This reference covers registration, identifiers, and lifecycle rules. The guide also shows [page-extension placement](/docs/building/pages-and-components#extending-another-modules-page) in the running playground.
+## Declare a page
 
-Everything on this page lives in `@antelopejs/interface-dms/page`.
+`PageController(id, options, layout?)` returns a class that extends `Controller(pageRoutePath(fullSlug))`, so its routes live under `PAGE_ROUTE_PREFIX` (`/dms/pages`). Extend it, decorate it with `@RegisterPage()`, and declare components as static fields.
 
-Registration happens at import time: the `@RegisterPage()` decorator runs when the file is loaded, so the order in which you import page files determines the order in which pages, categories and their permissions are registered.
-
-## Declare a Page
-
-`PageController(id, options, layout?)` returns a class extending `Controller(fullSlug)`. Extend it, decorate with `@RegisterPage()`, and declare components as static fields.
-
-```typescript
+```typescript fragment
 import {
   Category,
   PageController,
@@ -46,44 +41,58 @@ export class InvoicesPage extends PageController("invoices", {
 }
 ```
 
-`PageController` requires either `category` or `module` in its options and throws otherwise. Since the returned class extends `Controller`, route decorators from `@antelopejs/interface-api` work on it directly — a route declared on the page class is served under the page's slug.
+`PageController` throws when its options declare neither `category` nor `module`. The returned class extends `Controller`, so route decorators from `@antelopejs/interface-api` work on it directly, and a route declared on the page class is served under the page's slug. [Identifiers a page carries](#identifiers-a-page-carries) gives the exact path.
 
-The third argument is the page layout, a `ComponentInfo` produced by a layout builder such as `DefaultLayout()` from `@antelopejs/interface-dms/base`. When you omit it, the page uses its own `layout` option, then the `layout` option of the nearest category or parent page declaring one, then `DefaultLayout()`.
+The third argument is the page layout, a `ComponentInfo` from a layout builder such as `DefaultLayout()` from `@antelopejs/interface-dms/base`. Without it, the page uses its own `layout` option, then the `layout` of the nearest category or parent page that declares one, then `DefaultLayout()`.
+
+`@RegisterPage()` reads the class's own static properties and records every `Component` under its property name. It skips a property whose name starts with `_`, so a class can keep a helper value without turning it into a layout entry.
 
 ### `MenuOptions`
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
 | `displayName` | `string` | Label shown in the sidebar. Required. |
-| `category` | `CategoryInfo \| ControllerClass` | Parent category. A `CategoryInfo` from `Category`/`RootCategory`/`RegisterModule`, or a controller class produced by `PageController`/`RootPageController`. |
-| `module` | `string` | Id of a module registered with `RegisterModule`. Attaches the page to that module's tree. |
+| `category` | `CategoryInfo \| ControllerClass` | Parent category: a `CategoryInfo` from `Category`, `RootCategory` or `RegisterModule`, or a controller class from `PageController` or `RootPageController`. |
+| `module` | `string` | Id of a module registered with `RegisterModule`. Attaches the entry to that module's tree. |
 | `urlSlug` | `string` | URL segment for this entry. Defaults to `id`. |
 | `description` | `string` | Longer description carried in the page metadata. |
 | `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. |
-| `memberAccess` | `boolean \| "self"` | Every signed-in member holds the page, its components and their actions without a role grant: their permissions register as `defaultGranted`, so guards still run and the Roles editor leaves them out. `true` is inherited by what is declared under the entry, page or category. `"self"` opens the entry alone: the settings root declares it, so it opens itself, not the pages declared under it. |
+| `hidden` | `boolean` | Keeps the entry out of the menu. A page or category under a hidden category is hidden too. |
+| `parent` | `ControllerClass` | The page this one is a detail of. The breadcrumb shows it before this page ("Operations / Projects / <record>"), with its route parameters filled from this page's parameters of the same name. Resolved at registration and served as `parentSlug`. Read on pages only. |
+| `permission` | `Partial<Permission> \| Action` | Overrides the derived page permission, or binds the page to an existing component `Action`. See [Permissions](/docs/interfaces/core/permissions). |
+| `publicAccess` | `boolean` | Serves the page without authentication. A page inherits it from its category. |
+| `authOnly` | `boolean` | Requires a signed-in user and no permission. A page inherits it from its category. |
+| `memberAccess` | `boolean \| "self"` | Opens the entry, its components and their actions to every signed-in member without a role grant. Their permissions register as `defaultGranted`, so guards still check them, the tenant access gate still applies, and the roles editor does not list them. `true` passes to what is declared under the entry. `"self"` opens the entry alone. `settingsCategory` declares `"self"`, so every member opens the settings overview while the workspace pages under it stay gated. `MemberAccess` names this type. |
 | `type` | `MenuItemType` | `"label"` or `"link"`. |
 | `validation` | `PageValidation` | Preconditions for opening the page. |
 | `setupId` | `string` | Id of a page setup function to run while the page is mounted. |
-| `noComponentPermissions` | `boolean` | Do not register per-component permissions for this page. |
+| `noComponentPermissions` | `boolean` | Registers no permission for the page's components. |
 | `query` | `MenuItemQuery` | Query parameters carried by the entry's menu link. |
 | `variant` | `MenuItemVariant` | Semantic look of the entry. |
-| `status` | `MenuItemStatus` | Semantic state dot rendered at the end of the entry. |
-| `badge` | `string` | Short count or label at the end of the entry (`3`, `new`); wins over `status` and over a counted navigation badge. |
-| `layout` | `ComponentInfo` | Default layout of the entry and of every page and sub-category declared under it that sets none of its own. The nearest declaring ancestor wins; a page's layout argument always overrides it. |
-| `bypassTenantAccessGate` | `boolean` | Keep the page reachable while a tenant access gate denies the tenant. Inherited by the pages of a flagged category. |
-| `live` | `PageLiveOptions` | Gives the page a Live / Pause state over the realtime of its blocks: `{ maxRate?, slowRateAfter?, rememberKey? }`. `maxRate` is the shortest interval in seconds between two refetches of one block, and the polling interval while the realtime stream is down; `slowRateAfter` (`PageLiveSlowRate`: `{ period: PageLivePeriod, maxRate }`, `period` like `"7d"`) a slower one once the period shown spans `period`; `rememberKey` a key sharing the remembered choice between pages. Read on pages only. A rate that is not a positive number, a period not reading like `30m` / `24h` / `7d`, or an empty `rememberKey` throws at declaration. |
+| `status` | `MenuItemStatus` | Semantic state dot at the end of the entry. |
+| `badge` | `string` | Short count or label at the end of the entry (`3`, `new`). It takes the place of `status` and of a counted navigation badge. |
+| `layout` | `ComponentInfo` | Default layout of the entry and of every page and category under it that sets none. The nearest declaring ancestor wins, and a page's layout argument always overrides it. |
+| `bypassTenantAccessGate` | `boolean` | Keeps the page reachable while a tenant access gate denies the tenant. The pages of a flagged category inherit it. |
+| `live` | `PageLiveOptions` | Gives the page a Live and Pause state over the realtime of its blocks. Read on pages only. |
 
 `MenuItemType` is `"label" | "link"`.
 
-`PageValidation` has three optional fields: `requiredQueryParams` (a `string[]` of query parameters the page needs), `customFunctionId` (the id of a registered validation function) and `redirectTo` (where a page failing its validation sends the user instead of answering "Page not found": a dashboard path, with the page URL's `{{params.X}}` / `{{query.X}}` tokens; see [Page setup and validation](/docs/building/pages-and-components#page-setup-and-validation)).
+`PageValidation` has three optional fields:
+
+- `requiredQueryParams`, a `string[]` of query parameters the page needs, each with a non-empty value.
+- `customFunctionId`, the id of a validation function the frontend registers.
+- `redirectTo`, the dashboard path a page that fails its validation sends the user to instead of answering "Page not found". The path may use the `{{params.X}}` and `{{query.X}}` tokens of the page URL. [Page setup and validation](/docs/building/pages-and-components#page-setup-and-validation) shows it in use.
+
+`PageLiveOptions` has three optional fields. [Live pages](/docs/building/live-pages) explains the behaviour they control.
+
+- `maxRate`, the shortest interval in seconds between two refetches of one block, and the polling interval while the realtime stream is down.
+- `slowRateAfter`, a `PageLiveSlowRate` of `{ period: PageLivePeriod; maxRate: number }`. Once the period the page shows spans `period`, its `maxRate` replaces the page's. `PageLivePeriod` is a whole number followed by `m`, `h` or `d`, such as `"7d"`.
+- `rememberKey`, a key that shares the remembered Live or Pause choice between the pages that declare it.
 
-### Menu Entry Appearance
+A rate that is not a positive number, a period that does not read like `30m`, `24h` or `7d`, or an empty `rememberKey` throws at declaration.
+
+### Menu entry appearance
 
 Three types describe how an entry looks, so a consumer never ships raw classes:
 
@@ -93,11 +102,13 @@ type MenuItemStatus = "success" | "warning" | "error" | "neutral";
 type MenuItemQuery = Record<string, string>;
 ```
 
-`accent` renders the entry in the theme's primary color, for a call-to-action entry such as "New project". `status` maps to the theme's semantic colors.
+`accent` renders the entry in the theme's primary color, for a call to action such as "New project". `status` maps to the theme's semantic colors.
 
-`query` appends parameters to the entry's link, which is what lets a single page serve many entries — declare it with `validation.requiredQueryParams`, then point several entries at it:
+`query` appends parameters to the entry's link, so one page can serve many entries. Declare the parameter in `validation.requiredQueryParams`, then point several entries at the page:
 
 ```typescript
+import { PageController, RegisterPage, pagesCategory } from "@antelopejs/interface-dms/page";
+
 @RegisterPage()
 export class ProjectPage extends PageController("project", {
   displayName: "Project",
@@ -107,15 +118,15 @@ export class ProjectPage extends PageController("project", {
 }) {}
 ```
 
-### Reaching a Page Behind a Tenant Gate
+### Reach a page behind a tenant gate
 
-`bypassTenantAccessGate` is the page-level mirror of the guard option of the same name ([Permissions](/docs/interfaces/core/permissions)). It covers page visibility, menu visibility and the page's own layout route, and a flagged category passes it to its pages. Permission checks still apply — unlike `authOnly`, which drops them entirely.
+`bypassTenantAccessGate` is the page-level mirror of the guard option of the same name ([Permissions](/docs/interfaces/core/permissions#authtenantowner-and-authtenantmember)). It covers the page's visibility, its menu entry and its own layout route, and a flagged category passes it to its pages. Permission checks still apply. `authOnly`, by contrast, drops them.
 
-It does not cover the data routes feeding the page: a data API is not owned by a single page, so it opts out through its own guard, or through `TableViewOptions.bypassTenantAccessGate` for a table view. Reserve the flag for recovery surfaces — billing, a payment portal — that a blocked tenant must still reach in order to unblock itself.
+The flag does not cover the data routes that feed the page. A data API belongs to no single page, so it opts out through its own guard, or through `TableViewOptions.bypassTenantAccessGate` for a table view. Reserve the flag for recovery surfaces, such as billing or a payment portal, that a blocked tenant must reach to unblock itself.
 
-## Group Pages with Categories
+## Group pages with categories
 
-`Category(id, options)` returns a `CategoryInfo` you pass as another entry's `category`. Categories nest, and they require a `category` or a `module` of their own.
+`Category(id, options)` returns a `CategoryInfo` that you pass as another entry's `category`. Categories nest, and each one throws unless it declares a `category` or a `module`.
 
 ```typescript
 import {
@@ -135,11 +146,11 @@ export const contacts = Category("contacts", {
 });
 ```
 
-Creating a category registers a permission keyed to its `fullId`, unless the category sits inside a module — see [Permissions](/docs/interfaces/core/permissions).
+Creating a category registers a permission keyed to its `fullId`. The permission is `defaultGranted` when the category declares `publicAccess` or `memberAccess`, and its `permission` option overrides the derived fields. A category inside a module marks its id module-scoped instead, and a category whose `permission` is an `Action` registers none. [Permissions](/docs/interfaces/core/permissions) covers both.
 
-### Root Categories
+### Root categories
 
-`RootCategory(id, options)` creates a top-level group next to the built-in ones. Its options are `MenuOptions` without `category` and `module`. `type` defaults to `"label"`. The ids `pages`, `modules` and `settings` are reserved and throw.
+`RootCategory(id, options)` creates a top-level group next to the built-in ones. Its options are `MenuOptions` without `category` and `module`, and `type` defaults to `"label"`. The ids `pages`, `modules` and `settings` are reserved and throw.
 
 ```typescript
 import { RootCategory } from "@antelopejs/interface-dms/page";
@@ -151,187 +162,48 @@ export const catalogCategory = RootCategory("catalog", {
 });
 ```
 
-The interface exports three built-in roots:
+The interface exports these built-in roots:
 
-| Export | Kind | URL slug |
-| ------ | ---- | -------- |
-| `pagesCategory` | `CategoryInfo` | `/` |
-| `modulesCategory` | controller class (`RootPageController`) | `/modules` |
-| `settingsCategory` | controller class (`RootPageController`) | `/settings` |
+| Export | Kind | URL slug | `order` |
+| ------ | ---- | -------- | ------- |
+| `pagesCategory` | `CategoryInfo` | `/` | `1` |
+| `modulesCategory` | controller class (`RootPageController`) | `/modules` | `2` |
+| `settingsCategory` | controller class (`RootPageController`) | `/settings` | `3` |
 
-`settingsCategory` declares `layout: SettingsLayout()`, so every page under it renders in the settings frame unless it passes a layout of its own. `workspaceSettingsCategory` (`Category("workspace", …)` under `settingsCategory`, full id `settings.workspace`, URL `/settings/workspace`) holds the workspace settings — members, invitations, roles — and is where a project adds its own ([Settings pages](/docs/building/settings-pages)).
+`settingsCategory` declares `layout: SettingsLayout()`, so every page under it renders in the settings frame unless it passes its own layout. `workspaceSettingsCategory` is `Category("workspace", …)` under `settingsCategory`, with the full id `settings.workspace` and the URL `/settings/workspace`. It holds the workspace settings, such as members, invitations and roles, and a project adds its own there ([Settings pages](/docs/building/settings-pages)).
 
-`modulesCategory` is the module root: every module registered with `RegisterModule` attaches under it. A page or category that declares a `module` cannot resolve to a category under `settingsCategory`; that combination throws.
+`modulesCategory` is the module root that every module registered with `RegisterModule` attaches under. A page or category that declares a `module` cannot resolve to a category under `settingsCategory`. That combination throws.
 
 ### `RootPageController`
 
-`RootPageController(id, options, layout?)` builds a page controller at the root of the tree. Its options are `MenuOptions` without `category` and `module`, plus an optional `isModuleRoot` boolean. Unlike `PageController` it does not require a parent, which is what makes it usable for a top-level landing screen.
-
-## Identifiers a Page Carries
-
-`Category`, `PageController` and `RootPageController` compute two identifiers from the entry's own id and its parent chain:
-
-- `fullId` — the dot-joined chain of ids, starting at the root category (`pages.crm.contacts`). This is the page's permission id and the key realtime topics are registered under.
-- `fullSlug` — the joined URL slugs (`/crm/contacts`).
-
-`CategoryInfo` extends `MenuOptions` with `category` redeclared as a required `CategoryInfo | ControllerClass | undefined` holding the resolved parent, and adds `id`, `fullId`, `fullSlug` and an optional `isModuleRoot`. `PageInfo` extends `CategoryInfo` and adds `layoutUrl`, the URL the page's component tree is served from — `/dms/pages`, the page's `fullSlug`, then `/pagelayout`.
-
-A page controller (`PageController`, `RootPageController`) serves its routes under `PAGE_ROUTE_PREFIX` (`/dms/pages`), not at the page's own path: the frontend server answers that path with the page and proxies only the backend prefixes declared to it, `/api/**` and `/dms/**` for the DMS. `@Get("/sessions")` on the page `/settings/user/security` is `GET /dms/pages/settings/user/security/sessions`, which `pageRoutePath("/settings/user/security", "/sessions")` spells out. A plain `Controller` a module mounts for its frontend sits under `/api/<module>/` instead, or under a prefix it declares (`backendProxies`, below).
-
-`GetPermissionId(target)` returns the permission id recorded for a page controller class or a `Component`, or `undefined` when the target was never registered. A child component resolves to its full positional path. When the same component instance is mounted more than once, every position registers a permission but the instance resolves to its first registered position, because the instance alone cannot identify which mount the caller means.
-
-```typescript
-import { GetPermissionId } from "@antelopejs/interface-dms/page";
-
-const pagePermission = GetPermissionId(InvoicesPage); // "pages.billing.invoices"
-```
-
-## Declare a Module
-
-A module is a self-contained feature area with its own root in the sidebar. `RegisterModule(info)` creates that root under `modulesCategory` and returns its `CategoryInfo`.
-
-```typescript
-import { RegisterModule } from "@antelopejs/interface-dms/page";
-
-RegisterModule({
-  id: "automation",
-  title: "$dms_automation.module.title",
-  description: "$dms_automation.module.description",
-  icon: "i-ph-flow-arrow",
-  defaultCategory: { displayName: "$dms_automation.module.pages", order: 0 },
-});
-```
-
-Call `RegisterModule` before any page that references the module id: a page resolves its module synchronously inside the `PageController` call of its class declaration, before `@RegisterPage()` runs, and an unknown module id throws. Registering the same id twice throws as well.
-
-### `ModuleInfo`
-
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `id` | `string` | Module id. Also the URL segment under `/modules`. |
-| `title` | `string` | Display name of the module root. |
-| `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. 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.
-
-### Attaching Pages to a Module
-
-Set `module` on the page options. `category` stays available to group pages inside the module:
-
-```typescript
-import {
-  PageController,
-  RegisterPage,
-} from "@antelopejs/interface-dms/page";
-import "./module"; // ensures RegisterModule ran first
-
-@RegisterPage()
-export class OverviewPage extends PageController("overview", {
-  displayName: "$dms_automation.overview.title",
-  icon: "i-ph-gauge",
-  module: "automation",
-  order: 0,
-}) {}
-```
-
-When a page declares both `module` and an explicit `category`, the category must be a descendant of that module's root; otherwise registration throws.
-
-### Module URLs and Detection
-
-`MODULE_URL_PREFIX` is `"/modules"`. Module pages resolve under `/modules/<moduleId>/...` because the module root's `urlSlug` is the module id and its parent is `modulesCategory`. Their ids follow the same chain: the module root's `fullId` is `modules.<moduleId>`, and a page in it is `modules.<moduleId>.<pageId>`.
-
-`isInsideModule(entry)` answers whether an entry belongs to a module. It accepts anything carrying `module`, `category` and `isModuleRoot` — a `CategoryInfo` or `PageInfo` qualifies — and walks the category chain looking for a module root.
-
-```typescript
-import { isInsideModule } from "@antelopejs/interface-dms/page";
-
-if (isInsideModule(pageInfo)) {
-  // module pages are gated to platform owners
-}
-```
-
-Permissions belonging to a module entry are marked module-scoped instead of being registered in the grantable permission tree. [Permissions](/docs/interfaces/core/permissions) covers what that implies.
-
-## Contribute Menu Entries at Request Time
-
-Everything above declares the menu at import time. A dynamic menu provider adds entries resolved per request instead — one entry per project, per workspace, per whatever the tenant happens to own.
-
-```typescript
-import { RegisterDynamicMenuProvider } from "@antelopejs/interface-dms/page";
-
-RegisterDynamicMenuProvider("pages.projects", async (user, tenantId) => {
-  const projects = await listProjects(tenantId);
-  return projects.map((project, index) => ({
-    id: project.slug,
-    displayName: project.name,
-    fullSlug: "/projects/:projectId",
-    params: { projectId: project.id },
-    icon: "i-ph-folder",
-    order: index,
-  }));
-});
-```
-
-```typescript
-function RegisterDynamicMenuProvider(
-  categoryFullId: string,
-  resolver: DynamicMenuResolver,
-): () => void;
-
-type DynamicMenuResolver = (
-  user: User | undefined,
-  tenantId: string,
-  permissions: Set<string>,
-) => MaybePromise<DynamicMenuItem[]>;
-```
-
-A registration is a `DynamicMenuProviderInfo` — the `categoryFullId` and the `resolver`, paired. The resolver runs during `/sitelayout`, and its entries are grafted onto that request's copy of the tree only — the global navigation tree is never touched, so one tenant's entries can never reach another's site layout. Dynamic and static children of the category sort together by `order`.
+`RootPageController(id, options, layout?)` builds a page controller at the root of the tree. Its options are `MenuOptions` without `category` and `module`, plus an optional `isModuleRoot` boolean. It requires no parent, so it suits a top-level landing screen.
 
-`permissions` is the caller's effective permission set as the parent category sees it: empty while a tenant access gate denies the tenant, unless the category is flagged `bypassTenantAccessGate`, in which case the real set is kept. `user` is `undefined` for an unauthenticated request.
+## Identifiers a page carries
 
-A resolver that throws is skipped with a warning and the rest of the menu still resolves. The registration is removed when the registering module unloads; the returned function drops it earlier, for the rare case a module stops providing while staying loaded.
+`Category`, `PageController` and `RootPageController` compute two identifiers from the entry's id and its parent chain:
 
-### `DynamicMenuItem`
+- `fullId` is the chain of ids joined by dots, from the root category (`pages.crm.contacts`). It is the page's permission id and the key its realtime topics register under.
+- `fullSlug` is the chain of URL slugs (`/crm/contacts`).
 
-An item is not a page. It links to an already registered page, which is why one page — typically one whose slug has `:name` segments, or one with `validation.requiredQueryParams` — can back any number of entries.
+`CategoryInfo` extends `MenuOptions` without `parent`. It redeclares `category` as a required `CategoryInfo | ControllerClass | undefined` that holds the resolved parent, and adds `id`, `fullId`, `fullSlug`, an optional `isModuleRoot`, and an optional `urlTransparent`. `urlTransparent` is `true` when the category adds no URL segment of its own, as `urlSlug: "/"` produces. Such a category is a section heading, not a route, and any number of them may sit under one parent.
 
-`params` fills the `:name` segments of `fullSlug`, URL-encoding each value, and the entry links to the result: `fullSlug: "/projects/:projectId"` with `params: { projectId: "acme" }` links to `/projects/acme`. The values must fill every segment and nothing else. An entry that leaves a segment empty, or names a parameter the slug does not have, is skipped with a warning rather than linking to a literal `:projectId`.
-
-| Field | Type | Description |
-| ----- | ---- | ----------- |
-| `id` | `string` | Unique within the provider's category, and becomes the entry's `fullId` suffix. Dots separate `fullId` levels, so an id containing one is skipped with a warning. Required. |
-| `displayName` | `string` | Entry label. Required. |
-| `fullSlug` | `string` | Full slug of the page the entry links to, `:name` segments included. Required. |
-| `params` | `MenuItemParams` | Values for the `:name` segments of `fullSlug`. |
-| `query` | `MenuItemQuery` | Query parameters narrowing that page. |
-| `description` | `string` | Longer description. |
-| `icon` | `string` | Icon name. |
-| `order` | `number` | Sort order among the category's children, dynamic and static alike. |
-| `variant` | `MenuItemVariant` | Semantic look. |
-| `status` | `MenuItemStatus` | Semantic state dot. |
-| `permissionId` | `string` | Permission required to see the entry, as a raw id. Unset means always visible. |
+`PageInfo` extends `CategoryInfo` with `layoutUrl` and an optional `parentSlug`. `layoutUrl` is the URL the page's component tree is served from: `/dms/pages`, then the page's `fullSlug`, then `/pagelayout`. `parentSlug` is the full slug of the page declared as `parent`.
 
-An entry is listed only when the caller can access the page it points at, so it never offers a link its target would refuse.
+A page controller serves its routes under `PAGE_ROUTE_PREFIX` (`/dms/pages`), not at the page's own path. The frontend server answers the page's own path with the page, and proxies only the backend prefixes declared to it, which are `/api/**` and `/dms/**` for the DMS. `@Get("/sessions")` on the page `/settings/user/security` is `GET /dms/pages/settings/user/security/sessions`, which `pageRoutePath("/settings/user/security", "/sessions")` returns. A plain `Controller` that a module mounts for its frontend sits under `/api/<module>/` instead, or under a prefix it declares in [`backendProxies`](/docs/interfaces/core/frontend-modules-and-request-helpers#addfrontendmoduleoptions).
 
-`permissionId` is a raw id here, unlike `MenuOptions.permission`, which takes a whole permission or an `Action`. It is matched against the permission set the caller's browser actually receives, the way the browser matches it — the wildcard or a literal grant, never a `defaultGranted` fallback — so the sidebar never offers an entry whose controls would be inert. While a gate denies the tenant that set holds only the surfaces flagged `bypassTenantAccessGate`, so a recovery entry declares its permission under its target page, as in `<recoveryPageFullId>.settle`.
+`GetPermissionId(target)` returns the permission id recorded for a page controller class, a `Component`, or a child position, or `undefined` when the target never registered. A child component resolves to its full positional path. When one component instance is mounted more than once, every position registers a permission, but the instance alone resolves to its first registered position. `GetComponentPermissionIds(component)` returns the ids of every live position of a reusable component.
 
-### `NotifyMenuChanged`
+```typescript fragment
+import { GetPermissionId } from "@antelopejs/interface-dms/page";
 
-```typescript
-const NotifyMenuChanged: (tenantId?: string) => void;
+const pagePermission = GetPermissionId(InvoicesPage);
 ```
 
-Call it when the data behind a provider changes — a project created or deleted — so connected clients resync. The signal carries no data: it is an invalidation, and each client re-fetches its own `/sitelayout`, resolved against its own permissions.
+For the page declared above, `pagePermission` is `"pages.billing.invoices"`. `GetRegisteredPageIds()` returns the ids of every registered page, sorted.
 
-Pass the `tenantId` whose data changed so only that tenant's sessions re-fetch. Omitting it invalidates the menu for every connected session, which is meant for changes that are not tenant-scoped.
+## Extend a page from another module
 
-## Extend a Page from Another Module
-
-`@RegisterPageExtension(targetPageId)` injects components into a page owned by someone else. The decorated class is not a page: every static component field on it becomes a component of the target page, keyed by its field name.
+`@RegisterPageExtension(targetPageId)` injects components into a page that another module owns. The decorated class is not a page. Every static component field on it becomes a component of the target page, keyed by its field name.
 
 ```typescript
 import { RegisterPageExtension } from "@antelopejs/interface-dms/page";
@@ -345,17 +217,22 @@ export class SeatQuotaExtension {
 }
 ```
 
-The target is named by its page id — the `fullId` the page registered under, which is also its permission id: the dotted path of its categories followed by its own id (`settings.workspace.members` for the DMS members page). Nothing of the owning module is imported, so an extending module depends on `@antelopejs/interface-dms` alone and never owns another module's registrations. `GetRegisteredPageIds()` lists the ids currently registered, and `GetPermissionId(ThePageClass)` returns one from inside the module that owns the page.
+The target is named by its page id, the `fullId` it registered under, which is also its permission id. The DMS members page is `settings.workspace.members`. The extending module imports nothing from the owning module, so it depends on `@antelopejs/interface-dms` alone. `GetRegisteredPageIds()` lists the ids, and `GetPermissionId(ThePageClass)` returns one inside the owning module.
 
-Because the field name is the component key, an injected component is permissioned as `<target fullId>.<field name>` in the target page's own permission tree — exactly like a component the target declares itself. The target's own fields and every extension of it share that one namespace.
+The field name is the component key, so an injected component's permission is `<target fullId>.<field name>` in the target page's own permission tree, like a component the target declares itself. The target's fields and those of every extension share that namespace.
 
-Placement is declared on the component with `.before(anchor)` / `.after(anchor)`, where the anchor is a component key of the target page — `"table"` for a static field of the page, `"content.tasks"` for a position nested under one. Without one, the component is appended after the page's own components. When several land at the same spot `.order(n)` decides, and equal orders fall back to the extension class name and then to declaration order — never to module start order. [Components](/docs/interfaces/core/components) covers those three builder methods.
+`.before(anchor)` and `.after(anchor)` on the component set its placement. The anchor is a component key of the target page: `"table"` for a static field, or `"content.tasks"` for a nested position. Without an anchor, the component goes after the page's own components. When several components land at the same spot, `.order(n)` decides, and equal orders fall back to the extension class name and then to declaration order, never to module start order. [Components](/docs/interfaces/core/components) covers those builder methods.
 
-The injection applies as soon as the target page has finished registering — it is held until then whichever module starts first, so anchors always resolve against the page's complete component set — and is removed when the extending module stops. Its components are prepared as the extending module — whichever module's registration triggers it, and again each time the target page registers anew — so what they register (their permissions, native upload fields, form sub-pages, realtime topics) belongs to the extending module: it survives a reload of the DMS or of the target's module, and goes away with the extending module. An extension class declaring no component field is a warning, not an error, and injects nothing; an empty target id throws.
+The injection applies once the target page finishes registering, whichever module starts first, so anchors resolve against the page's complete component set. It is removed when the extending module stops. The components are prepared as the extending module, each time the target page registers. What they register, such as permissions, native upload fields, form sub-pages and realtime topics, belongs to the extending module. It survives a reload of the DMS or of the target's module and goes away with the extending module.
 
-Nothing about the target can be checked when the decorator runs, so everything is checked when the injection applies: a page id no module registers keeps the extension pending and is reported as a warning once every module has started, while a key the page (or another extension) already uses and an anchor the page does not declare are reported at error level — with the extension name, the target id and the offending key — and that extension alone is skipped.
+Nothing about the target can be checked when the decorator runs, so the checks happen when the injection applies:
 
-```typescript
+- An empty target id throws at the decorator.
+- An extension class with no component field logs a warning and injects nothing.
+- A page id that no module registers keeps the extension pending, with a warning once every module has started.
+- A key that the page or another extension already uses, or an anchor that the page does not declare, is reported at error level with the extension name, the target id and the key. That extension alone is skipped.
+
+```typescript fragment
 interface PageExtensionInfo {
   extensionName: string;
   targetFullId: string;
@@ -366,46 +243,48 @@ interface PageExtensionComponent {
   key: string;
   component: Component;
   side: PlacementSide;
-  anchorKey?: string;
+  anchorPath?: readonly string[];
   order: number;
 }
 ```
 
-`PageExtensionInfo` is the registration handle: it is the object that gets unregistered when the extending module stops. `key` is the static field name the component was declared under, and also the last segment of its permission id on the target page.
+`PageExtensionInfo` is the registration handle that is unregistered when the extending module stops. `key` is the static field name, and also the last segment of the component's permission id on the target page. `anchorPath` is the anchor split into its dotted segments.
 
-## Page Layouts
+## Page layouts
 
 A page layout is the serialized description of the page's components:
 
-```typescript
+```typescript fragment
 interface PageLayout<T = unknown> {
   components: Record<string, ComponentInfoSerialized<T>>;
   layout?: ComponentInfo<T>;
+  allComponentsHidden?: true;
 }
 ```
 
-`components` is keyed by the static field name on the page class; each value is the serialized form of the component ([Components](/docs/interfaces/core/components)). `layout` is the layout component passed as `PageController`'s third argument.
+`components` is keyed by the static field name on the page class, and each value is the serialized component ([Components](/docs/interfaces/core/components)). `layout` is the layout component. `allComponentsHidden` is set when the page declares components and the caller may see none of them, so the browser can say so instead of drawing a blank page.
 
 Registering a page installs a `PageLayoutHandler` for its `fullSlug`:
 
-```typescript
+```typescript fragment
 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:
+`query` and `params` are the page URL's query and route parameters, handed to header-button availability. `resolverContext` goes to the permissions resolvers, with `preview` set when the layout is served for a role preview.
+
+The handler drops the components the caller has no permission for and applies each component's own filter. A page with `publicAccess`, `authOnly` or `noComponentPermissions` skips the permission step and returns every component. Native upload tokens are bound to the exact page and component mount at page registration, not by this handler, and upload and metadata requests still check live authorization ([File storage](/docs/components/file-storage)).
+
+`GetPageLayoutBySlug(slug)` returns the handler, or `undefined` for an unknown slug:
 
 ```typescript
 import { GetModel } from "@antelopejs/interface-database-decorators";
@@ -434,40 +313,43 @@ async function renderLayout(
 }
 ```
 
-`ClearPageLayoutBySlug(slug)` drops the handler again. A page unregisters through it: the handler is reachable by slug from `/dms/pagelayout`, so leaving it behind keeps serving the layout of a page that is already gone from the registry, the navigation tree and its own route — an unloaded module's screens would still answer.
+`ClearPageLayoutBySlug(slug)` drops the handler. A page unregisters through it, because `/dms/pagelayout` reaches the handler by slug. A handler left behind would keep serving the layout of a page already gone from the registry, the navigation tree and its own route.
 
 ### `PageMetadata`
 
-`PageMetadata` is the per-controller record the decorator fills in. `GetMetadata(controllerClass, PageMetadata)` returns it. It holds `pageInfo`, `layout` and `components`, and exposes:
+`PageMetadata` is the record the decorator fills in for each controller. `GetMetadata(controllerClass, PageMetadata)` returns it. It holds `pageInfo`, `layout` and `components`, and exposes:
 
 | Member | Description |
 | ------ | ----------- |
-| `SetInfo(id, fullSlug, menuOptions, pageLayout?)` | Compute and store the `PageInfo` and the layout. |
-| `SetComponent(id, component)` | Attach a component under a key. |
-| `inherit(parent)` | Merge another `PageMetadata`'s info, layout and components into this one. |
-| `Register()` | Register the page: permissions, layout handler, `/pagelayout` route and auth decorators. |
-| `target` | The controller class the metadata belongs to. |
+| `SetInfo(id, fullSlug, menuOptions, pageLayout?)` | Computes and stores the `PageInfo` and the layout. |
+| `SetComponent(id, component)` | Attaches a component under a key. |
+| `inherit(parent)` | Merges another `PageMetadata`'s info, layout and components into this one. |
+| `Register()` | Registers the page: permissions, layout handler, `/pagelayout` route and auth decorators. |
+| `ComponentPermissionIds(component)` | Returns the permission ids of every position the component holds on this page. |
+| `target` | The controller class the record belongs to. |
+
+`@RegisterPage()` calls `SetComponent` for each static component and then `Register()`. Use `PageMetadata` directly only to generate pages programmatically.
 
-`@RegisterPage()` does this for you: it scans the class's own static properties, records every `Component` it finds under its property name, and calls `Register()`. Static properties whose name starts with `_` are skipped, which is how you keep a helper value on the class without turning it into a layout entry. Reach for `PageMetadata` directly only when you generate pages programmatically.
+Registration also runs each component's `onCreated` callback with this record. It registers a permission for each component and each component action, unless the page sets `noComponentPermissions` or `authOnly`, or sits inside a module ([Permissions](/docs/interfaces/core/permissions)).
 
-Registration also runs each component's `onCreated` callback with this record, and registers a permission per component and per component action unless the page opts out ([Permissions](/docs/interfaces/core/permissions)).
+A declaration that the page cannot honour throws `PageDeclarationConflictError` and the page fails to register. `FormPageRouteConflictError` extends it for two page-mode table views that register the same form sub-page.
 
-## Page Access
+## Page access
 
-Registering a page installs an auth decorator on the controller, chosen from the options:
+Registering a page installs an auth decorator on the controller's `user` property, chosen from the options:
 
 | Options | Decorator installed |
 | ------- | ------------------- |
-| `publicAccess: true` | none — the page is served to anonymous callers |
-| `authOnly: true` | `AuthUser` from `@antelopejs/interface-dms/auth`: a logged-in user, no permission check |
-| page under `/modules/` | `AuthOwnerOnly` from `@antelopejs/interface-dms/auth`: module pages are platform-owner-only |
-| default | `AuthUserWithPermission(pageClass)` — the page's own permission ([Permissions](/docs/interfaces/core/permissions)) |
+| `publicAccess: true` | None. The page is served to anonymous callers. |
+| `authOnly: true` | `AuthUser` from `@antelopejs/interface-dms/auth`. A signed-in user, no permission check. |
+| page whose `fullSlug` starts with `/modules/` | `AuthOwnerOnly` from `@antelopejs/interface-dms/auth`. Module pages are for platform owners only. |
+| default | `AuthUserWithPermission(pageClass, { bypassTenantAccessGate })` with the page's own permission ([Permissions](/docs/interfaces/core/permissions#authuserwithpermission)). |
 
-On a page that is neither `publicAccess` nor `authOnly`, registration also binds `roleModel`, `memberModel` and `tenantId` properties on the controller, scoped to the request's tenant ([Tenancy](/docs/interfaces/core/tenancy)). Routes you declare on the page class inherit that gating: a route under a default page already requires the page's permission.
+On a page that is neither `publicAccess` nor `authOnly`, registration also binds `roleModel`, `memberModel` and `tenantId` properties on the controller, scoped to the request's tenant ([Tenancy](/docs/interfaces/core/tenancy)). Routes declared on the page class inherit that gating, so a route on a default page already requires the page's permission.
 
-Declaring the injected property on the class is enough to read it in a handler — the provider runs per request whether or not the handler reads it:
+Declare an injected property on the class to read it in a handler. The provider runs on every request, whether or not the handler reads it:
 
-```typescript
+```typescript fragment
 import { Get } from "@antelopejs/interface-api";
 import {
   PageController,
@@ -490,11 +372,11 @@ export class MyContactsPage extends PageController("mine", {
 }
 ```
 
-## Page Setup Functions
+## Page setup functions
 
-`setupId` names a function that runs while the page is mounted. The backend only carries the id; the function itself is registered on the frontend side and receives a `PageSetupContext`.
+`setupId` names a function that runs while the page is mounted. The backend carries only the id. The frontend registers the function, runs it when the page mounts, and passes it a `PageSetupContext`.
 
-```typescript
+```typescript fragment
 type PageSetupFunction = (
   context: PageSetupContext,
 ) => MaybePromise<PageSetupCleanup | void>;
@@ -502,14 +384,14 @@ type PageSetupFunction = (
 
 | Member of `PageSetupContext` | Description |
 | ---------------------------- | ----------- |
-| `pageInfo` | The `PageInfo` of the page being mounted. |
+| `pageInfo` | The `PageInfo` of the mounted page. |
 | `permissions` | `Set<string>` of the caller's effective permission ids. |
-| `on(component, event, handler)` | Subscribe to a component event. Returns an unsubscribe function. |
-| `emit(component, event, data?)` | Dispatch an event on the shared event bus. |
+| `on(component, event, handler)` | Subscribes to a component event. Returns an unsubscribe function. |
+| `emit(component, event, data?)` | Dispatches an event on the shared event bus. |
 
-`PageSetupCleanup` is `() => void`, returned by the setup function to release what it allocated when the page unmounts. `MaybePromise<T>` is `T | Promise<T>`, re-exported here from `@antelopejs/interface-dms/types`.
+`PageSetupCleanup` is `() => void`. The setup function returns it to release what it allocated, and the frontend calls it when the page unmounts. `MaybePromise<T>` is `T | Promise<T>`, re-exported from `@antelopejs/interface-dms/types`.
 
-```typescript
+```typescript fragment
 import {
   PageController,
   RegisterPage,
@@ -524,27 +406,11 @@ export class LifecyclePage extends PageController("lifecycle", {
 }) {}
 ```
 
-## Ship an Inertia/Vue Frontend Module
-
-`AddFrontendModule(config)` registers a frontend module your module ships. Call it from your module's `construct()`.
+## Frontend modules and request helpers
 
-```typescript
-import path from "node:path";
-import { AddFrontendModule } from "@antelopejs/interface-dms/page";
-
-export async function construct(): Promise<void> {
-  await AddFrontendModule({
-    name: "@acme/dms-billing",
-    sourcePath: path.join(__dirname, "../frontend-vue"),
-    renderer: { name: "vue", version: "3" },
-    configKey: "dmsBilling",
-    priority: 0,
-    options: { prefix: "Billing" },
-  });
-}
-```
+[Frontend modules and request helpers](/docs/interfaces/core/frontend-modules-and-request-helpers) describes the functions a module's backend calls outside page declarations.
 
-The frontend reads the project, not the backend's registrations: `ajs dms dev`, `ajs dms build` and `ajs dms start` call the module's `frontendModule` function, named as `dmsFrontend` in the module's `package.json` (`"dmsFrontend": "dist/frontend-module.js"`). Keep the registration in that pure function of the module's config, and pass its result to `AddFrontendModule`; a module that only calls `AddFrontendModule` is left out of the frontend, in development as in production.
+The frontend reads the project, not the backend's registrations. `ajs dms dev`, `ajs dms build` and `ajs dms start` call the module's `frontendModule` function, which the module's `package.json` names as `dmsFrontend` (`"dmsFrontend": "dist/frontend-module.js"`). Keep the registration in that pure function of the module's config, and pass its result to `AddFrontendModule`. A module that only calls `AddFrontendModule` is left out of the frontend, in development and in production.
 
 ```typescript
 import path from "node:path";
@@ -567,113 +433,20 @@ export const frontendModule: FrontendModuleFunction<BillingConfig> = (
 
 ### `AddFrontendModuleOptions`
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `name` | `string` | Logical frontend module name. Registry identity also includes renderer name and major version. Required. |
-| `sourcePath` | `string` | Absolute path to the frontend module directory. Required. |
-| `renderer` | `FrontendRendererMetadata` | Framework the module is written for, as a name and a version compared by major only. Use `{ name: "vue", version: "3" }` for the Inertia/Vue frontend. The loader releases the module runs on are declared in the `package.json` of `sourcePath` instead ([Frontend layer](/docs/building/frontend-layer#declaring-the-loader-releases-a-module-supports)). |
-| `options` | `Record<string, any>` | Values handed to the layer's configuration. Defaults to `{}`. |
-| `privateOptions` | `Record<string, any>` | A second set of values handed to the layer, kept separate from `options`. Defaults to `{}`. |
-| `priority` | `number` | Ordering among the registered layers. Defaults to `0`. |
-| `configKey` | `string` | Configuration key the layer is published under. |
-| `authEstablishEndpoints` | `string[]` | Backend routes (`/api/…`) the frontend server may open a session from on the module's behalf (its `/auth/establish` route). |
-| `publicEndpoints` | `FrontendPublicEndpoint[]` | Backend routes the module serves to callers outside the dashboard — a provider's webhook. See below. |
-| `backendProxies` | `FrontendBackendProxy[]` | Backend prefixes outside `/api/**` and `/dms/**` the browser reaches through the frontend server (`{ path: "/media/**", auth: "none" }`); `auth` is `"session"` (the default, the session's token added server-side) or `"none"`. A path is `/x`, `/x/*` or `/x/**`, its first segment literal; a malformed entry fails the registration. |
-
-#### Public endpoints
-
-The frontend server's proxy asks every state-changing request for a same-site `Origin` and forwards it with the signed-in user's session, relaying only a few headers. A webhook a mail or payment provider calls through the dashboard's public URL fails both checks. Declare such a route public:
-
-```typescript
-await AddFrontendModule({
-  name: "@acme/dms-mailing",
-  sourcePath: path.join(__dirname, "../frontend-vue"),
-  renderer: { name: "vue", version: "3" },
-  publicEndpoints: [
-    {
-      path: "/api/mailing/events/*/*",
-      methods: ["POST"],
-      headers: ["x-mailing-webhook-secret"],
-    },
-  ],
-});
-```
-
-A request to a declared route needs no `Origin`, carries the declared headers, and is **never sent the session**, even from a signed-in browser: a cross-site form posting to it acts as nobody, and the route authenticates its caller itself (a shared secret, a signature). `path` is absolute under `/api/`, its first segment literal (the module's own prefix, never `*`), each later `*` matching exactly one segment; `methods` defaults to `["POST"]`; `headers` names the module's own `x-` headers, those a proxy or the DMS gives a meaning to (`x-forwarded-*`, `x-real-ip`, `x-dms-*`, `x-inertia*`, method overrides) being refused. A malformed entry fails the registration. The declarations reach the frontend server through the manifest it is built from (an authenticated build only), and its `DMS_PUBLIC_ENDPOINTS` adds routes no module declares. It needs `@antelopejs/dms-frontend` with public endpoint support; an older one ignores the field.
-
-Within one logical name, renderer, and major version, the highest-priority
-registration wins. Equal-priority registrations use the latest registration.
-The manifest and archive endpoints select one renderer with the paired
-`renderer` and `rendererVersion` query parameters. The version is matched by
-major version; unsupported selections return 404 rather than mixing renderer
-sources. Omitting both parameters remains an alias for Vue 3 clients.
-
-## Stamp Upload Tokens
-
-`StampUploadFieldTokens(options)` takes a component's serialized options and returns them with a signed upload token stamped into every file and image field — the component's own fields, and the forms it embeds (a relation field's inline add form, a table view's `new` / `edit` / `view` forms) — binding each field to the storage and path it declares so a client cannot presign an upload elsewhere. The builders that carry upload fields attach it through `transformOptions`, and page registration stamps the authoritative declaration, so pages you declare with `@RegisterPage()` are covered already. Call it yourself only when you serialize and serve components outside that path: a token produced outside a registered page stays unbound and cannot authorize an upload.
-
-```typescript
-import { StampUploadFieldTokens } from "@antelopejs/interface-dms/uploads";
-
-const components = await StampUploadFieldTokens(layout.components);
-```
-
-Options holding no upload field come back untouched; otherwise the return value is a deep clone, since serialization runs again on a hot reload and each pass must start from the untransformed declaration.
-
-## Public URLs
-
-`GetApiBaseUrl()` and `GetClientBaseUrl()` answer the public origins of the DMS API and of the dashboard, from the DMS configuration (`apiBaseUrl`, `clientBaseUrl`); under `ajs dms dev` they follow the dev server's origins. Build an absolute link on them rather than on the request's headers: behind a reverse proxy that forwards no `X-Forwarded-Host`, the request only knows the internal host.
-
-```typescript
-import { GetApiBaseUrl } from "@antelopejs/interface-dms/api-base-url";
-import { GetClientBaseUrl } from "@antelopejs/interface-dms/client-base-url";
-
-const apiBase = await GetApiBaseUrl(); // "https://api.example.com"
-const downloadUrl = `${apiBase}/i18n/site/fr.json`;
-const inviteUrl = `${await GetClientBaseUrl()}/auth/signup`;
-```
-
-Both return `string | undefined`: `undefined` only when the configuration clears the value.
-
-## Client address
-
-`getClientIp(context)` answers the address a request came from, resolved the way the DMS resolves the one it records on a session: behind the `auth.trustedProxies` reverse proxies of its configuration ([Client address behind proxies](/docs/building/configuration#client-address-behind-proxies)), each trusted hop vouching for the `x-forwarded-for` entry it appended and nothing left of it, and an IPv4-mapped address (`::ffff:10.0.0.1`) written as plain IPv4. Key a rate limit or an anonymous visitor on it rather than on `x-forwarded-for` read by hand: the operator declares the proxies once, for the DMS and every module.
-
-```typescript
-import { Context, Controller, Post, type RequestContext } from "@antelopejs/interface-api";
-import { getClientIp } from "@antelopejs/interface-dms/client-ip";
-
-export class CollectController extends Controller("/api/collect") {
-  @Context()
-  declare requestContext: RequestContext;
-
-  @Post("/")
-  async collect(): Promise<void> {
-    const address = await getClientIp(this.requestContext); // "109.132.199.8"
-  }
-}
-```
-
-It answers an empty string when the request carries no address. `ResolveClientIp({ socketAddress, forwardedFor })` is the same resolution on values a module already holds, a request it queued for later say.
+The options of `AddFrontendModule`, which registers the frontend a module ships, are listed in [`AddFrontendModuleOptions`](/docs/interfaces/core/frontend-modules-and-request-helpers#addfrontendmoduleoptions).
 
-## `SaveComponentFiles`
+### Public URLs
 
-`SaveComponentFiles<T>(request: AttachmentSaveRequest, save: (promoted: Record<string, unknown>) => Promise<AttachmentSaveResult<T>>): Promise<T>` comes from `@antelopejs/interface-dms/attachments`. Call it from an authorized write route to validate native-file provenance, promote staging keys, and persist through `save`. The [file-storage guide](/docs/components/file-storage) covers the form/upload flow and storage authorization.
+`GetApiBaseUrl()` and `GetClientBaseUrl()` are described in [Public URLs](/docs/interfaces/core/frontend-modules-and-request-helpers#public-urls).
 
-`AttachmentSaveRequest` contains:
+### Client address
 
-| Field | Type | Contract |
-| --- | --- | --- |
-| `context` | `RequestContext` | The authorized server request. |
-| `componentIds` | `string[]` | Trusted component identities, not ids supplied by the client. |
-| `fields` | `AttachmentField[]` | Server-declared attachment fields. |
-| `submitted` | `Record<string, unknown>` | The submitted values. |
-| `before` | `Record<string, unknown>` | Previously persisted values, loaded by the server. |
+`getClientIp(context)` and `ResolveClientIp(source)` are described in [Client address](/docs/interfaces/core/frontend-modules-and-request-helpers#client-address).
 
-Each `AttachmentField` has `id` (matching the form's `attachmentField`), `key` (the document field), and `kind: "file" | "image"`. Optional `storage`, `visibility: "private" | "public"`, and `constraints: UploadConstraints` select the provider and upload policy; `UploadConstraints` comes from `@antelopejs/interface-file-storage`.
+### `SaveComponentFiles`
 
-The callback returns `AttachmentSaveResult<T>`: `{ document, result }`, where `document` contains the actual saved values used for cleanup, and `result` is returned to the caller. Removed native files are cleaned only after successful persistence; cleanup failures are logged. Failed saves leave promoted objects intact because another save may reference them. Cleanup is not reference-counted: callers must avoid unsafe sharing of file keys. Internal attachment validators and TableView save proxies are not consumer entry points.
+`SaveComponentFiles` is described in [`SaveComponentFiles`](/docs/interfaces/core/frontend-modules-and-request-helpers#savecomponentfiles).
 
-## Next Steps
+## Next steps
 
-[Components](/docs/interfaces/core/components) covers the builders that produce the values you assign to those static fields.
+[Components](/docs/interfaces/core/components) covers the builders that produce the values you assign to those static fields. [Modules and dynamic menus](/docs/interfaces/core/modules-and-dynamic-menus) covers module roots and per-request menu entries.