@antelopejs/interface-dms 0.7.0 → 0.7.2

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

@@ -0,0 +1,354 @@
+---
+title: "Hooks"
+description: "A hook is a named platform event with a typed argument list and a typed result."
+---
+
+# Hooks
+
+## Overview
+
+A hook is a named platform event with a typed argument list and a typed result. Modules register handlers with `RegisterHook`, and the code that owns the event dispatches it: `ExecuteHooks` runs every handler and discards what they return, `CollectHooks` gathers their return values, and `GetRegisteredHooks` hands back the handlers themselves for a caller that must invoke each one differently. `HookSignatures` ties each `Hook` member to its arguments and result, so the compiler checks a handler against the hook it registers for.
+
+Everything on this page lives in `@antelopejs/interface-dms/hooks`.
+
+## Register a Handler
+
+```typescript
+import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
+
+export function registerBillingHooks(): void {
+  RegisterHook(Hook.MEMBER_ADDED, async (payload) => {
+    // payload: { tenantId, userId, isTenantOwner }
+    await seedBillingProfile(payload.tenantId, payload.userId);
+  });
+
+  RegisterHook(Hook.TENANT_DELETED, async (tenantId) => {
+    await dropBillingProfiles(tenantId);
+  });
+}
+```
+
+`RegisterHook<H>(name: H, callback: HookHandler<H>, options?: HookRegistrationOptions)` appends the callback to the hook's list. The check is a TypeScript one: `HookHandler<H>` derives the parameter and return types from `HookSignatures[H]`, so a mismatched handler is a compile error. At runtime the call performs no validation.
+
+A hook whose result is `undefined` is an event: its dispatchers discard what the handlers return, so such a handler may return anything — nothing, the result of the write it awaited, or a promise of it. `HookHandlerResult<H>` is that rule: `unknown` for these hooks, the hook's result (or a promise of it) for a hook that has one, such as `Hook.TENANT_DATA_EXPORT`.
+
+A registration belongs to the module that makes it, and goes away with it. When the module is destroyed — it stops for good, or it reloads in development — its handlers are released, and a reloaded module registers its own again from its next `construct()`. A module therefore has nothing to unregister on its way out.
+
+Every registration records the module it came from, resolved from the registering call site. `HookRegistrationOptions.moduleId` overrides that resolution:
+
+```typescript
+interface HookRegistrationOptions {
+  moduleId?: string;
+}
+```
+
+The id only matters to a dispatcher that treats handlers per module rather than as one flat list — the tenant data export namespaces each contributor's archive entries by it. Set it explicitly whenever the registration happens somewhere the runtime would attribute to another module, such as a shared helper called during your module's construction. It does not change when the registration is released: that follows the module that made it.
+
+`UnregisterHook<H>(name: H, callback: HookHandler<H>)` removes a previously registered callback by identity, for a module that stops listening while it stays loaded. Keep a reference to the function you registered:
+
+```typescript
+import {
+  Hook,
+  type HookHandler,
+  RegisterHook,
+  UnregisterHook,
+} from "@antelopejs/interface-dms/hooks";
+
+const onMemberAdded: HookHandler<Hook.MEMBER_ADDED> = async (payload) => {
+  await seedBillingProfile(payload.tenantId, payload.userId);
+};
+
+RegisterHook(Hook.MEMBER_ADDED, onMemberAdded);
+UnregisterHook(Hook.MEMBER_ADDED, onMemberAdded);
+```
+
+`HookCallback` is the untyped shape the registry stores internally, `(...args: any[]) => Promise<any> | any`. Register through `HookHandler<H>` instead so the payload keeps its type.
+
+## The `Hook` Enum
+
+| Member | Value | Arguments | Result |
+| ------ | ----- | --------- | ------ |
+| `Hook.DATABASE_INITIALIZED` | `"database:initialized"` | none | `undefined` — fires on every DMS start; a handler registered later runs at once (see [Initialise Against the Database](#initialise-against-the-database)) |
+| `Hook.TENANT_BEING_PROVISIONED` | `"tenant:being-provisioned"` | `TenantProvisioningHookPayload` | `undefined` |
+| `Hook.TENANT_DELETED` | `"tenant:deleted"` | `tenantId: string` | `undefined` |
+| `Hook.TENANT_DATA_EXPORT` | `"tenant:data-export"` | `tenantId: string`, `archive: TenantExportArchive`, `signal: AbortSignal` | `TenantDataExportContribution \| void` |
+| `Hook.INVITE_BEING_CREATED` | `"invite:being-created"` | `InviteHookPayload` | `undefined` |
+| `Hook.INVITE_CREATED` | `"invite:created"` | `InviteCreatedHookPayload` | `undefined` |
+| `Hook.INVITE_DELETED` | `"invite:deleted"` | `InviteDeletedHookPayload` | `undefined` |
+| `Hook.MEMBER_BEING_ADDED` | `"member:being-added"` | `MemberHookPayload` | `undefined` |
+| `Hook.MEMBER_ADDED` | `"member:added"` | `MemberHookPayload` | `undefined` |
+| `Hook.MEMBER_REMOVED` | `"member:removed"` | `MemberRemovedHookPayload` | `undefined` |
+| `Hook.USER_REGISTERED` | `"user:registered"` | `UserRegisteredHookPayload` | `undefined` |
+| `Hook.USER_DELETED` | `"user:deleted"` | `UserDeletedHookPayload` | `undefined` — fires after every user deletion the DMS performs (today: a user deleting their own account), once its rows are gone; a failing handler is logged and does not bring the account back |
+
+The `*_BEING_*` members fire before the write they precede; the past-tense members fire after it. `TENANT_BEING_PROVISIONED` has no past-tense counterpart — see [Enrich a Workspace Being Provisioned](#enrich-a-workspace-being-provisioned).
+
+## Payload Interfaces
+
+```typescript
+interface TenantProvisioningHookPayload {
+  tenantId: string;
+  userId: string;
+  extras: Record<string, unknown>;
+}
+
+interface InviteHookPayload {
+  tenantId: string;
+  email: string;
+  asTenantOwner: boolean;
+  roleIds: string[];
+}
+
+interface InviteCreatedHookPayload extends InviteHookPayload {
+  inviteId: string;
+  token: string;
+}
+
+interface InviteDeletedHookPayload {
+  tenantId: string;
+  inviteId: string;
+  email: string;
+}
+
+interface MemberHookPayload {
+  tenantId: string;
+  userId: string;
+  isTenantOwner: boolean;
+}
+
+interface MemberRemovedHookPayload {
+  tenantId: string;
+  userIds: string[];
+}
+
+interface UserRegisteredHookPayload {
+  tenantId: string;
+  userId: string;
+  email: string;
+  name: string;
+}
+
+type UserDeletionReason = "self";
+
+interface UserDeletedHookPayload {
+  userId: string;
+  email: string;
+  tenantIds: string[];
+  reason: UserDeletionReason;
+}
+```
+
+The shapes are not uniform, and the difference between the addition and removal payloads is deliberate: `MEMBER_BEING_ADDED` and `MEMBER_ADDED` describe one member with `userId`, while `MEMBER_REMOVED` carries `userIds`, because a removal can cover several members at once. Let the handler's inferred parameter type guide you.
+
+`UserDeletedHookPayload.tenantIds` lists the workspaces the user was a member of, all left before the deletion; delete the per-user rows your module keeps in them. `reason` is `"self"` today, the user deleting their own account.
+
+`InviteCreatedHookPayload` carries the invite `token`. It is a signup credential: keep it inside the handler rather than forwarding it to a wider surface.
+
+`TenantProvisioningHookPayload.extras` is opaque: the DMS reads no key of it, validates nothing and stores nothing. See [Enrich a Workspace Being Provisioned](#enrich-a-workspace-being-provisioned).
+
+`TENANT_DATA_EXPORT` is the one hook whose handler produces something rather than only reacting. Its argument and return types live in `@antelopejs/interface-dms/tenant-export` and are re-exported from this module, so either import path works. They are covered in [Contribute to a Tenant Data Export](#contribute-to-a-tenant-data-export).
+
+## Dispatch: `ExecuteHooks` vs `CollectHooks`
+
+Both take the hook and its arguments and await each handler in registration order. They differ in what they do with the outcome.
+
+```typescript
+async function ExecuteHooks<H extends Hook>(
+  name: H,
+  ...args: HookSignatures[H]["args"]
+): Promise<void>;
+
+async function CollectHooks<H extends Hook>(
+  name: H,
+  ...args: HookSignatures[H]["args"]
+): Promise<HookSignatures[H]["result"][]>;
+```
+
+| | `ExecuteHooks` | `CollectHooks` |
+| --- | --- | --- |
+| Return value | `Promise<void>` — handler results are discarded | `Promise<Result[]>` — one entry per handler that returned |
+| A handler that throws | The rejection propagates to the caller and the remaining handlers do not run | The error is logged and the handler contributes nothing; the remaining handlers still run |
+| Use for | Notifying that something happened | Asking every handler to contribute something |
+
+Use `ExecuteHooks` for the notification hooks — a failing handler should be able to fail the operation that fired it. Use `CollectHooks` for contribution hooks, where one broken module must not sink the whole collection.
+
+```typescript
+import {
+  CollectHooks,
+  ExecuteHooks,
+  Hook,
+} from "@antelopejs/interface-dms/hooks";
+
+// notify: every handler runs, nothing is returned
+await ExecuteHooks(Hook.TENANT_DELETED, tenantId);
+
+// collect: gather what every handler returned, skipping the ones that threw
+const payloads = await CollectHooks(Hook.MEMBER_ADDED, {
+  tenantId,
+  userId,
+  isTenantOwner: false,
+});
+```
+
+A caller that must not be broken by a subscriber wraps `ExecuteHooks` in its own `try`/`catch` — the DMS does this for `USER_REGISTERED`, where a failing subscriber would otherwise strand a user whose account was already created.
+
+## Dispatch Handler by Handler: `GetRegisteredHooks`
+
+Both dispatchers pass the same arguments to every handler. When each handler needs arguments of its own, take the list instead:
+
+```typescript
+function GetRegisteredHooks<H extends Hook>(name: H): RegisteredHook<H>[];
+
+interface RegisteredHook<H extends Hook> {
+  moduleId?: string;
+  handler: HookHandler<H>;
+}
+```
+
+`moduleId` is what the registration recorded — the `HookRegistrationOptions.moduleId` that was passed, or the module the runtime attributed the call to — and is `undefined` when neither resolved. Handling the failures is the caller's job here: nothing wraps the handler for you.
+
+This is how the tenant data export runs. Each contributor needs an archive namespaced under its own module id, which no shared argument list can express.
+
+## Initialise Against the Database
+
+`DATABASE_INITIALIZED` behaves like an already-resolved promise rather than a one-off event. The DMS fires it from its `start()`, once the database schemas are registered, and the hook then stays settled until the DMS stops:
+
+- A handler registered before that runs when the DMS starts, in series with the others, as `ExecuteHooks` runs them. One that throws fails the DMS start.
+- A handler registered while it is settled — by a module loaded after the DMS started, or one reloaded in development — runs at once, in the background. The registration does not wait for it, and a failure is logged with the hook and module name rather than thrown into the registering module's `construct()` or `start()`.
+- A handler registered while the DMS is stopped waits for its next start.
+
+A handler therefore runs once per DMS start and once per registration made while the DMS runs, which adds up to several times over the life of a process: the DMS itself reloading replays every handler, and a module that reloads registers — and so runs — its own again. Write it to be safe to replay against a live database: create what is missing, never insert unconditionally, and never send a message or charge from it without a record that it already happened.
+
+The settled state is what `SettleHook` and `UnsettleHook` manage. Only the hooks typed `StickyHook` accept them, and only `DATABASE_INITIALIZED` is one; the DMS is the only caller.
+
+## Enrich a Workspace Being Provisioned
+
+A SaaS signup provisions a workspace, and the product running it usually collects more at that moment than the DMS models — an acquisition source, a team size, a referral code. `TENANT_BEING_PROVISIONED` is where a module writes those to its own tables, while the provisioning is still undone.
+
+```typescript
+import {
+  Hook,
+  RegisterHook,
+} from "@antelopejs/interface-dms/hooks";
+
+RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId, userId, extras }) => {
+  await recordAcquisition(tenantId, userId, {
+    source: extras.acquisitionSource,
+    referral: extras.referralCode,
+  });
+});
+```
+
+The hook is dispatched with `ExecuteHooks`, so handlers run in series, each awaited, and **a handler that throws aborts the provisioning**: the rejection reaches the emitter, later handlers do not run, and the emitter unwinds the workspace it was creating. A workspace therefore never ends up provisioned while the enrichment a consumer needed failed to be written — that direction is the guarantee, and the reason to fire before the commit rather than after it.
+
+The other direction is not guaranteed, and no hook could provide it: there is no shared transaction to enlist in. A handler that already returned has committed its own rows, and neither a later handler throwing nor the emitter failing afterwards takes them back. Two habits make that survivable:
+
+- Key the write on `tenantId`, so it can be cleaned up along with the workspace — subscribing to `TENANT_DELETED` covers the ordinary deletion path.
+- Make it idempotent, so a retried signup does not double it.
+
+The flip side is the usual one for a `*_BEING_*` hook: a handler that throws for its own reasons fails somebody's signup, so keep it to what genuinely must not be lost.
+
+`extras` is opaque by design. The DMS reads no key of it, validates nothing, and stores nothing — it carries the object from the caller of the provisioning flow to the handlers, and each handler writes what it recognises. The shape is a contract between that caller and that handler, one the DMS is deliberately not a party to, so a product can start collecting a new field without waiting on a DMS release.
+
+No DMS code fires this hook: provisioning belongs to the signup flow of a SaaS module such as **`dms-saas`**. The DMS declares the contract; the emitter honours it. Without such a module, nothing invokes it.
+
+## Contribute to a Tenant Data Export
+
+`TENANT_DATA_EXPORT` asks every module for its slice of one tenant's data, which is assembled into a single ZIP archive. A handler receives the tenant id, an archive to write into, and an `AbortSignal`. It has two ways to contribute, and may use both:
+
+- Return a `TenantDataExportContribution` — its `data` is serialized to `modules/<moduleId>.json`.
+- Write entries into the `archive` — for anything too large to hold in memory, or that is not JSON.
+
+Register with `RegisterTenantDataExportContributor` rather than a bare `RegisterHook`. It names the module id explicitly, and that id is what namespaces the contributor's archive entries:
+
+```typescript
+import { RegisterTenantDataExportContributor } from "@antelopejs/interface-dms/hooks";
+
+RegisterTenantDataExportContributor(
+  "@acme/dms-billing",
+  async (tenantId, archive, signal) => {
+    await archive.addStream(
+      "invoices.ndjson",
+      streamInvoices(tenantId, signal),
+    );
+    return {
+      moduleId: "@acme/dms-billing",
+      data: await collectBillingSettings(tenantId),
+    };
+  },
+);
+
+```
+
+The helper's signature is shown separately for reference:
+
+```typescript
+import type { Hook, HookHandler } from "@antelopejs/interface-dms/hooks";
+
+declare function RegisterTenantDataExportContributor(
+  moduleId: string,
+  handler: HookHandler<Hook.TENANT_DATA_EXPORT>,
+): void;
+```
+
+A handler that only writes archive entries returns nothing.
+
+```typescript
+interface TenantDataExportContribution {
+  moduleId: string;
+  data: unknown;
+}
+```
+
+### `TenantExportArchive`
+
+```typescript
+import type { Readable } from "node:stream";
+
+interface TenantExportArchive {
+  addJson(path: string, data: unknown): Promise<void>;
+  addFile(path: string, localPath: string): Promise<void>;
+  addStream(path: string, stream: Readable): Promise<void>;
+}
+```
+
+| Method | Adds |
+| ------ | ---- |
+| `addJson` | `data` serialized as a JSON entry. |
+| `addFile` | An artifact already materialized on disk, read from `localPath`. |
+| `addStream` | A remote or generated dump, without ever holding it in memory. |
+
+Paths are relative: the implementation prefixes every entry with `modules/<moduleId>/`, so two contributors can both write `invoices.ndjson` without colliding, and none has to defend against another's paths.
+
+**Await every call.** Each method resolves only once the archiver has consumed the entry — awaiting is what propagates back-pressure to whatever produces the data, and is what keeps memory flat however large the export grows. Firing them without `await` gives up both.
+
+The `signal` aborts when the export is cancelled or times out. Pass it down to whatever produces your data so a cancelled export stops reading rather than finishing into a discarded archive.
+
+### The Manifest
+
+Every run writes a `manifest.json` at the archive root recording what each contributor produced:
+
+```typescript
+interface TenantExportManifest {
+  tenantId: string;
+  exportedAt: string;
+  partial: boolean;
+  modules: TenantExportModuleReport[];
+}
+
+interface TenantExportModuleReport {
+  moduleId: string;
+  declaredModuleId?: string;
+  entries: string[];
+  failed: boolean;
+  error?: string;
+}
+```
+
+A failing contributor does not fail the export: its report carries `failed: true` and the error message, and `partial` goes `true` on the manifest so a consumer can tell an incomplete archive from a complete one. `declaredModuleId` appears when the returned contribution named a different id than the one the archive namespaced the entries under — a sign the registration and the return value disagree.
+
+Running the export is the other side of this contract: `buildTenantExportArchive` drives the contributors and writes the ZIP, and `startTenantExportJob` runs it as a background export job. Both belong to the [Base](/docs/interfaces/base/introduction) domain, under its helpers.
+
+## Next Steps
+
+[Realtime](/docs/interfaces/core/realtime) covers pushing an event to an open page instead of reacting to a platform event.

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

@@ -0,0 +1,147 @@
+---
+title: "Realtime"
+description: "Publish events on topics from the backend, and how page-bound topics reach the browsers viewing the page."
+---
+
+# Realtime
+
+## Overview
+
+Realtime works on topics. A topic is a plain string a page declares interest in, and any backend code can publish a message on it. `RegisterPageTopic` binds a topic to a page id; `PublishMessage` sends an event on that topic to every client currently subscribed to it. `SubscribeMessage` is the read half: it lets backend code receive what is published, instead of only feeding the dashboard's own streams.
+
+Everything on this page lives in `@antelopejs/interface-dms/realtime`.
+
+## How a Page Ends Up Subscribed
+
+Subscription is derived, not requested by the publisher:
+
+1. A page — or a component on it — calls `RegisterPageTopic(pageId, topic)` at registration time. `pageId` is the page's `fullId` ([Pages and Modules](/docs/interfaces/core/pages-and-modules)), not its slug.
+2. A client opens a realtime session and reports which page it is on. The backend checks that the user may access that page, then subscribes the session to every topic registered for that page id, and drops the topics that are no longer wanted.
+3. `PublishMessage(topic, type)` delivers to the sessions currently subscribed to `topic`.
+
+So a publisher never addresses a page or a user. It addresses a topic, and the page-topic registry decides who is listening.
+
+Registering the same topic for the same page twice is harmless — a page's topics are a set.
+
+A binding belongs to the module that registered it: it is removed when that module is unloaded, and it survives a reload of the DMS module, which gets every binding back from the core. Registering from `onCreated`, as below, makes the module whose page it is that owner.
+
+## Register a Topic for a Page
+
+The typical caller is a component builder's `onCreated` callback, which receives the `PageMetadata` of the page the component was declared on ([Components](/docs/interfaces/core/components)):
+
+```typescript
+import { ComponentBuilder } from "@antelopejs/interface-dms/component";
+import { RegisterPageTopic } from "@antelopejs/interface-dms/realtime";
+
+export const STOCK_TOPIC = "catalog:stock";
+
+export function StockCounter(options: { fetchUrl: string }) {
+  return new ComponentBuilder<{ fetchUrl: string }>("acme-stock-counter")
+    .options(options)
+    .onCreated((page) => {
+      const pageInfo = page.pageInfo;
+      if (!pageInfo) return;
+      RegisterPageTopic(pageInfo.fullId, STOCK_TOPIC);
+    });
+}
+```
+
+Registering from `onCreated` is what makes the binding follow the component: whichever page the component is placed on gets the topic. The chart builders of the [Base](/docs/interfaces/base/introduction) domain do exactly this — a chart declaring `realtimeTopic` registers each of its topics on the page it is placed on.
+
+To bind a topic to a page you know statically, call `RegisterPageTopic` with that page's `fullId` directly.
+
+```typescript
+RegisterPageTopic(pageId: string, topic: string): void
+```
+
+## Publish a Message
+
+```typescript
+import { Controller, Post } from "@antelopejs/interface-api";
+import { PublishMessage } from "@antelopejs/interface-dms/realtime";
+import { STOCK_TOPIC } from "../components/stock-counter";
+
+export class StockController extends Controller("/api/stock") {
+  @Post("/restock")
+  async restock(): Promise<{ ok: boolean }> {
+    await applyRestock();
+    await PublishMessage(STOCK_TOPIC, "stock.updated", {
+      payload: { warehouse: "eu-west" },
+      actorId: "system",
+    });
+    return { ok: true };
+  }
+}
+```
+
+```typescript
+PublishMessage(
+  topic: string,
+  type: string,
+  options?: PublishMessageOptions,
+): Promise<void>
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `topic` | The topic to publish on. Subscribers are the sessions on a page that registered this topic. |
+| `type` | The event type carried with the message, for subscribers that distinguish several kinds of event on one topic. |
+| `options` | Optional payload and actor. |
+
+### `PublishMessageOptions`
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `payload` | `Record<string, unknown>` | Data carried with the event. |
+| `actorId` | `string` | Identifies who caused the event, so a client can ignore an event it triggered itself. |
+
+`PublishMessage` resolves once the message has been handed to the broker. It does not report how many sessions received it, and publishing on a topic no page registered is not an error — it simply reaches nobody.
+
+## Subscribe from the Backend
+
+`SubscribeMessage` receives every message published on a topic, whichever instance published it: the subscription rides the same broker as `PublishMessage`, so what one instance publishes reaches subscribers on every other.
+
+```typescript
+import { SubscribeMessage } from "@antelopejs/interface-dms/realtime";
+import { STOCK_TOPIC } from "../components/stock-counter";
+
+const unsubscribe = SubscribeMessage(STOCK_TOPIC, (message) => {
+  if (message.type !== "stock.updated") return;
+  const warehouse = message.payload?.warehouse;
+  if (typeof warehouse === "string") {
+    void refreshWarehouseCache(warehouse);
+  }
+});
+```
+
+```typescript
+function SubscribeMessage(
+  topic: string,
+  handler: RealtimeMessageHandler,
+): UnsubscribeMessage;
+
+type RealtimeMessageHandler = (message: RealtimeMessage) => void;
+type UnsubscribeMessage = () => void;
+```
+
+### `RealtimeMessage`
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `topic` | `string` | Topic the message was published on. |
+| `type` | `string` | Event type given to `PublishMessage`. |
+| `payload` | `Record<string, unknown>` | Data carried with the event, when the publisher sent any. |
+| `actorId` | `string` | Who caused the event, when the publisher named an actor. |
+| `ts` | `number` | Publication timestamp. |
+
+Paired with `PublishMessage`, this turns the DMS's broker into one a module can use for realtime channels of its own — its own endpoint subscribes here and the DMS carries the messages — instead of bringing a second broker to do the same job.
+
+Three properties to design around:
+
+- **Handlers must not throw.** They are called on the delivering instance's event loop, and nothing catches for you.
+- **Delivery is fire-and-forget.** There is no replay: a message published while nobody was subscribed is gone. Do not use a topic as a queue.
+- **Unsubscribing is automatic** when the registering module is unloaded. The returned `UnsubscribeMessage` is for ending a subscription earlier than that; calling it twice is a no-op.
+
+## Next Steps
+
+[Quick Actions](/docs/interfaces/core/quick-actions) covers the other way a module reaches the running dashboard: entries in the command palette.

package/docs/1.core/9.quick-actions.md

@@ -0,0 +1,115 @@
+---
+title: "Quick Actions"
+description: "A quick action is a shortcut the backend contributes to the dashboard's command palette: a labelled entry, grouped under a category, that points at a registered page, a table creation form, a table toolbar button, or…"
+---
+
+# Quick Actions
+
+## Overview
+
+A quick action is a shortcut the backend contributes to the dashboard's command palette: a labelled entry, grouped under a category, that points at a registered page, a table creation form, a table toolbar button, or an event. Actions register at import time. Access follows the target page and, for a form or a button, the permission of what it opens.
+
+Both functions live in `@antelopejs/interface-dms/quick-actions`.
+
+## Declare a Category and Its Actions
+
+`QuickActionCategory(id, info)` registers the group; `QuickAction(id, info)` registers an entry in it. Both return the registered record. Create the category first: registering an action whose category is unknown throws.
+
+This example assumes your application exports a registered `TasksPage` from `./pages/tasks`.
+
+```typescript
+import { TasksPage } from "./pages/tasks";
+import {
+  QuickAction,
+  QuickActionCategory,
+} from "@antelopejs/interface-dms/quick-actions";
+
+const tasks = QuickActionCategory("tasks", {
+  displayName: "$my_app.quick_actions.tasks",
+  icon: "i-ph-check-square",
+  order: 10,
+});
+
+QuickAction("tasks-new", {
+  category: tasks,
+  displayName: "$my_app.quick_actions.tasks_new",
+  icon: "i-ph-plus",
+  target: { type: "navigate", page: TasksPage },
+});
+```
+
+Actions are keyed by their category id and their own id, so the same action id may appear under two categories. Registering an id that is already taken keeps the first registration.
+
+## `QuickActionCategoryInfo`
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `id` | `string` | Category id. Supplied as the first argument of `QuickActionCategory`, not inside `info`. |
+| `displayName` | `string` | Group label. Required. |
+| `icon` | `string` | Icon name. |
+| `order` | `number` | Sort order among categories. |
+
+## `QuickActionInfo`
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `id` | `string` | Action id. Supplied as the first argument of `QuickAction`, not inside `info`. |
+| `category` | `QuickActionCategoryInfo` | The record returned by `QuickActionCategory`. Required. |
+| `displayName` | `string` | Entry label. Required. |
+| `icon` | `string` | Icon name. Required. |
+| `order` | `number` | Sort order within the category. |
+| `target` | `QuickActionTarget` | What running the action does. Required. |
+
+Access is computed per caller from the registered target page, including its permission and tenant access gate ([Permissions](/docs/interfaces/core/permissions)). An `openForm` target also checks the selected table's create action; a `button` target checks the button's own `permission`. Configure access on the destination rather than adding a separate `permission` property to the quick action.
+
+## `QuickActionTarget`
+
+Every target requires `page`, the registered page controller class. The frontend URL derives from that page, so renaming a route does not leave a stale URL in the action.
+
+| Variant | Fields | Meaning |
+| ------- | ------ | ------- |
+| `"navigate"` | `page`, optional `query` | Navigate to the page with optional string query parameters. |
+| `"openForm"` | `page`, optional `component` | Open a table's creation form. Select the component explicitly if the page has more than one eligible table. |
+| `"button"` | `page`, `button`, optional `component` | Open the page and press the table toolbar button whose `id` is `button`, e.g. to open the modal it opens. Select the component explicitly if several components of the page declare that button id. |
+| `"event"` | `page`, `name`, optional `payload` | Navigate to the page and emit the named event. |
+
+The following examples assume an existing registered `BooksPage` with a `TableView` stored in its static `table` field. For a nested table, pass a target such as `BooksPage.content.targetChild("table")` instead.
+
+```typescript
+import { BooksPage } from "./pages/books";
+import {
+  QuickAction,
+  QuickActionCategory,
+} from "@antelopejs/interface-dms/quick-actions";
+
+const catalog = QuickActionCategory("catalog", {
+  displayName: "$my_app.quick_actions.catalog",
+  icon: "i-ph-books",
+});
+
+QuickAction("catalog-new-book", {
+  category: catalog,
+  displayName: "$my_app.quick_actions.new_book",
+  icon: "i-ph-plus",
+  target: { type: "openForm", page: BooksPage, component: BooksPage.table },
+});
+
+// BooksPage.table declares customButtons: [{ id: "import", permission: "add", … }]
+QuickAction("catalog-import", {
+  category: catalog,
+  displayName: "$my_app.quick_actions.import_books",
+  icon: "i-ph-upload",
+  target: { type: "button", page: BooksPage, button: "import" },
+});
+
+QuickAction("catalog-refresh", {
+  category: catalog,
+  displayName: "$my_app.quick_actions.refresh",
+  icon: "i-ph-arrows-clockwise",
+  target: { type: "event", page: BooksPage, name: "catalog:refresh", payload: { force: true } },
+});
+```
+
+Declare quick actions in a file imported by your module so the registrations run at import time, next to the pages they point at.
+
+[Layout Banners](/docs/interfaces/core/layout-banners) covers the other global surface a backend module contributes to: messages under the dashboard header.

package/docs/2.auth/.navigation.yml

@@ -0,0 +1,2 @@
+title: Auth
+icon: i-lucide-key-round