@antelopejs/interface-dms-builder 0.0.1

package/dist/resources.js

@@ -0,0 +1,13 @@
+"use strict";
+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)();
+exports.ConfigureResource = (0, interface_core_1.InterfaceFunction)();
+exports.DeleteResource = (0, interface_core_1.InterfaceFunction)();
+exports.AddField = (0, interface_core_1.InterfaceFunction)();
+exports.ConfigureField = (0, interface_core_1.InterfaceFunction)();
+exports.RemoveField = (0, interface_core_1.InterfaceFunction)();
+exports.ListResources = (0, interface_core_1.InterfaceFunction)();
+exports.GetResourceStructure = (0, interface_core_1.InterfaceFunction)();
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA4MlD,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAId,CAAC;AAcO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAMd,CAAC;AAEO,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

@@ -0,0 +1,59 @@
+import type { BlockPath } from "./addressing";
+export interface FileChange {
+    path: string;
+    kind: "create" | "modify" | "delete";
+    diff: string;
+}
+export interface ValidationIssue {
+    pointer: string;
+    message: string;
+}
+export interface TypecheckError {
+    file: string;
+    line: number;
+    message: string;
+}
+export interface OpWarning {
+    code: "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed";
+    message: string;
+}
+export type DuplicateScope = "page" | "siblings" | "category" | "resource" | "query";
+export type BuilderError = {
+    code: "not_found";
+    ref: string;
+} | {
+    code: "duplicate_name";
+    name: string;
+    scope: DuplicateScope;
+} | {
+    code: "invalid_config";
+    issues: ValidationIssue[];
+} | {
+    code: "opaque_target";
+    path: BlockPath;
+} | {
+    code: "unsupported";
+    detail: string;
+} | {
+    code: "referential_integrity";
+    blockedBy: string[];
+} | {
+    code: "stale";
+    ref: string;
+    currentVersion: string;
+} | {
+    code: "typecheck_failed";
+    diagnostics: TypecheckError[];
+};
+export type OpResult<T = void> = {
+    ok: true;
+    data: T;
+    changes: FileChange[];
+    warnings?: OpWarning[];
+} | {
+    ok: false;
+    error: BuilderError;
+};
+export interface MutationOpts {
+    expectedVersion?: string;
+}

package/dist/results.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=results.js.map

package/dist/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../src/results.ts"],"names":[],"mappings":""}

package/dist/structure.d.ts

@@ -0,0 +1,62 @@
+import type { BlockPath, CategoryRef, PageRef } from "./addressing";
+import type { QueryStructure } from "./queries";
+import type { ResourceRef } from "./resources";
+export type PagePermission = Record<string, unknown>;
+export interface PageMeta {
+    ref: PageRef;
+    id: string;
+    displayName: string;
+    icon?: string;
+    category: CategoryRef;
+    order?: number;
+    description?: string;
+    hidden?: boolean;
+    permission?: PagePermission;
+    filepath: string;
+}
+export interface EditablePageMeta {
+    displayName: string;
+    icon?: string;
+    category: CategoryRef;
+    order?: number;
+    description?: string;
+    hidden?: boolean;
+    permission?: PagePermission;
+}
+export interface BlockNode {
+    path: BlockPath;
+    name: string;
+    type: string | null;
+    editable: boolean;
+    opaqueReason?: string;
+    slot?: string;
+    meta?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    controller?: ResourceRef;
+    children?: BlockNode[];
+}
+export interface PageStructure {
+    page: PageMeta;
+    blocks: BlockNode[];
+    queries: QueryStructure[];
+    version: string;
+}
+export interface PageSummary {
+    ref: PageRef;
+    id: string;
+    displayName: string;
+    category: CategoryRef;
+    moduleId?: string;
+    filepath: string;
+}
+export interface CategorySummary {
+    ref: CategoryRef;
+    displayName: string;
+    parent?: CategoryRef;
+}
+export interface EditableCategoryMeta {
+    displayName: string;
+    parent?: CategoryRef;
+    icon?: string;
+    order?: number;
+}

package/dist/structure.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=structure.js.map

package/dist/structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../src/structure.ts"],"names":[],"mappings":""}

package/dist/values.d.ts

@@ -0,0 +1,19 @@
+export interface DataTypeValue {
+    $dataType: string;
+    config?: Record<string, unknown>;
+}
+export interface ExprValue {
+    $expr: string;
+}
+export interface RefValue {
+    $ref: {
+        resource: string;
+        as?: "dataApi" | "table" | "model";
+    };
+}
+export interface BlockValue {
+    $block: {
+        type: string;
+        config?: Record<string, unknown>;
+    };
+}

package/dist/values.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=values.js.map

package/dist/values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../src/values.ts"],"names":[],"mappings":""}

package/docs/1.introduction.md

@@ -0,0 +1,86 @@
+# DMS Builder Documentation
+
+## Overview
+
+The DMS Builder interface edits a DMS project's source tree programmatically. Where the DMS itself is authored by writing TypeScript — a `PageController` here, a `DataController` there — the builder exposes those same authoring moves as operations: create a page, add a block to it, generate a resource with its table and API, declare a query that counts rows.
+
+Every operation reads or rewrites real source files. There is no separate database of pages, and no runtime registry to keep in sync: the builder parses the project, applies the edit with an AST rewrite, typechecks the result in memory, and writes only if it compiles. What you get back is the list of files it changed.
+
+A *block* is the builder's name for one DMS component. Every type the catalog reports is a `dms-base` factory returning a `ComponentBuilder`, and `AddBlock` writes that factory call either as a static field of the page's `PageController` or as a `.child()` of another block — the same declaration you would otherwise have typed by hand.
+
+Operations are `InterfaceFunction` exports, so you import one and call it like any async function; the call is routed to the module implementing the interface. Reads such as `ListPages` return their value directly. Everything that can fail — every mutation, and the two structure reads — returns an `OpResult`, a discriminated union you branch on rather than a value you wrap in `try`.
+
+```typescript
+import type { OpResult } from "@antelopejs/interface-dms-builder";
+
+// { ok: true; data: T; changes: FileChange[]; warnings?: OpWarning[] }
+// { ok: false; error: BuilderError }
+```
+
+## Key Features
+
+- **Source as the Single Source of Truth** — Operations parse and rewrite the project's own TypeScript, so hand-written code and generated code are the same code.
+- **Typechecked Writes** — Each mutation is staged in memory, typechecked across the project, and rolled back on any diagnostic, so a rejected operation leaves nothing behind.
+- **A Discoverable Catalog** — `GetCatalog` reports every block factory and DataType the builder can emit, each with a schema for its options, so a caller validates a configuration before writing it.
+- **Stable String Addresses** — A page, a block, a category, a resource, a field and a query are each named by a plain string ref you can store and pass back into the next call.
+- **Structural Read-Back** — Blocks, resource fields and queries are read back off disk by shape, so a hand-written declaration matching the grammar is as editable as a generated one, and one that drifts out of grammar is reported as opaque rather than silently rewritten.
+- **Resource Generation** — A single call writes a `Table`, a `DataController` and a model into a wired folder, described in semantic field aspects rather than in decorators.
+- **Derived Queries** — A query template compiles into a model method and a page route, giving a card on a page a number to fetch without hand-writing either half.
+- **Optimistic Concurrency** — Structures carry a content-hash `version` you can pass back as `expectedVersion` to make the next write conditional.
+
+## Dependencies
+
+This interface relies on the following AntelopeJS packages:
+
+- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - The `InterfaceFunction` call surface every operation is declared with.
+
+The implementation lives in the dms-builder module, so the interface only works in a project that also loads `@antelopejs/dms`: the block factories and DataTypes the catalog reports are read from its [`@antelopejs/interface-dms/base`](https://github.com/AntelopeJS/dms) interface, and the pages and resources the builder writes import from it. Clearing a deleted resource's rows goes through [@antelopejs/interface-database](https://github.com/AntelopeJS/interface-database).
+
+## Quick Start
+
+The example creates a page under the root `pages` category and puts a KPI card on it.
+
+```typescript
+import {
+  AddBlock,
+  CreatePage,
+} from "@antelopejs/interface-dms-builder";
+
+const page = await CreatePage({
+  name: "revenue",
+  displayName: "Revenue",
+  category: "pages",
+  icon: "i-ph-chart-line",
+});
+if (!page.ok) {
+  throw new Error(`could not create the page: ${page.error.code}`);
+}
+
+const block = await AddBlock({
+  page: page.data.ref, // "/revenue"
+  name: "total",
+  type: "KpiCard",
+  config: {
+    title: "Total revenue",
+    icon: "i-ph-currency-eur",
+  },
+});
+if (!block.ok) {
+  throw new Error(`could not add the block: ${block.error.code}`);
+}
+
+console.log(block.data.path); // "/revenue#total"
+for (const change of block.changes) {
+  console.log(change.kind, change.path);
+}
+```
+
+## Documentation Sections
+
+- [Addressing and Structure](./2.addressing-and-structure.md) - The refs that name a page, a block and a category, and the shapes the builder reads back
+- [Catalog](./3.catalog.md) - The block types, DataTypes and reserved names the builder can report
+- [Page Operations](./4.page-operations.md) - Create pages and categories, and edit a page's block tree
+- [Resources](./5.resources.md) - Generate tables, DataAPI controllers and their fields
+- [Queries](./6.queries.md) - Compile counts and aggregates into a model method and a page route
+- [Value Encodings](./7.values.md) - Write configuration values that are not plain literals
+- [Results and Errors](./8.results-and-errors.md) - Branch on `OpResult`, read diagnostics, and make a write conditional

package/docs/2.addressing-and-structure.md

@@ -0,0 +1,207 @@
+# Addressing and Structure
+
+## Overview
+
+Every builder operation names the thing it edits with a string ref. There are three of them — a `PageRef` for a page, a `BlockPath` for a block inside a page, and a `CategoryRef` for a category — and each is a plain string you can store, log and pass back into the next call.
+
+Alongside the refs, this page describes the read shapes the builder hands back: the page metadata it can read and patch, the block tree it resolves from source, and the lightweight summaries the listing operations return. The operations that produce and consume these shapes live in [Page Operations](./4.page-operations.md).
+
+```typescript
+import type {
+  BlockPath,
+  CategoryRef,
+  PageRef,
+} from "@antelopejs/interface-dms-builder";
+
+const page: PageRef = "/dashboard";
+const block: BlockPath = "/dashboard#kpis/row/revenue";
+const category: CategoryRef = "pages.reports";
+```
+
+## Address a Page
+
+`PageRef` is a page's route string, built from its category's slug and the page's own name — a page named `revenue` under the root `pages` category is `/revenue`. `CreatePage` returns the ref it assigned, and every page operation takes it as its first argument.
+
+```typescript
+import {
+  CreatePage,
+  GetPageStructure,
+} from "@antelopejs/interface-dms-builder";
+
+const created = await CreatePage({
+  name: "revenue",
+  displayName: "Revenue",
+  category: "pages",
+});
+if (created.ok) {
+  const structure = await GetPageStructure(created.data.ref); // "/revenue"
+}
+```
+
+## Address a Block
+
+`BlockPath` addresses one block inside a page: `<pageRef>#<name>` for a top-level block, then `/<childId>` for each nesting level below it.
+
+| Path | What it addresses |
+| --- | --- |
+| `/dashboard#kpis` | The top-level block named `kpis` on `/dashboard` |
+| `/dashboard#kpis/row` | The `.child("row", …)` of that block |
+| `/dashboard#kpis/row/revenue` | The `.child("revenue", …)` of `row` |
+
+The first segment after `#` is the static class member the block is declared as; every further segment is the id passed to `.child()`. `AddBlock` returns the path of the block it added, so you rarely build one by hand.
+
+## Address a Category
+
+`CategoryRef` is a category's stable id. The three roots are `pages`, `modules` and `settings`; a category created under a parent is addressed by joining them with a dot, so a `reports` category under `pages` is `pages.reports`.
+
+```typescript
+import { CreateCategory } from "@antelopejs/interface-dms-builder";
+
+const category = await CreateCategory({
+  name: "reports",
+  displayName: "Reports",
+  parent: "pages",
+});
+// category.data.ref === "pages.reports"
+```
+
+## Read a Page's Metadata
+
+`PageMeta` is what the builder knows about a page. It comes back inside `PageStructure`, which `GetPageStructure` returns.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ref` | `PageRef` | The page's route string. |
+| `id` | `string` | The page id, the first argument of its `PageController`. |
+| `displayName` | `string` | The label shown in the menu. |
+| `icon` | `string` | Icon name, when the page declares one. |
+| `category` | `CategoryRef` | The category the page belongs to. |
+| `order` | `number` | Sort order within the category. |
+| `description` | `string` | The page's description. |
+| `hidden` | `boolean` | Whether the page is hidden from the menu. |
+| `permission` | `PagePermission` | The permission guarding the page. |
+| `filepath` | `string` | The file the page is declared in, resolved by the builder's source index rather than by the runtime registry. |
+
+`hidden` and `permission` read back like any other field, as long as the page declares them literally. A `permission` built from a call or a reference — an `Action`, say — reads back as `undefined`: the builder reports only what it can also rewrite.
+
+`PagePermission` mirrors the DMS `MenuOptions.permission`: a partial permission spec, whose fields are `id`, `title`, `icon`, `description`, `dependencies` and `defaultGranted`. A bare action id is *not* accepted — the DMS types the option as `Partial<Permission> | Action`, so a string would be written and then refused by the typecheck gate.
+
+```typescript
+import type { PagePermission } from "@antelopejs/interface-dms-builder";
+
+const permission: PagePermission = {
+  id: "reports.export",
+  title: "Export reports",
+};
+```
+
+The DMS also accepts an `Action` there. That is a live object rather than data, so it has no encoding in the builder: a page declaring one reads its permission back as `undefined`.
+
+## Patch a Page's Metadata
+
+`EditablePageMeta` is the subset of `PageMeta` that `ConfigurePage` accepts as a patch: `displayName`, `icon`, `category`, `order`, `description`, `hidden` and `permission`. `ref`, `id` and `filepath` are not patchable — they follow from where the page lives.
+
+Patching `category` moves the page, which changes its `ref`: the result carries the new one, and a `route_changed` warning says what the old route was. See [Page Operations](./4.page-operations.md).
+
+```typescript
+import type { EditablePageMeta } from "@antelopejs/interface-dms-builder";
+
+const patch: Partial<EditablePageMeta> = {
+  displayName: "Monthly revenue",
+  order: 10,
+};
+```
+
+## Read the Block Tree
+
+`BlockNode` is one block in a page's tree. The builder resolves each static member and each `.child()` call it can parse; anything it cannot parse still appears as a node, marked not editable.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `path` | `BlockPath` | The block's address. |
+| `name` | `string` | Static key for a top-level block, `.child()` id for a nested one. |
+| `type` | `string \| null` | The factory name, or `null` when it does not resolve. |
+| `editable` | `boolean` | `false` marks an opaque, non-canonical block. |
+| `opaqueReason` | `string` | Why the block is opaque. Set when `editable === false`. |
+| `slot` | `string` | The slot the block sits in, when its parent declares slots. |
+| `config` | `Record<string, unknown>` | The block's options object. Present only when the block is editable. |
+| `controller` | `ResourceRef` | For a controller-leading block such as `TableView`, the resource its leading argument resolves to, when it is a known generated resource. |
+| `children` | `BlockNode[]` | Container blocks only, in `.child()` order. |
+
+An opaque block is one the builder can see but not rewrite — a block behind an unresolved reference, or one produced by a computed expression rather than a direct factory call. Reading it is fine; `ConfigureBlock`, `AddBlock` under it and `MoveBlock` onto it fail with `opaque_target`, described in [Results and Errors](./8.results-and-errors.md).
+
+```typescript
+import { GetPageStructure } from "@antelopejs/interface-dms-builder";
+
+const result = await GetPageStructure("/dashboard");
+if (result.ok) {
+  for (const block of result.data.blocks) {
+    if (!block.editable) {
+      console.log(`${block.path} is opaque: ${block.opaqueReason}`);
+    }
+  }
+}
+```
+
+## Read a Page's Structure
+
+`PageStructure` is the whole page as the builder sees it.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `page` | `PageMeta` | The page's metadata. |
+| `blocks` | `BlockNode[]` | The top-level blocks, each carrying its own children. |
+| `queries` | `QueryStructure[]` | The query routes declared on the page, found by shape. See [Queries](./6.queries.md). |
+| `version` | `string` | A content hash of the page file. |
+
+`version` is what makes a write conditional: pass it back as `expectedVersion` on the next mutation and the operation fails with `stale` if the file changed in between. See [Results and Errors](./8.results-and-errors.md).
+
+## Read the Listings
+
+`ListPages` and `ListCategories` return summaries rather than full structures, so you can survey a project without parsing every page.
+
+`PageSummary`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ref` | `PageRef` | The page's route string. |
+| `id` | `string` | The page id. |
+| `displayName` | `string` | The label shown in the menu. |
+| `category` | `CategoryRef` | The category the page belongs to. |
+| `moduleId` | `string` | The module the page comes from, for pages declared inside a module. |
+| `filepath` | `string` | The file the page is declared in. |
+
+`CategorySummary`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `ref` | `CategoryRef` | The category's id. |
+| `displayName` | `string` | The label shown in the menu. |
+| `parent` | `CategoryRef` | The parent category, absent for a root. |
+
+```typescript
+import {
+  ListCategories,
+  ListPages,
+} from "@antelopejs/interface-dms-builder";
+
+const [pages, categories] = await Promise.all([
+  ListPages(),
+  ListCategories(),
+]);
+const rootPages = pages.filter((page) => page.category === "pages");
+```
+
+## Patch a Category's Metadata
+
+`EditableCategoryMeta` is what `ConfigureCategory` accepts: `displayName`, `parent`, `icon` and `order`. Re-parenting a category is refused — every page beneath it would change route at once; see [Page Operations](./4.page-operations.md).
+
+```typescript
+import type { EditableCategoryMeta } from "@antelopejs/interface-dms-builder";
+
+const patch: Partial<EditableCategoryMeta> = { displayName: "Reports", order: 2 };
+```
+
+## Next Steps
+
+- [Catalog](./3.catalog.md) - Discover the block types and DataTypes you can emit

package/docs/3.catalog.md

@@ -0,0 +1,176 @@
+# Catalog
+
+## Overview
+
+The catalog is the builder's answer to "what can I put on a page?". `GetCatalog` returns a `BlockCatalog`: every block factory the builder knows how to emit, every DataType a form field can use, and the field names a resource may not take. Each entry carries the import the emitter will add and a schema for the options the factory accepts, so you can validate a configuration before you write it.
+
+Read the catalog before `AddBlock`: the `type` you pass is a catalog key, and `AddBlock` rejects a type that is not in it.
+
+## Read the Catalog
+
+```typescript
+import { GetCatalog } from "@antelopejs/interface-dms-builder";
+
+const catalog = await GetCatalog();
+const kpi = catalog.blocks.find((block) => block.type === "KpiCard");
+const containers = catalog.blocks.filter((block) => block.container);
+const dataTypeIds = catalog.dataTypes.map((dataType) => dataType.id);
+```
+
+`GetCatalog` is a read: it returns a `BlockCatalog` directly, not an `OpResult`.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `blocks` | `BlockTypeDescriptor[]` | Every block factory the builder can emit and configure. |
+| `dataTypes` | `DataTypeDescriptor[]` | Every DataType usable as a form field's `type`. |
+| `reservedFieldNames` | `string[]` | Names a resource field may not take. |
+| `generatedAt` | `string` | Cache key, invalidated when the module source changes. |
+
+The catalog is cached. `RefreshSourceIndex` with no scope drops that cache; see [Page Operations](./4.page-operations.md).
+
+## Describe a Block Type
+
+`BlockTypeDescriptor` is keyed on `type`, the factory's export name.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type` | `string` | The factory export name, e.g. `KpiCard`. This is the catalog key and the value of `AddBlockInput.type`. |
+| `import` | `ImportRef` | The import the emitter adds for the factory. |
+| `container` | `boolean` | Whether the block accepts `.child(...)`. |
+| `slots` | `SlotDescriptor[]` | The named regions the block exposes, when it has any. |
+| `config` | `ConfigSchema` | A description of the factory's options object. |
+| `shapeSource` | `ShapeSource` | How the emit shape was determined. |
+| `description` | `string` | A human-readable description of the block. |
+| `controllerArg` | `boolean` | `true` when the factory takes a leading controller-class argument before its options object. |
+
+Only a `container` block can hold children, so it is the check to make before passing a block's path as `AddBlockInput.parent`.
+
+## Place a Block in a Slot
+
+A container block may declare named regions. `SlotDescriptor` describes one:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The slot id, passed as `AddBlockInput.slot`. |
+| `description` | `string` | What the slot is for. |
+
+```typescript
+import { GetCatalog } from "@antelopejs/interface-dms-builder";
+
+const catalog = await GetCatalog();
+const descriptor = catalog.blocks.find((block) => block.type === "Tab");
+const slotIds = descriptor?.slots?.map((slot) => slot.id) ?? [];
+```
+
+## Handle a Controller-Leading Block
+
+Some factories take a controller class before their options — `TableView(controller, options)` is the common case. Those descriptors carry `controllerArg: true`, and their `config` describes the *second* argument, the options object.
+
+A block type with `controllerArg: true` requires `AddBlockInput.controller`, naming the resource whose DataAPI class becomes the leading argument; passing `controller` for any other block type is rejected with `invalid_config`. Both rules are covered in [Page Operations](./4.page-operations.md).
+
+```typescript
+import { GetCatalog } from "@antelopejs/interface-dms-builder";
+
+const catalog = await GetCatalog();
+const tableView = catalog.blocks.find((block) => block.type === "TableView");
+if (tableView?.controllerArg) {
+  // AddBlock for this type must carry `controller: "<resource ref>"`.
+}
+```
+
+## Read a Config Schema
+
+`ConfigSchema` is a `Record<string, unknown>` holding a JSON-Schema-shaped description of a block's or DataType's options, generated from its TypeScript type. Keys are option names; each value describes that option — `type`, `enum` for a literal union, `properties` for a nested object, `items` for an array, `oneOf` for a union of object shapes.
+
+On top of the standard keys, the schema carries DMS extensions in the `x-` namespace. The one you act on is `x-dataType`:
+
+| Key | Meaning |
+| --- | --- |
+| `x-dataType: true` | The value is a DataType instance (`new <DataType>(...)`), such as a Form field's `type`. Pass a `DataTypeValue`, described in [Value Encodings](./7.values.md). |
+
+An option whose value holds a nested block is marked the same way, with its own `x-` key. That is rare: most nesting goes through `.child`, which you express with `AddBlockInput.parent` rather than through config.
+
+```typescript
+import { GetCatalog } from "@antelopejs/interface-dms-builder";
+
+const catalog = await GetCatalog();
+const form = catalog.blocks.find((block) => block.type === "Form");
+const fieldsOption = form?.config.fields; // schema for the `fields` option
+```
+
+## Resolve an Import
+
+`ImportRef` is the import the emitter adds when it writes a factory call, a DataType instantiation or a class reference.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The imported symbol, e.g. `KpiCard` or `DefaultDataTypes.StringType`. |
+| `module` | `string` | A package specifier, fixed and independent of the emitting file. |
+| `targetFile` | `string` | An absolute path, resolved to a specifier relative to the file being written — used for a reference to a local class such as a generated resource. |
+
+A descriptor carries one or the other: `module` for a symbol that comes from a package, `targetFile` for one that lives in the project's own source.
+
+## Know Where a Shape Came From
+
+`ShapeSource` is `"inferred" | "annotated"`, and a `BlockTypeDescriptor` reports which applies to its `config`:
+
+- **`inferred`** — the shape was read off the factory's TypeScript signature. It is as good as the types are: a well-typed options interface yields a precise schema, while a wide or generic option yields a loose one.
+- **`annotated`** — the shape was declared for the builder rather than derived from the signature.
+
+Use `shapeSource` when deciding how much to trust `config`. An empty or shallow `config` on an `inferred` descriptor means the type could not be described further, not that the factory takes no options.
+
+## Choose a DataType
+
+`DataTypeDescriptor` describes a DataType a form field's `type` (or a table column's `type`) can use.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The registered id, e.g. `string`, `number`, `select`. |
+| `import` | `ImportRef` | The import the emitter adds for the DataType class. |
+| `config` | `ConfigSchema` | A description of the DataType's options. |
+| `description` | `string` | A human-readable description. |
+
+The `id` is what you pass as `$dataType` when writing a value; see [Value Encodings](./7.values.md). A `$dataType` the catalog does not list is rejected with `invalid_config`.
+
+```typescript
+import {
+  AddBlock,
+  GetCatalog,
+} from "@antelopejs/interface-dms-builder";
+
+const catalog = await GetCatalog();
+const hasSelect = catalog.dataTypes.some((dataType) => dataType.id === "select");
+
+await AddBlock({
+  page: "/customers",
+  name: "editor",
+  type: "Form",
+  config: {
+    fields: [
+      {
+        id: "name",
+        label: "Name",
+        type: { $dataType: "string" },
+      },
+    ],
+  },
+});
+```
+
+## Avoid a Reserved Field Name
+
+`reservedFieldNames` lists the names a resource field may not take: they collide with a generated DataController route or a Model member, and `CreateResource` or `AddField` rejects them with `invalid_config`. Reading them from the catalog saves you carrying your own copy of the list.
+
+```typescript
+import { GetCatalog } from "@antelopejs/interface-dms-builder";
+
+const catalog = await GetCatalog();
+const reserved = new Set(catalog.reservedFieldNames);
+const fieldName = reserved.has("status") ? "state" : "status";
+```
+
+Resource fields are covered in [Resources](./5.resources.md).
+
+## Next Steps
+
+- [Page Operations](./4.page-operations.md) - Create pages and categories, and edit a page's block tree