@antelopejs/interface-dms-builder 0.4.1 → 0.5.0

package/dist/project.js

@@ -2,8 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CreateLocalModule = exports.ConfigureModule = exports.AddModule = exports.ConfigureProject = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
+/**
+ * Applies steps to `antelope.config.ts` in order, as one edit: every step is validated before
+ * anything is written, and none is written if one is refused. The configuration must be a
+ * `defineConfig({ … })` (or plain object) literal with a literal `modules`. With `variables`,
+ * `.env` is written first, once a dry run accepted the steps, and put back when the configuration
+ * cannot be written.
+ */
 exports.ConfigureProject = (0, interface_core_1.InterfaceFunction)();
+/** One `AddModule` step. */
 exports.AddModule = (0, interface_core_1.InterfaceFunction)();
+/** One `ConfigureModule` step. */
 exports.ConfigureModule = (0, interface_core_1.InterfaceFunction)();
+/** One `CreateLocalModule` step; `opts.connection` is the step's `connection`. */
 exports.CreateLocalModule = (0, interface_core_1.InterfaceFunction)();
 //# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -1 +1 @@
-{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA8GlD,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAKd,CAAC;AAGO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAOd,CAAC"}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2H/D;;;;;;GAMG;AACU,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAKd,CAAC;AAEN,4BAA4B;AACf,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAMd,CAAC;AAEN,kCAAkC;AACrB,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAMd,CAAC;AAEN,kFAAkF;AACrE,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAOd,CAAC"}

package/dist/queries.d.ts

@@ -2,65 +2,190 @@ import type { ConfigSchema } from "./catalog";
 import type { ResourceRef } from "./resources";
 import type { MutationOpts, OpResult } from "./results";
 import type { ConfigValue } from "./values";
+/**
+ * A query's address: `<pageRef>@<name>`, e.g. `/books@inStockCount`. The page is
+ * where the route lives; the resource it reads is recorded in the query itself.
+ */
 export type QueryRef = string;
+/**
+ * The shape a query's route responds with: one number as `{ value }`, or one
+ * point per group as `{ series }`, each point carrying its group as `x` and what
+ * was measured as `y`.
+ */
 export type QueryOutputKind = "scalar" | "series";
+/**
+ * How a query's answer is arranged for the block that reads it.
+ *
+ * The calculation is the same either way — a measure, possibly per group. This
+ * says what the route wraps it in: the points themselves, a headline figure above
+ * them, that figure alone, or the points as a ranked list.
+ */
 export type QueryArrangement = "series" | "card" | "value" | "items";
+/** The comparison operators a filter may use. */
 export type FilterOp = "eq" | "ne" | "gt" | "ge" | "lt" | "le";
+/**
+ * A filter value supplied per request rather than baked into the chain. It
+ * becomes a parameter of the model method and a `@Parameter` on the route.
+ *
+ * `name` and `in` describe the *route*, not the model: the route reads the value
+ * from that source, coerces it (`Number(...)` / `new Date(...)`), and passes it
+ * positionally to the model method. The model method neither knows nor cares
+ * where the value came from — its own parameter is named from the template, so
+ * `name`/`in` here only shape the route and are recovered from it on read-back.
+ */
 export type QueryParamBinding = {
     $param: {
+        /** A camelCase identifier; the route exposes the value under this name. */
         name: string;
+        /** Where the route reads the value from; defaults to `"query"`. */
         in?: "query" | "param";
     };
 };
+/**
+ * A filter value: either a plain scalar baked into the chain, or a
+ * {@link QueryParamBinding}. `$expr` is refused — a query's values are data.
+ *
+ * The alias is deliberate: it documents that a parameter value is data, never an
+ * expression, which `QueryParamBinding` relies on.
+ */
 export type QueryParamValue = ConfigValue;
+/** One conjunct of a query's `where`. Filters combine with AND. */
 export type QueryFilter = {
     field: string;
     op: FilterOp;
     value: QueryParamValue;
 };
+/** A query template the builder can compile into a model method. */
 export interface QueryTemplateDescriptor {
+    /** The template id, e.g. `"count"` | `"aggregate"`. */
     id: string;
     resourceType: "database-table";
     title: string;
     description?: string;
     output: QueryOutputKind;
+    /** The template's parameter schema, in the same vocabulary as the block catalog. */
     params: ConfigSchema;
 }
+/** One measured group, as a route answers it and a chart reads it. */
 export interface QueryPoint {
     x: number | string;
     y: number;
 }
+/**
+ * The body a query's route returns.
+ *
+ * `{ value }` for a scalar and `{ series }` for a plain grouped route; for an
+ * arranged one, whatever the DMS helper built — `ChartCardData`, `KpiCardData`,
+ * `TopListData`. Those types belong to `@antelopejs/interface-dms`, which this
+ * package deliberately does not depend on, so the body travels as the JSON the
+ * route serves it as.
+ */
 export type QueryResponseBody = object;
+/**
+ * What a draft query answers when run without being written.
+ *
+ * `body` is what the route would return, built by the same helper the route would
+ * call, so a block can be handed it directly; `output` and `response` report it
+ * the way {@link QueryStructure} reports the saved query, so a preview and the
+ * page it previews cannot disagree about what they show.
+ *
+ * `truncated` is the one thing the route has no equivalent of: a preview stops
+ * reading at some point, and a chart that silently lost its tail is worse than one
+ * that says so.
+ */
 export interface QueryPreview {
     output: QueryOutputKind;
+    /**
+     * How the body is arranged, set only when a helper arranged it — the same
+     * condition under which read-back reports it.
+     */
     response?: QueryArrangement;
     body: QueryResponseBody;
     truncated: boolean;
 }
+/** Input for `AddQuery`. */
 export interface AddQueryInput {
+    /**
+     * Query name — a camelCase identifier. Names the route method, and the model
+     * method too unless one of that name already exists compiling a *different*
+     * chain, in which case the model method is emitted under a free suffixed name
+     * so the queries already sharing the original keep their behaviour.
+     */
     name: string;
+    /** The resource the query reads. */
     resource: ResourceRef;
+    /** A `QueryTemplateDescriptor.id`. */
     template: string;
+    /** The template's parameters. */
     params?: Record<string, QueryParamValue>;
+    /**
+     * How the answer is arranged for the block reading it. Defaults to what the
+     * template computes: a number for a scalar, its points for a series.
+     *
+     * A grouped calculation feeds a bare chart, a card with a headline figure, or
+     * a ranked list without being described three times.
+     */
     response?: QueryArrangement;
+    /**
+     * Answer the preceding period alongside the current one, so a card can show a
+     * variation. Only meaningful when the query binds a period.
+     */
     compare?: boolean;
+    /**
+     * The route path, relative to the page: the DMS serves it at
+     * `/dms/pages<pageRef><endpoint>` (`pageRoutePath` of interface-dms). Defaults to
+     * `/stats/<kebab-name>`; any path is allowed, since read-back identifies a
+     * query by its shape rather than its URL. Must not collide with another route
+     * on the page.
+     */
     endpoint?: string;
 }
+/**
+ * A query as read back off disk. Read-back is purely structural: a route reads
+ * as a query when its shape and the chain it calls both parse, so a hand-written
+ * route matching the grammar is as editable as a generated one, and any edit
+ * that keeps the chain in-grammar is simply re-read. A query that no longer
+ * parses still reports `route`, `resource` and `modelMethod` — only
+ * `template`/`params` go missing — so the builder can always see and remove what
+ * it cannot edit.
+ */
 export interface QueryStructure {
     name: string;
+    /** How the answer is arranged, when the route wraps the calculation. */
     response?: QueryArrangement;
+    /** The route path relative to the page's slug, as {@link AddQueryInput.endpoint} takes it. */
     endpoint: string;
     resource?: ResourceRef;
+    /**
+     * The model method the route calls. Several queries may share one method, but
+     * only while they want the exact same chain — see {@link AddQueryInput.name}.
+     */
     modelMethod?: string;
     output?: QueryOutputKind;
     template?: string;
     params?: Record<string, QueryParamValue>;
+    /**
+     * The route's declared parameters — the source of truth for a bound value's
+     * `name` and `in`. `header` appears only on hand-written routes; a generated
+     * one binds `$param` to `query` or `param`.
+     */
     routeParams?: {
         name: string;
         in: "query" | "param" | "header";
     }[];
+    /**
+     * True when the route answers the preceding period beside the current one,
+     * as {@link AddQueryInput.compare} asked it to.
+     */
     compare?: boolean;
+    /** True when the query could not be reversed to an editable template. */
     opaque?: boolean;
+    /**
+     * Set when `opaque === true`. `unparseable_route` — the GET wrapper is not the
+     * recognized `return { value: await model.m(...) }` shape. `unparseable_chain`
+     * — the model method it calls is not a chain any registered template accepts
+     * (hand-written, edited out of grammar, or from a newer builder).
+     */
     opaqueReason?: "unparseable_route" | "unparseable_chain";
 }
 export declare const ListQueryTemplates: (resourceType?: string | undefined) => Promise<QueryTemplateDescriptor[]>;

package/dist/resources.d.ts

@@ -1,60 +1,164 @@
 import type { CategoryRef, PageRef } from "./addressing";
 import type { MutationOpts, OpResult } from "./results";
 import type { ConfigObject, DataTypeValue } from "./values";
+/** A resource's stable ref — its `name`, e.g. `"product"`. */
 export type ResourceRef = string;
+/** A field's address within a resource: `<resourceRef>#<fieldName>`. */
 export type FieldPath = string;
+/** The paths of the files a resource is composed of. */
 export interface ResourceFiles {
     database: string;
     dataApi: string;
     index: string;
 }
+/**
+ * The semantic aspects of a resource field. The engine maps these to the paired
+ * `@Field`/`@Index` (Table) and `@Select`/`@Listable`/`@Column`/`@Access`/…
+ * (DataAPI) decorator stacks; the consumer never touches raw decorators.
+ */
 export interface FieldAspects {
+    /** The field's DataType value, e.g. `{ $dataType: "string" }`. */
     dataType: DataTypeValue;
+    /** Column header label; defaults to the field name. */
     label?: string;
+    /** Listed by the DataAPI's list route (`@Listable`). Default true. */
     listable?: boolean;
+    /** Offered to relation pickers by the select route (`@Select`). */
     selectable?: boolean;
+    /** Full-text searchable. */
     searchable?: boolean;
+    /** Sortable in the TableView. */
     sortable?: boolean;
+    /**
+     * Column-filterable in the TableView. Never on an archive field: the filter
+     * `@ArchiveField` registers serves it, and `TableView` refuses another.
+     */
     filterable?: boolean;
+    /** Field access mode. Default `"readwrite"`. */
     access?: "read" | "readwrite";
+    /** Whether the field is required. Default false → `@Optional()`. */
     required?: boolean;
+    /**
+     * Whether the Table column is indexed. When a field is created, defaults to
+     * true for `relation`, `cascader_relation` and `tree` fields and to false
+     * otherwise.
+     */
     indexed?: boolean;
+    /** The `@Column` display order. */
     order?: number;
+    /** Included in the resource's CSV export (`@Exported`). */
     exported?: boolean;
+    /** The boolean column archiving marks (`@ArchiveField`). */
     archiveField?: boolean;
+    /** Routes the field is mandatory on, e.g. `["new", "edit"]` (`@Mandatory`). */
     mandatory?: string[];
+    /**
+     * How the column is declared on the Table, as it stands: the `@Field(...)`
+     * argument and the TypeScript type. Only a handful of DataTypes map to a
+     * database type, so a field the builder did not write keeps its own
+     * declaration instead of being narrowed to the `string` fallback.
+     */
     dbField?: {
         field: string;
         ts: string;
         optional?: boolean;
+        /**
+         * The Table decorators the builder does not model — `@Localized()` and
+         * anything else its author put there — carried verbatim. Dropping one
+         * changes how the column is stored, so it is never re-derived.
+         */
         decorators?: string[];
     };
+    /**
+     * The `@Column` options the builder does not model — `defaultValue`,
+     * `description`, anything a hand-written field carries. They are read back
+     * and written again untouched, so configuring a field never silently drops
+     * what the builder did not put there.
+     */
     columnExtras?: ConfigObject;
 }
+/** A field in a `CreateResource`/`AddField` request. */
 export interface FieldSpec extends FieldAspects {
+    /** Field name — immutable; rename = `RemoveField` + `AddField`. */
     name: string;
 }
+/**
+ * A route a resource's DataAPI exposes. Selecting a subset lets a resource serve
+ * only the endpoints it needs (e.g. a singleton edit form wants `["get", "edit"]`
+ * and no list/create/delete). Each name maps to the paired `TableViewRoutes`
+ * members the engine emits:
+ *
+ * - **`list`** — the paginated table listing (`list` + `count`).
+ * - **`get`** — read a single row (detail / view).
+ * - **`create`** — create a row (`new`).
+ * - **`edit`** — update a row.
+ * - **`delete`** — delete a row.
+ * - **`select`** — option lists for relation pickers that reference this resource.
+ * - **`archive`** — soft delete + undo (`archive` + `restore`).
+ * - **`export`** — CSV/export endpoints (`exportStart`/`exportStatus`/`exportDownload`).
+ */
 export type ResourceRoute = "list" | "get" | "create" | "edit" | "delete" | "select" | "archive" | "export";
+/**
+ * Where a resource's `<name>/` folder is placed, and which barrel re-exports it.
+ * The nearest ancestor barrel to the resolved folder is wired (the root barrel is
+ * the ultimate fallback), so a relative import chain to `src/index.ts` is kept.
+ *
+ * - **Omitted** — a `<name>/` folder at the src root (`src/<name>/`), as before.
+ * - **A `dir` string** — an explicit folder relative to the src root; the resource
+ *   lands at `src/<dir>/<name>/`. Must stay within the src tree.
+ * - **`{ category }`** — the source folder of that category (mirrors page
+ *   placement): `src/<category-dir>/<name>/`. A root category falls back to the
+ *   src root.
+ * - **`{ page }`** — nested inside that page's feature folder:
+ *   `src/<page-dir>/<name>/`, so the page imports `./<name>/data-api`.
+ */
 export type ResourceLocation = string | {
     category: CategoryRef;
 } | {
     page: PageRef;
 };
+/**
+ * Input for `CreateResource`. Creates a `<name>/` folder (see `location`) and
+ * wires the nearest barrel.
+ */
 export interface CreateResourceInput {
+    /** Unique resource name — duplicate → `duplicate_name`. */
     name: string;
     displayName?: string;
+    /** DB schema; defaults to `CORE_SCHEMA_NAME`. */
     schema?: string;
     fields: FieldSpec[];
+    /** `@Fixture` seed rows; each row must supply its own `_id`. */
     seeds?: ConfigObject[];
+    /** File placement; omit for `src/<name>/`. */
     location?: ResourceLocation;
+    /**
+     * Which DataAPI routes to expose. Omit for the full set (list/get/create/edit/
+     * delete/select/archive/export); pass a subset to serve only those endpoints —
+     * an omitted route's HTTP endpoint is simply not registered. Must be non-empty
+     * when provided.
+     */
     routes?: ResourceRoute[];
+    /**
+     * The project module to write into, by its id in the project configuration. Unset, the
+     * project's own module. A module is one of the project's local modules with an `src/index.ts`;
+     * what it writes may only use declarations from that same module.
+     */
     module?: string;
 }
+/**
+ * A field as reported by `GetResourceStructure`. Aspects are present for
+ * cleanly-reversed fields; an `opaque` field (hand-edited / unknown decorator /
+ * relation) carries only `name` + `opaqueReason`.
+ */
 export interface ResourceFieldStructure extends Partial<FieldAspects> {
     name: string;
+    /** True when the field's decorator stack could not be reversed. */
     opaque?: boolean;
+    /** Set when `opaque === true`. */
     opaqueReason?: string;
 }
+/** A resource's full structure. `version` is a content hash of both files. */
 export interface ResourceStructure {
     ref: ResourceRef;
     className: string;
@@ -63,9 +167,15 @@ export interface ResourceStructure {
     schema: string;
     files: ResourceFiles;
     fields: ResourceFieldStructure[];
+    /**
+     * The exposed DataAPI routes when the resource serves a subset; omitted when it
+     * serves the full set (`TableViewRoutes.All`). Best-effort — absent for a
+     * hand-edited route map the engine could not map back to semantic names.
+     */
     routes?: ResourceRoute[];
     version: string;
 }
+/** A lightweight resource listing entry. */
 export interface ResourceSummary {
     ref: ResourceRef;
     className: string;
@@ -76,19 +186,41 @@ export interface ResourceSummary {
         database: string;
         dataApi: string;
     };
+    /** The project module the resource lives in, when it is not the project's own. */
     sourceModule?: string;
 }
+/** Options for `DeleteResource`. */
 export interface DeleteResourceOpts extends MutationOpts {
+    /**
+     * Keep the resource's database table data. By default `DeleteResource` also
+     * deletes every row of the resource's table (so a later resource reusing the
+     * name/table re-seeds cleanly instead of inheriting stale documents); set
+     * `true` to leave the data in place.
+     */
     keepData?: boolean;
 }
 export declare const CreateResource: (input: CreateResourceInput) => Promise<OpResult<{
     ref: ResourceRef;
     files: ResourceFiles;
 }>>;
+/** The resource fields `ConfigureResource` may patch. */
 export interface EditableResourceMeta {
+    /**
+     * Which DataAPI routes the resource exposes. Replaces the current set, so
+     * pass the whole list; omit the field to leave it alone.
+     */
     routes?: ResourceRoute[];
 }
+/**
+ * Patch a resource's DataAPI surface. Only what a route map can express is
+ * patchable — a resource's fields are edited with `AddField`/`ConfigureField`.
+ */
 export declare const ConfigureResource: (ref: string, patch: EditableResourceMeta, opts?: MutationOpts | undefined) => Promise<OpResult>;
+/**
+ * Delete a resource's files and, unless `keepData`, its table rows. Refused
+ * with `referential_integrity` while another resource references it (a
+ * relation field pointing at it); `blockedBy` lists those resources.
+ */
 export declare const DeleteResource: (ref: string, opts?: DeleteResourceOpts | undefined) => Promise<OpResult>;
 export declare const AddField: (ref: string, field: FieldSpec, opts?: MutationOpts | undefined) => Promise<OpResult<{
     path: FieldPath;

package/dist/resources.js

@@ -3,7 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GetResourceStructure = exports.ListResources = exports.RemoveField = exports.ConfigureField = exports.AddField = exports.DeleteResource = exports.ConfigureResource = exports.CreateResource = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
 exports.CreateResource = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Patch a resource's DataAPI surface. Only what a route map can express is
+ * patchable — a resource's fields are edited with `AddField`/`ConfigureField`.
+ */
 exports.ConfigureResource = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Delete a resource's files and, unless `keepData`, its table rows. Refused
+ * with `referential_integrity` while another resource references it (a
+ * relation field pointing at it); `blockedBy` lists those resources.
+ */
 exports.DeleteResource = (0, interface_core_1.InterfaceFunction)();
 exports.AddField = (0, interface_core_1.InterfaceFunction)();
 exports.ConfigureField = (0, interface_core_1.InterfaceFunction)();

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAwNlD,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAId,CAAC;AAcO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAMd,CAAC;AAOO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,oBAAoB,GAC/B,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2NlD,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAId,CAAC;AAUN;;;GAGG;AACU,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAMd,CAAC;AAEN;;;;GAIG;AACU,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,oBAAoB,GAC/B,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/results.d.ts

@@ -1,23 +1,68 @@
 import type { BlockPath } from "./addressing";
+/** A single file mutation staged by an operation. */
 export interface FileChange {
     path: string;
     kind: "create" | "modify" | "delete";
+    /**
+     * The change as unified diff hunks (`@@ -a,b +c,d @@`, then lines prefixed with a space, `-`
+     * or `+`), with no file headers; empty for a deleted file or folder.
+     */
     diff: string;
 }
+/** A config validation failure, addressed by a JSON pointer. */
 export type ValidationIssue = {
     pointer: string;
     message: string;
 };
+/** A TypeScript diagnostic from the in-memory typecheck gate. */
 export type TypecheckError = {
     file: string;
     line: number;
     message: string;
 };
+/** A non-fatal advisory attached to an otherwise successful operation. */
 export interface OpWarning {
-    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed" | "data_kept" | "page_not_written" | "relation_missing" | "display_not_proposed" | "module_not_loaded" | "setting_dropped" | "relation_skipped" | "display_dropped" | "field_flag_set" | "label_changed";
+    code: 
+    /** A query on the page was taken over by hand, so the draft left it alone. */
+    "query_opaque"
+    /** A query the draft dropped is still read by a block, so it was kept. */
+     | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped"
+    /** A page moved category, so its route changed and old links break. */
+     | "route_changed"
+    /** A mapped resource was deleted; its rows belong to the external database and were kept. */
+     | "data_kept"
+    /** A mapped relation's tables were written, but its TableView page could not be. */
+     | "page_not_written"
+    /** A relation the module maps is no longer in the database, or the role can no longer see it. */
+     | "relation_missing"
+    /** An SVG logo had scripts, event handlers or external references removed. */
+     | "svg_sanitized"
+    /**
+     * A relation was mapped without the `display` of its text columns, and neither a profile nor
+     * an analysis was there to propose a badge from, so those columns were written plain.
+     */
+     | "display_not_proposed"
+    /**
+     * The mapping was written, but the module it was written into did not load again afterwards:
+     * it was unloaded and did not start within the wait, or the runtime does not report it active.
+     * The message names the module; the backend log holds the error.
+     */
+     | "module_not_loaded"
+    /** A setting the page held no longer holds, because another change removed what it needed. */
+     | "setting_dropped"
+    /** A relation of a batch was left out because one of its choices was refused; the others were written. */
+     | "relation_skipped"
+    /** A column display was not written because it does not suit the column; the column is written plain. */
+     | "display_dropped"
+    /** A column was marked filterable or sortable because a view, footer figure, tab or grouping needs it. */
+     | "field_flag_set"
+    /** A relation's label was changed to one the generated code can read, or dropped when no column offers it. */
+     | "label_changed";
     message: string;
 }
+/** The scope a duplicate name collides within. */
 export type DuplicateScope = "page" | "siblings" | "category" | "resource" | "query" | "module";
+/** Every way an operation can fail. */
 export type BuilderError = {
     code: "not_found";
     ref: string;
@@ -45,6 +90,7 @@ export type BuilderError = {
     code: "typecheck_failed";
     diagnostics: TypecheckError[];
 };
+/** The result of a builder operation. On success, carries the staged changes. */
 export type OpResult<T = void> = {
     ok: true;
     data: T;
@@ -54,6 +100,8 @@ export type OpResult<T = void> = {
     ok: false;
     error: BuilderError;
 };
+/** Optional trailing options for version-checked mutations; category mutations do not accept them. */
 export interface MutationOpts {
+    /** The page or resource structure's `version` last read → `stale` on mismatch. */
     expectedVersion?: string;
 }

package/dist/structure.d.ts

@@ -2,8 +2,21 @@ import type { BlockPath, CategoryRef, PageRef } from "./addressing";
 import type { QueryStructure } from "./queries";
 import type { ResourceRef } from "./resources";
 import type { ConfigObject } from "./values";
+/**
+ * A page's permission, mirroring the DMS `MenuOptions.permission`: a partial
+ * permission spec — `id`, `title`, `icon`, `description`, `dependencies`,
+ * `defaultGranted`. The DMS also accepts an `Action` there, which is a live
+ * object rather than data and so has no encoding here; a page declaring one
+ * reads its permission back as `undefined`.
+ */
 export type PagePermission = ConfigObject;
+/**
+ * A page's Direct / Pause valve over the realtime of its blocks, mirroring the
+ * DMS `MenuOptions.live`: `maxRate`, `slowRateAfter`, `rememberKey`. Present,
+ * even empty, the page is live; absent, it refetches on every event.
+ */
 export type PageLive = ConfigObject;
+/** Page metadata the builder can read. */
 export interface PageMeta {
     ref: PageRef;
     id: string;
@@ -15,8 +28,10 @@ export interface PageMeta {
     hidden?: boolean;
     permission?: PagePermission;
     live?: PageLive;
+    /** Resolved by the builder's source index, NOT the runtime registry. */
     filepath: string;
 }
+/** The page metadata fields `ConfigurePage` may patch. */
 export interface EditablePageMeta {
     displayName: string;
     icon?: string;
@@ -27,25 +42,45 @@ export interface EditablePageMeta {
     permission?: PagePermission;
     live?: PageLive;
 }
+/** A single block in a page's tree. */
 export interface BlockNode {
     path: BlockPath;
+    /** Static key (top-level) or `.child()` id (nested). */
     name: string;
+    /** Factory name; null if unresolved. */
     type: string | null;
+    /** Whether understood options can be edited, independently of identity. */
     editable: boolean;
+    /** Set when `editable === false`. */
     opaqueReason?: string;
     slot?: string;
+    /**
+     * The child metadata beyond `slot`, as declared in the third argument of
+     * `.child()` — `{ colSpan: 2 }` on a grid child, for instance. Nested blocks
+     * only; the catalog describes the accepted shape as `childMeta`.
+     */
     meta?: ConfigObject;
+    /** Present only when editable. */
     config?: ConfigObject;
+    /** Top-level options retained on the server, with a reason for each lock. */
     lockedOptions?: Record<string, string>;
+    /**
+     * Controller-leading blocks (e.g. `TableView`): the resource ref of the leading
+     * DataAPI class argument, when it resolves to a known generated resource.
+     */
     controller?: ResourceRef;
+    /** Containers only, in `.child()` order. */
     children?: BlockNode[];
 }
+/** A page's full structure. `version` is a content hash. */
 export interface PageStructure {
     page: PageMeta;
     blocks: BlockNode[];
+    /** The query routes declared on the page, found by shape. */
     queries: QueryStructure[];
     version: string;
 }
+/** A lightweight page listing entry. */
 export interface PageSummary {
     ref: PageRef;
     id: string;
@@ -53,18 +88,25 @@ export interface PageSummary {
     category: CategoryRef;
     moduleId?: string;
     filepath: string;
+    /** The icon the menu shows beside the page. */
     icon?: string;
+    /** Sorts the page among the others of its category. */
     order?: number;
+    /** Whether the menu leaves the page out; its route still answers. */
     hidden?: boolean;
+    /** The project module the page lives in, when it is not the project's own. */
     sourceModule?: string;
 }
+/** A lightweight category listing entry. */
 export interface CategorySummary {
     ref: CategoryRef;
     displayName: string;
     parent?: CategoryRef;
     icon?: string;
+    /** Its place among its siblings in the menu, lowest first. */
     order?: number;
 }
+/** The category metadata fields `ConfigureCategory` may patch. */
 export interface EditableCategoryMeta {
     displayName: string;
     parent?: CategoryRef;