@antelopejs/interface-dms 0.7.1 → 0.7.2

package/docs/5.html-render/1.introduction.md

@@ -0,0 +1,372 @@
+---
+title: "Introduction"
+description: "Turn a named template and a props object into an HTML string, rendered by the frontend and delivered by your code — as an email, a file or a response."
+---
+
+# Introduction
+
+## Overview
+
+The `html-render` domain of `@antelopejs/interface-dms` turns a named template plus a props object into an HTML string. You declare a template once with `RegisterHtmlTemplate`, which records the name in a process-wide registry and hands back a typed reference; passing that reference to `GenerateHtml` produces the rendered HTML.
+
+Rendering itself does not happen in the backend process. `GenerateHtml` performs an HTTP `POST` to the render endpoint configured on the DMS (`htmlRender.renderEndpoint`), authenticated with a signed service token, and returns the HTML the endpoint sends back. The backend therefore owns the template *names* and the props *types*; the markup lives with the renderer behind that endpoint.
+
+The interface produces HTML and nothing else. Delivering that HTML — as a transactional email, as a file, as a response body — is your code's job.
+
+Everything below is exported from a single subpath:
+
+```typescript
+import {
+  GenerateHtml,
+  GetAllHtmlTemplates,
+  GetHtmlTemplate,
+  RegisterHtmlTemplate,
+} from "@antelopejs/interface-dms/html-render";
+import type {
+  HtmlRenderConfig,
+  HtmlTemplateInfo,
+  HtmlTemplateRef,
+} from "@antelopejs/interface-dms/html-render";
+```
+
+## Key Features
+
+- **Named template registry** — `RegisterHtmlTemplate` records a template name at import time, so the whole process shares one catalogue of renderable templates.
+- **Documented props** — the type parameter on `RegisterHtmlTemplate` travels with the returned `HtmlTemplateRef`, recording on the reference itself which props the template expects.
+- **Remote rendering over HTTP** — `GenerateHtml` calls the configured render endpoint with a signed service token and resolves to the returned HTML string.
+- **Registry inspection** — `GetHtmlTemplate` and `GetAllHtmlTemplates` read back what has been registered, one name at a time or in bulk.
+- **Configurable endpoint and token** — `HtmlRenderConfig` types the `htmlRender` block of the DMS module configuration: endpoint URL, signing secret, token lifetime.
+
+## Dependencies
+
+This interface relies on the following AntelopeJS packages:
+
+- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - `InterfaceFunction` and `RegisteringProxy`, the primitives the interface is built from.
+
+## Quick Start
+
+Register a template next to the code that uses it, then render it with props.
+
+```typescript
+import {
+  GenerateHtml,
+  RegisterHtmlTemplate,
+} from "@antelopejs/interface-dms/html-render";
+
+interface WelcomeProps {
+  userName: string;
+  activationLink: string;
+}
+
+// Registration happens at import time; keep the ref in module scope.
+const WelcomeTemplate = RegisterHtmlTemplate<WelcomeProps>("EmailWelcome");
+
+export async function buildWelcomeHtml(
+  userName: string,
+  activationLink: string,
+): Promise<string> {
+  return GenerateHtml(WelcomeTemplate, { userName, activationLink });
+}
+```
+
+`GenerateHtml` needs the render endpoint to be reachable, so it belongs in request or job code — do not call it at import time.
+
+## RegisterHtmlTemplate
+
+Registers a template name and returns the reference you render with.
+
+```typescript
+function RegisterHtmlTemplate<TProps = unknown>(
+  name: string,
+): HtmlTemplateRef<TProps>;
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `name` | The template identifier. It is the key the registry stores the template under, and the `templateName` sent to the render endpoint. |
+
+The type parameter `TProps` declares the props the template expects. It is carried by the returned [`HtmlTemplateRef`](#htmltemplateref) as a record of the template's shape; [`GenerateHtml`](#generatehtml) takes its `props` argument as `unknown`, so the compiler does not check the two against each other at the call site. Omitting `TProps` leaves the reference's props type as `unknown`.
+
+```typescript
+import { RegisterHtmlTemplate } from "@antelopejs/interface-dms/html-render";
+
+interface InvoiceProps {
+  invoiceNumber: string;
+  amount: string;
+  dueDate: string;
+}
+
+export const InvoiceTemplate =
+  RegisterHtmlTemplate<InvoiceProps>("EmailInvoice");
+```
+
+The registry is keyed by name, so registering an existing name replaces the earlier entry. The DMS registers seven names for its own emails, listed in [Built-in Emails](/docs/interfaces/html-render/built-in-emails) — pick different names for your templates.
+
+Call `RegisterHtmlTemplate` at module scope, in a file your module imports during startup. The returned reference is a plain object, so exporting it from that module is the usual way to share it.
+
+The subpath also exports an `internal` namespace holding the registering proxy this function writes through. It is implementation detail — register through `RegisterHtmlTemplate`.
+
+## GenerateHtml
+
+Renders a registered template and resolves to the resulting HTML.
+
+```typescript
+const GenerateHtml: (
+  template: HtmlTemplateRef<unknown>,
+  props: unknown,
+) => Promise<string>;
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `template` | The reference returned by `RegisterHtmlTemplate`. Pass the reference, not the name string. |
+| `props` | The data the template renders with, serialised into the request body. The render endpoint expects a JSON object and rejects anything else with a `400`, so keep the props type an object shape. Typed `unknown` at this boundary, so the props type recorded on the reference is not enforced here — match it yourself. |
+
+```typescript
+import { GenerateHtml } from "@antelopejs/interface-dms/html-render";
+import { InvoiceTemplate } from "./templates";
+
+export async function renderInvoice(invoiceNumber: string): Promise<string> {
+  return GenerateHtml(InvoiceTemplate, {
+    invoiceNumber,
+    amount: "240.00 EUR",
+    dueDate: "2026-08-15",
+  });
+}
+```
+
+The call `POST`s `{ templateName, props }` as JSON to `htmlRender.renderEndpoint`, with a service token signed from `htmlRender.serviceSecret` in the `x-dms-service-token` header, and reads the `html` field out of the JSON response.
+
+`GenerateHtml` does not consult the registry before calling out: it sends whatever name the reference carries. A name the render endpoint does not know surfaces as a rejected promise, not as a missing-template check on the backend.
+
+On a non-2xx response the promise rejects with an `Error` whose message starts with `Failed to render HTML template:`, followed by the response body's `error` string, its `statusMessage`, or `HTTP <status>`. When the endpoint is unreachable the underlying `fetch` failure propagates instead, without that prefix. Wrap the call when a failed render must not abort the surrounding operation:
+
+```typescript
+import { Logging } from "@antelopejs/interface-core/logging";
+import { GenerateHtml } from "@antelopejs/interface-dms/html-render";
+import { InvoiceTemplate } from "./templates";
+
+export async function renderInvoiceOrNull(
+  invoiceNumber: string,
+): Promise<string | null> {
+  try {
+    return await GenerateHtml(InvoiceTemplate, {
+      invoiceNumber,
+      amount: "240.00 EUR",
+      dueDate: "2026-08-15",
+    });
+  } catch (error) {
+    Logging.Error(`Invoice render failed: ${(error as Error).message}`);
+    return null;
+  }
+}
+```
+
+## GetHtmlTemplate
+
+Looks a single template up in the registry.
+
+```typescript
+const GetHtmlTemplate: (key: string) => Promise<HtmlTemplateInfo | undefined>;
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `key` | The name the template was registered under. |
+
+Resolves to the [`HtmlTemplateInfo`](#htmltemplateinfo) stored for that name, or to `undefined` when nothing is registered under it.
+
+```typescript
+import { GetHtmlTemplate } from "@antelopejs/interface-dms/html-render";
+
+export async function isTemplateRegistered(name: string): Promise<boolean> {
+  return (await GetHtmlTemplate(name)) !== undefined;
+}
+```
+
+## GetAllHtmlTemplates
+
+Resolves to every registered template, keyed by name.
+
+```typescript
+const GetAllHtmlTemplates: () => Promise<Record<string, HtmlTemplateInfo>>;
+```
+
+```typescript
+import { GetAllHtmlTemplates } from "@antelopejs/interface-dms/html-render";
+
+export async function listTemplateNames(): Promise<string[]> {
+  return Object.keys(await GetAllHtmlTemplates());
+}
+```
+
+The result is a fresh object built from the registry, so mutating it does not change what is registered. Because registration happens as modules are imported, call this after startup rather than at import time if you want the complete set.
+
+## HtmlTemplateInfo
+
+What the registry stores for each template, and what `GetHtmlTemplate` and `GetAllHtmlTemplates` resolve to.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | The registered template name. |
+
+```typescript
+import type { HtmlTemplateInfo } from "@antelopejs/interface-dms/html-render";
+import { GetAllHtmlTemplates } from "@antelopejs/interface-dms/html-render";
+
+export async function describeTemplates(): Promise<string> {
+  const templates: Record<string, HtmlTemplateInfo> =
+    await GetAllHtmlTemplates();
+
+  return Object.values(templates)
+    .map((info) => info.name)
+    .join(", ");
+}
+```
+
+## HtmlTemplateRef
+
+The handle `RegisterHtmlTemplate` returns and `GenerateHtml` accepts.
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | The template name sent to the render endpoint. |
+| `_propsType` | `TProps \| undefined` | Type-only carrier for the props type. It is never assigned a value; do not read it. |
+
+Annotate the reference explicitly when you collect handles in a shared module and want the props type visible in that module's declarations:
+
+```typescript
+import type { HtmlTemplateRef } from "@antelopejs/interface-dms/html-render";
+import { RegisterHtmlTemplate } from "@antelopejs/interface-dms/html-render";
+
+interface AlertProps {
+  title: string;
+  body: string;
+}
+
+export const AlertTemplate: HtmlTemplateRef<AlertProps> =
+  RegisterHtmlTemplate<AlertProps>("EmailAlert");
+```
+
+## HtmlRenderConfig
+
+Types the `htmlRender` block of the DMS module configuration in `antelope.config.ts`.
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `renderEndpoint` | `string` | Absolute URL `GenerateHtml` posts to. Default `http://localhost:3001/api/html/render`. |
+| `serviceSecret` | `string` | Secret used to sign the service token that authenticates the render call. Default `"dev"` — set a strong value in production. |
+| `serviceTokenLifetime` | `number` | Lifetime of that service token, in milliseconds. The frontend render server rejects a token valid for more than five minutes. Default `300000` (5 minutes). |
+
+The DMS merges the block you supply over those defaults, so a configuration only needs the keys it changes:
+
+```typescript
+import { defineConfig } from "@antelopejs/interface-core/config";
+
+const renderSecret = process.env.DMS_HTML_RENDER_SECRET;
+if (!renderSecret) {
+  throw new Error("DMS_HTML_RENDER_SECRET is not set");
+}
+
+export default defineConfig({
+  name: "acme-admin",
+  modules: {
+    dms: {
+      source: {
+        type: "package",
+        package: "@antelopejs/dms",
+        version: ">=0.4.3 <1.0.0",
+      },
+      config: {
+        htmlRender: {
+          renderEndpoint: "https://admin.example.com/api/html/render",
+          serviceSecret: renderSecret,
+        },
+      },
+    },
+  },
+});
+```
+
+The Configuration chapter of the DMS guide covers where this block sits alongside the other DMS options.
+
+## Email Layout
+
+The DMS ships the frame of its own emails as `EmailLayout`, which a module's email template (registered through `dms.email.ts`) may reuse: the branding logo, a card, an optional heading and a `footer` slot below a separator.
+
+```vue
+<script setup lang="ts">
+import EmailLayout from "#dms-layout/app/emails/components/EmailLayout.vue";
+
+defineProps<{ subject: string; preheader: string; locale: string }>();
+</script>
+
+<template>
+  <EmailLayout
+    :lang="locale"
+    :preheader="preheader"
+    :divider="false"
+    public-logo-only
+  >
+    <template #head>
+      <title>{{ subject }}</title>
+    </template>
+    <EText>Your order has shipped.</EText>
+    <template #footer>
+      <EText>Acme Inc.</EText>
+    </template>
+  </EmailLayout>
+</template>
+```
+
+| Prop | Type | Description |
+| ---- | ---- | ----------- |
+| `title` | `string` (optional) | Drawn as the `h1` heading. Without it the email has no heading. |
+| `lang` | `string` (optional) | The `lang` of the document. Default `"en"`. |
+| `preheader` | `string` (optional) | Inbox preview text, hidden in the body. |
+| `divider` | `boolean` (optional) | Draws the separator above the `footer` slot. Default `true`. |
+| `logoAlt` | `string` (optional) | Alternative text of the logo. Default `"Logo"`; pass `""` for a decorative logo. |
+| `publicLogoOnly` | `boolean` (optional) | Leaves the logo out unless a mail client can load it (see below). Default `false`. |
+
+The `head` slot adds elements to the document head (a `<title>`, a viewport `<meta>`).
+
+The logo is `branding.logo.email.light` from the app config, or `branding.logo.default.light` without an email logo, made absolute against `public.dms.clientBaseUrl` when it starts with `/`. A recipient's mail client fetches it from the internet, and Gmail and Outlook refuse SVG: with `publicLogoOnly`, the layout leaves the logo out when it is an SVG, is not an `http(s)` URL, or is served from a host a mail client cannot reach (`localhost`, `*.local`, `*.internal`, a loopback, private or link-local address), rather than drawing a broken image. Set a PNG logo and a public `clientBaseUrl` for it to show. A `branding.logo.email.dark` goes through the same rules and, when it differs from the light one, is offered to the mail clients in dark mode: the logo is then drawn as `<picture><source media="(prefers-color-scheme: dark)" srcset="…"><img …></picture>`, and a client that ignores the source draws the light image. The same check is exported as `emailLogoUrl(logoPath, clientBaseUrl)` from `#dms-layout/app/emails/components/index`, for a template that draws its own header.
+
+## Sending Rendered HTML as Email
+
+Rendering and sending are separate steps. Render with `GenerateHtml`, then hand the string to the standard AntelopeJS email interface, which needs an implementing module (such as `@antelopejs/nodemailer`) loaded in your project configuration.
+
+```typescript
+import { Send } from "@antelopejs/interface-email";
+import {
+  GenerateHtml,
+  RegisterHtmlTemplate,
+} from "@antelopejs/interface-dms/html-render";
+
+interface ReceiptProps {
+  userName: string;
+  orderId: string;
+}
+
+const ReceiptTemplate = RegisterHtmlTemplate<ReceiptProps>("EmailReceipt");
+
+export async function sendReceipt(
+  email: string,
+  userName: string,
+  orderId: string,
+): Promise<void> {
+  const html = await GenerateHtml(ReceiptTemplate, { userName, orderId });
+
+  const result = await Send({
+    to: email,
+    subject: `Your receipt for order ${orderId}`,
+    html,
+  });
+
+  if (!result.success) {
+    throw new Error(`Failed to send receipt: ${result.error?.message}`);
+  }
+}
+```
+
+This is the shape the DMS uses for its own account emails, and it keeps the two failure modes apart: a rejected `GenerateHtml` means the HTML was never produced, while a `success: false` response from `Send` means it was produced but not delivered.

package/docs/5.html-render/2.built-in-emails.md

@@ -0,0 +1,107 @@
+---
+title: "Built-in Emails"
+description: "The DMS sends seven emails of its own."
+---
+
+# Built-in Emails
+
+## Overview
+
+The DMS sends seven emails of its own. Each one is a template registered through [`RegisterHtmlTemplate`](/docs/interfaces/html-render/introduction#registerhtmltemplate), rendered by the frontend server from a Vue component in `frontend-vue/layers/dms-layout/app/emails/`, and delivered through `@antelopejs/interface-email`. They share one frame, `EmailLayout`: the branding logo, a white card, a heading, the body, a separator and a footer.
+
+| Template | Sent when | Sent to | English subject |
+| -------- | --------- | ------- | ------- |
+| `EmailUserValidation` | A user signs up while `auth.mustValidateEmail` is on, or asks for a new code | The new account's address | `Verify Your Email` |
+| `EmailResetPassword` | A user asks for a password reset | The account's address | `Reset Your Password` |
+| `EmailTwoFactor` | A user signs in with email as their second factor | The account's address | `Your verification code` |
+| `EmailAdminInvite` | A member is invited to the platform or to a workspace | The invited address | `You're invited to join <workspace> on <platform>`, shorter when a name is unknown |
+| `EmailChangeVerification` | A user asks to change their sign-in email | The new address | `Confirm your new sign-in email` |
+| `EmailChangeNotice` | The same request | The current address | `Your sign-in email is being changed` |
+| `EmailExportReady` | A data export delivered by email has finished | The user who asked for it | `Your data export is ready` |
+
+Each email, subject included, is written in the recipient's language, English or French (see [Language](#language)).
+
+These names are taken: pick other names for your own emails. To change what a built-in email looks like, see [Replacing a built-in email](#replacing-a-built-in-email).
+
+## Props
+
+What the backend passes to each template. A template that replaces a built-in one receives the same props.
+
+| Template | Props |
+| -------- | ----- |
+| `EmailUserValidation` | `userName`, `validationCode`, `expiresInHours` (from `auth.emailValidationTokenLifetime`), `expiresIn` |
+| `EmailResetPassword` | `userName`, `resetCode`, `expiresInHours` (from `auth.passwordRecoverTokenLifetime`), `expiresIn` |
+| `EmailTwoFactor` | `userName`, `verificationCode` |
+| `EmailAdminInvite` | `email`, `signupLink`, `expiresInDays`, and when known `workspaceName`, `inviterName`, `platformName` (`meta.title`) |
+| `EmailChangeVerification` | `userName`, `newEmail`, `code`, `expiresInHours` (from `auth.emailValidationTokenLifetime`), `expiresIn` |
+| `EmailChangeNotice` | `userName`, `newEmail` |
+| `EmailExportReady` | `userName`, `downloadLink`, `expiresInHours`, `expiresIn`, `partial`, `failedSources` (the export sources that could not be included) |
+
+`userName` is the user's name, or their email address when they have none. `expiresInHours` is the lifetime as a number, for the template to word in the recipient's language; `expiresIn` is the same lifetime already worded in English (`24 hours`), kept for templates written before `expiresInHours`.
+
+## Language
+
+Each email is written in the recipient's language: the account's `language`, or for an invitation the language it was sent in. English and French are supported; any other language falls back to English.
+
+The body text lives in the `dms-layout` locale files (`i18n/locales/layout-*.json`), under one key per email (`emails.user_validation`, `emails.reset_password`, `emails.two_factor`, `emails.admin_invite`, `emails.email_change_verification`, `emails.email_change_notice`, `emails.export_ready`) plus the shared `emails.common`. Locale files merge in module priority order, so a module registered with a priority above the DMS's (`0`) can reword any of these keys in its own `i18n/locales/*.json`:
+
+```json [frontend-vue/i18n/locales/acme-en-GB.json]
+{
+  "emails": {
+    "reset_password": {
+      "footer": "Didn't ask for this? Contact support@acme.test."
+    }
+  }
+}
+```
+
+The subject is set by the backend, which sends it in the same language. It cannot be reworded from a module.
+
+## Logo
+
+Every built-in email draws `branding.logo.email.light` from the app config, or `branding.logo.default.light` when no email logo is set (see [Email Layout](/docs/interfaces/html-render/introduction#email-layout)), with `publicLogoOnly` on. The logo shows only when a mail client can load it: a PNG or JPEG served from a public `http(s)` address. The default DMS logo is an SVG, which Gmail and Outlook refuse, so out of the box the emails carry no logo. To show yours, set an `email` logo in your layer's `app/app.config.ts`, and serve the dashboard from a public `clientBaseUrl`:
+
+```ts [frontend-vue/app/app.config.ts]
+export default defineDmsAppConfig({
+  branding: {
+    logo: {
+      email: {
+        light: "/branding/logo-email.png",
+        dark: "/branding/logo-email-dark.png",
+      },
+    },
+  },
+});
+```
+
+The loader hands every layer's `app/app.config.ts` to the email renderer too (`@antelopejs/dms-frontend` 0.6.0 or later), merged in module priority order, so a module registered with a priority above the DMS's (`0`) wins. `dark` is optional: when it passes the same check and differs from `light`, the header becomes a `<picture>` whose dark source the mail clients that follow the reader's dark mode pick, and the others draw `light`.
+
+## Replacing a built-in email
+
+The render server looks a template up by its file name, in module priority order, and renders the first match. A module registered with a `priority` above the DMS's (`0`, see [`AddFrontendModule`](/docs/interfaces/core/pages-and-modules#addfrontendmoduleoptions)) therefore replaces a built-in email by shipping a component of the same name in its `dms.email.ts`:
+
+```ts [frontend-vue/dms.email.ts]
+export const serverEmailTemplates = import.meta.glob("./app/emails/**/*.vue");
+```
+
+```vue [frontend-vue/app/emails/EmailResetPassword.vue]
+<script setup lang="ts">
+import { useI18n } from "vue-i18n";
+import EmailLayout from "#dms-layout/app/emails/components/EmailLayout.vue";
+import EmailOTP from "#dms-layout/app/emails/components/EmailOTP.vue";
+
+defineProps<{ userName: string; resetCode: string; expiresInHours: number }>();
+
+const { t, locale } = useI18n();
+</script>
+
+<template>
+  <EmailLayout :title="t('emails.reset_password.title')" :lang="locale" public-logo-only>
+    <EText>{{ t("emails.common.greeting", { name: userName }) }}</EText>
+    <EText>Use this code to choose a new Acme password:</EText>
+    <EmailOTP :code="resetCode" :expires-in="t('emails.common.hours', expiresInHours)" />
+  </EmailLayout>
+</template>
+```
+
+The replacement receives the props listed in [Props](#props) and keeps the backend's subject. Do not register the name again with `RegisterHtmlTemplate`: the DMS already sends it. At equal priority the first module by id wins, so set the priority explicitly rather than relying on it.

package/docs/index.md

@@ -0,0 +1,100 @@
+---
+title: "The DMS interface"
+description: "One public package, @antelopejs/interface-dms, holds every contract a module uses — its subpaths, domain by domain."
+---
+
+# The DMS interface
+
+## Overview
+
+The DMS ships one public AntelopeJS interface package, `@antelopejs/interface-dms`. Everything a module needs to declare pages, build components, authenticate a request, send a notification or render an HTML template comes from that single package, through a subpath named after the domain it belongs to. Never reach the surface through the runtime package `@antelopejs/dms`.
+
+```json
+{
+  "dependencies": {
+    "@antelopejs/interface-dms": ">=0.0.1 <1.0.0"
+  }
+}
+```
+
+This section is the contract reference: the exact symbol names, options and return types, grouped by domain. The DMS guide covers the same ground task by task, organised around what you are building.
+
+Separately published extension interfaces have their own [module interface references](/docs/modules#interface-references), including Builder. This page covers `@antelopejs/interface-dms` itself.
+
+## One installed copy
+
+The host and every module must resolve **the same installed copy** of `@antelopejs/interface-dms`. The package holds live state, not just types: the page, category and extension registries, the permission tree, the hook registry, the data-type and block registries and the component slot resolvers. A second copy gets its own empty registries: pages register into a tree nobody reads, permissions never reach the roles form, and hooks never fire, without any error. `@antelopejs/core` checks this before constructing modules and fails with `Incompatible interface package resolution` when a module resolves another copy.
+
+Depend on the package with a wide range, raising the lower bound to the version you need rather than pinning an upper one, so package managers can deduplicate, and never vendor or bundle it into a module. `@antelopejs/dms`, which implements the interface, is the exception: it caps its range below the next minor, so a breaking minor never reaches an older DMS.
+
+The runtime also hands a module a per-context view of the values it receives through an interface, so reference equality does not survive the round trip. Compare registrations on a field, never with `===`, and compare plain data rather than the views themselves: `isDeepStrictEqual` and `assert.deepStrictEqual` refuse two views that hold equal values.
+
+## The Domains
+
+| Domain | What it is for | Import prefix |
+| ------ | -------------- | ------------- |
+| [Core](/docs/interfaces/core/introduction) | Pages, modules, components, permissions, tenancy, invites, hooks, realtime, quick actions and layout banners. | `@antelopejs/interface-dms` and its root-level subpaths |
+| [Auth](/docs/interfaces/auth/introduction) | Authentication decorators, token and session handling, and the user and session tables. | `@antelopejs/interface-dms/auth` |
+| [Base](/docs/interfaces/base/introduction) | The component vocabulary: forms, tables, charts, layout, trees, data types and the shared prop types. | `@antelopejs/interface-dms/base` |
+| [Notifications](/docs/interfaces/notifications/introduction) | Declaring notification categories and subjects, and building and sending notifications. | `@antelopejs/interface-dms/notifications` |
+| [HTML Render](/docs/interfaces/html-render/introduction) | Registering HTML templates and rendering them server-side. | `@antelopejs/interface-dms/html-render` |
+
+Start with [Core](/docs/interfaces/core/introduction) and [Base](/docs/interfaces/base/introduction): the first declares pages and the components they carry as serializable data, the second is the concrete set of components you fill those pages with. [Auth](/docs/interfaces/auth/introduction) resolves a request to a user, which the permission and tenant guards build on. The remaining two stand on their own and are used where you need them.
+
+## Subpath Map
+
+Each subpath is its own entry point: importing one does not pull the others in, and the modules that register schemas or controllers as they evaluate are deliberately kept off the root barrel. Every domain's introduction carries the detailed map of its own subpaths; this is the whole set at a glance.
+
+| Subpath | Holds | Domain |
+| ------- | ----- | ------ |
+| `@antelopejs/interface-dms` | The root barrel over the core surface below | [Core](/docs/interfaces/core/introduction) |
+| `/page` | Pages, categories, modules, layouts, page extensions, dynamic menus, frontend modules | [Core](/docs/interfaces/core/pages-and-modules) |
+| `/component` | `Component`, `ComponentBuilder`, actions, watches | [Core](/docs/interfaces/core/components) |
+| `/component-slots` | `RegisterComponentSlot`, `ComponentSlotResolver`, `SlotOptions` | [Core](/docs/interfaces/core/components#registercomponentslot) |
+| `/attachments` | `SaveComponentFiles` and its request, field and result types | [Core](/docs/interfaces/core/pages-and-modules#savecomponentfiles) |
+| `/permission-gate` | Shared `PermissionGate` fields for permission-filtered UI | [Base](/docs/interfaces/base/types#permissiongate) |
+| `/permissions` | The permission registry and the permission computation | [Core](/docs/interfaces/core/permissions) |
+| `/permissions-resolver` | Registering and running permission resolvers | [Core](/docs/interfaces/core/permissions) |
+| `/guards` | `AuthUserWithPermission`, `AuthTenantOwner`, `AuthTenantMember` | [Core](/docs/interfaces/core/permissions) |
+| `/constants` | Schema names and the default tenant | [Core](/docs/interfaces/core/tenancy) |
+| `/db`, `/db/models`, `/db/tables` | The `Tenant`, `TenantMember`, `Role` and `UserInvite` tables and models | [Core](/docs/interfaces/core/tenancy) |
+| `/request-tenant` | `getRequestTenantId` | [Core](/docs/interfaces/core/tenancy) |
+| `/tenant-scoped-model` | `TenantScopedModel` | [Core](/docs/interfaces/core/tenancy) |
+| `/tenant-access` | Tenant access gates | [Core](/docs/interfaces/core/tenancy) |
+| `/tenant-ownership` | Membership and ownership writes | [Core](/docs/interfaces/core/tenancy) |
+| `/tenant-lifecycle` | Producer admission and permanent closure before tenant deletion | [Core](/docs/interfaces/core/tenancy#tenant-lifecycle-admission) |
+| `/data-controllers` | The built-in members and roles data controllers | [Core](/docs/interfaces/core/tenancy) |
+| `/invites` | Inviting a user into a tenant | [Core](/docs/interfaces/core/invites) |
+| `/invite-extensions` | Invite form contributions, validation, delivery and availability | [Core](/docs/interfaces/core/invites#registerinviteextension) |
+| `/invite-resolution` | Durable terminal decisions and retryable invite effects | [Core](/docs/interfaces/core/invites#durable-invite-resolution) |
+| `/hooks` | The `Hook` enum, handlers and dispatch | [Core](/docs/interfaces/core/hooks) |
+| `/tenant-export` | The tenant export archive, contribution and manifest types | [Core](/docs/interfaces/core/hooks) |
+| `/realtime` | Page topics, publishing and backend subscription | [Core](/docs/interfaces/core/realtime) |
+| `/quick-actions` | Command-palette entries | [Core](/docs/interfaces/core/quick-actions) |
+| `/layout-banners` | Global banners under the dashboard header | [Core](/docs/interfaces/core/layout-banners) |
+| `/uploads` | Signed upload tokens for the file and image fields of a serialized component | [Core](/docs/interfaces/core/pages-and-modules) |
+| `/types` | `MaybePromise`, the one shared type alias | [Core](/docs/interfaces/core/pages-and-modules) |
+| `/api-base-url`, `/client-base-url` | `GetApiBaseUrl`, `GetClientBaseUrl`: the public origins of the API and the dashboard | [Core](/docs/interfaces/core/pages-and-modules#public-urls) |
+| `/client-ip` | `getClientIp`, `ResolveClientIp`: a request's client address behind the trusted proxies | [Core](/docs/interfaces/core/pages-and-modules#client-address) |
+| `/auth` | Authentication decorators, tokens, sessions, external identities, account mail | [Auth](/docs/interfaces/auth/introduction) |
+| `/auth/db`, `/auth/db/models`, `/auth/db/tables` | The `User`, `Session` and `UserExternalIdentity` tables and models | [Auth](/docs/interfaces/auth/users) |
+| `/base` | The component barrel: forms, tables, charts, cards, layout, trees | [Base](/docs/interfaces/base/introduction) |
+| `/base/types` | Base props, colours, sizes, buttons, action targets, row-action rules, guards | [Base](/docs/interfaces/base/types) |
+| `/base/form` | `Form`, the field and group shapes, `FormComponents`, `FormEvents`, the schema helpers | [Base](/docs/interfaces/base/forms) |
+| `/base/table-view` | `TableView`, `@Column`, `TableViewRoutes`, guards, row actions | [Base](/docs/interfaces/base/tables) |
+| `/base/data-types` | `DataType`, the registration decorators, `DefaultDataTypes`, `DefaultDataCompareTypes`, `StatusType` | [Base](/docs/interfaces/base/data-types) |
+| `/base/…` | The per-component subpaths — `chart`, `grid`, `stack`, `tab`, `tree`, `custom`, `layouts`, `helpers/…` | [Base](/docs/interfaces/base/introduction) |
+| `/notifications`, `/notifications/types` | Categories, subjects, the notification builder and its dispatch targets | [Notifications](/docs/interfaces/notifications/introduction) |
+| `/html-render` | `RegisterHtmlTemplate`, `GenerateHtml` and the template reference types | [HTML Render](/docs/interfaces/html-render/introduction) |
+
+Beyond these entry points, built files are importable through the `./*` export (`@antelopejs/interface-dms/base/form-types`). Moving or renaming a public path is a breaking change, like removing an export.
+
+Importability does not make a declaration public. Paths under `internal/`, symbols tagged `@internal`, and `internal` namespaces are wiring between the interface and its implementation, not supported consumer APIs. This includes compatibility exports retained at old paths. Public types named by a supported signature remain part of its contract; use the documented entry points rather than calling internal proxies or raw writer helpers.
+
+## How to Read a Domain
+
+Every domain folder opens with `1.introduction.md`. It gives you the overview, the key features, the AntelopeJS packages the domain depends on, one runnable quick-start example, and the list of the folder's other pages.
+
+The numbered pages after it are topic pages, ordered so that reading them front to back builds up. Each one starts with an overview, then works through the surface task by task with a code example per section and a table for anything that takes options. Every topic page ends with a link to the next one, so you can also follow a folder straight through from its introduction.
+
+Read a topic page on its own when you already know which surface you need.

package/docs/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "composite": false,
+    "incremental": false,
+    "tsBuildInfoFile": null,
+    "noEmit": true
+  },
+  "include": ["../src/**/*.ts", "**/*.ts"]
+}