@antelopejs/interface-dms-builder 0.2.2 → 0.2.3

package/dist/analysis.d.ts

@@ -0,0 +1,124 @@
+import type { ResourceRef } from "./resources";
+import type { OpResult } from "./results";
+export type ProposedKind = "fact" | "default";
+export interface Proposed<T> {
+    value: T;
+    rule: string;
+    kind: ProposedKind;
+}
+export interface ProposedDeclaration extends Proposed<string> {
+    lossy?: string;
+}
+export interface ProposedRelationColumn extends Proposed<string> {
+    implied: boolean;
+}
+export interface ProposedRange {
+    min: number | string;
+    max: number | string;
+}
+export interface ProposedCategory {
+    value: string | number | boolean;
+    rows: number;
+}
+export interface ProposedColumnProfile {
+    traits: string[];
+    nulls?: number;
+    distinct?: number;
+    range?: ProposedRange;
+    categories?: ProposedCategory[];
+}
+export interface ProposedField {
+    column: string;
+    native: string;
+    accepts: string[];
+    declared: ProposedDeclaration;
+    label: Proposed<string>;
+    listable: Proposed<boolean>;
+    filterable: Proposed<boolean>;
+    sortable: Proposed<boolean>;
+    searchable: Proposed<boolean>;
+    relation?: ProposedRelationColumn;
+    profile?: ProposedColumnProfile;
+}
+export interface ProposedLeftOut {
+    column: string;
+    reason: string;
+    rule: string;
+}
+export interface ProposedWrites {
+    insert: boolean;
+    update: boolean;
+    delete: boolean;
+}
+export interface ProposedResource {
+    relation: string;
+    tableView: Proposed<boolean>;
+    writable: Proposed<boolean>;
+    label: Proposed<string | null>;
+    title: Proposed<string>;
+    fields: ProposedField[];
+    leftOut: ProposedLeftOut[];
+    writes: ProposedWrites;
+}
+export interface ProposedExclusion {
+    relation: string;
+    reason: string;
+    rule: string;
+}
+export type OpenItemKind = "schemas" | "purpose" | "label" | "reference";
+export interface OpenItemOption {
+    value: unknown;
+    title: string;
+}
+export interface OpenItem {
+    id: string;
+    kind: OpenItemKind;
+    relation?: string;
+    column?: string;
+    question: string;
+    options: OpenItemOption[];
+    proposed: unknown;
+    resource?: ProposedResource;
+}
+export interface ProposalDatabase {
+    engine: string;
+    role: string;
+    writes: "none" | "some" | "all";
+}
+export interface MappingProposal {
+    connection: string;
+    module: string;
+    database: ProposalDatabase;
+    resources: ProposedResource[];
+    excluded: ProposedExclusion[];
+    open: OpenItem[];
+}
+export interface AnalyseDatabaseInput {
+    connection: string;
+    module: string;
+    schemas?: string[];
+}
+export interface AnalysisProgress {
+    relations: number;
+    described: number;
+    toProfile: number;
+    profiled: number;
+    timeouts: number;
+}
+export type AnalysisStatus = "running" | "done" | "failed";
+export interface AnalysisState {
+    id: string;
+    connection: string;
+    status: AnalysisStatus;
+    progress: AnalysisProgress;
+    proposal?: MappingProposal;
+    error?: string;
+}
+export declare const AnalyseDatabase: (input: AnalyseDatabaseInput) => Promise<OpResult<AnalysisState>>;
+export declare const GetAnalysis: (id: string) => Promise<OpResult<AnalysisState>>;
+export interface MappedRelation {
+    ref: ResourceRef;
+    resource: ProposedResource;
+    included: string[];
+}
+export declare const GetMapping: (connection: string, module: string) => Promise<OpResult<MappedRelation[]>>;

package/dist/analysis.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetMapping = exports.GetAnalysis = exports.AnalyseDatabase = void 0;
+const interface_core_1 = require("@antelopejs/interface-core");
+exports.AnalyseDatabase = (0, interface_core_1.InterfaceFunction)();
+exports.GetAnalysis = (0, interface_core_1.InterfaceFunction)();
+exports.GetMapping = (0, interface_core_1.InterfaceFunction)();
+//# sourceMappingURL=analysis.js.map

package/dist/analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAoLlD,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AAMO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAAoD,CAAC;AAc3D,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export * from "./addressing";
+export * from "./analysis";
 export * from "./catalog";
 export * from "./drafts";
+export * from "./mapping";
 export * from "./operations";
+export * from "./project";
 export * from "./queries";
 export * from "./resources";
 export * from "./results";

package/dist/index.js

@@ -15,9 +15,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./addressing"), exports);
+__exportStar(require("./analysis"), exports);
 __exportStar(require("./catalog"), exports);
 __exportStar(require("./drafts"), exports);
+__exportStar(require("./mapping"), exports);
 __exportStar(require("./operations"), exports);
+__exportStar(require("./project"), exports);
 __exportStar(require("./queries"), exports);
 __exportStar(require("./resources"), exports);
 __exportStar(require("./results"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,4CAA0B;AAC1B,2CAAyB;AACzB,+CAA6B;AAC7B,4CAA0B;AAC1B,8CAA4B;AAC5B,4CAA0B;AAC1B,8CAA4B;AAC5B,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,6CAA2B;AAC3B,4CAA0B;AAC1B,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,4CAA0B;AAC1B,4CAA0B;AAC1B,8CAA4B;AAC5B,4CAA0B;AAC1B,8CAA4B;AAC5B,2CAAyB"}

package/dist/mapping.d.ts

@@ -0,0 +1,49 @@
+import type { CategoryRef, PageRef } from "./addressing";
+import type { ResourceRef } from "./resources";
+import type { OpResult } from "./results";
+export interface MappedField {
+    column: string;
+    declared?: string;
+    label?: string;
+    listable?: boolean;
+    filterable?: boolean;
+    sortable?: boolean;
+    searchable?: boolean;
+    relation?: string;
+}
+export interface MappedResource {
+    relation: string;
+    className?: string;
+    label?: string;
+    title?: string;
+    tableView: boolean;
+    writable: boolean;
+    fields: MappedField[];
+}
+export interface ExcludedRelation {
+    relation: string;
+    reason: string;
+}
+export interface MapResourcesInput {
+    module: string;
+    connection: string;
+    resources: MappedResource[];
+    excluded?: ExcludedRelation[];
+}
+export interface LeftOutColumn {
+    relation: string;
+    column: string;
+    reason: string;
+}
+export interface MappedResult {
+    relation: string;
+    ref: ResourceRef;
+    page?: PageRef;
+    files: string[];
+}
+export interface MapResourcesResult {
+    resources: MappedResult[];
+    leftOut: LeftOutColumn[];
+    category?: CategoryRef;
+}
+export declare const MapResources: (input: MapResourcesInput) => Promise<OpResult<MapResourcesResult>>;

package/dist/mapping.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapResources = void 0;
+const interface_core_1 = require("@antelopejs/interface-core");
+exports.MapResources = (0, interface_core_1.InterfaceFunction)();
+//# sourceMappingURL=mapping.js.map

package/dist/mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAmGlD,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/operations.d.ts

@@ -15,6 +15,7 @@ export interface CreatePageInput {
     description?: string;
     permission?: PagePermission;
     dir?: string;
+    module?: string;
 }
 export interface CreateCategoryInput {
     name: string;
@@ -22,6 +23,7 @@ export interface CreateCategoryInput {
     parent?: CategoryRef;
     icon?: string;
     order?: number;
+    module?: string;
 }
 export interface AddBlockInput {
     page: PageRef;

package/dist/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA4FlD,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAC9D,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,UAAU,GAAG,IAAA,kCAAiB,GAA+B,CAAC;AAS9D,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAAsD,CAAC;AAM7D,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAId,CAAC;AAOO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAA4D,CAAC;AAEnE,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAoGlD,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAC9D,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,UAAU,GAAG,IAAA,kCAAiB,GAA+B,CAAC;AAS9D,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAAsD,CAAC;AAM7D,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAId,CAAC;AAOO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAA4D,CAAC;AAEnE,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/project.d.ts

@@ -0,0 +1,40 @@
+import type { OpResult } from "./results";
+export interface ImportOverrideInput {
+    interface: string;
+    source?: string;
+    id?: string;
+}
+export interface ModuleEntryInput {
+    source?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    env?: Record<string, string>;
+    importOverrides?: ImportOverrideInput[];
+    exportPriority?: Record<string, number>;
+}
+export interface AddModuleStep {
+    op: "AddModule";
+    id: string;
+    entry: ModuleEntryInput;
+}
+export interface ConfigureModuleStep {
+    op: "ConfigureModule";
+    id: string;
+    entry: ModuleEntryInput;
+}
+export interface CreateLocalModuleStep {
+    op: "CreateLocalModule";
+    id: string;
+    path: string;
+    entry?: ModuleEntryInput;
+}
+export type ProjectConfigStep = AddModuleStep | ConfigureModuleStep | CreateLocalModuleStep;
+export interface ProjectConfigOpts {
+    dryRun?: boolean;
+}
+export interface ProjectConfigResult {
+    files: string[];
+}
+export declare const ConfigureProject: (steps: ProjectConfigStep[], opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+export declare const AddModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+export declare const ConfigureModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+export declare const CreateLocalModule: (id: string, path: string, entry?: ModuleEntryInput | undefined, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;

package/dist/project.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateLocalModule = exports.ConfigureModule = exports.AddModule = exports.ConfigureProject = void 0;
+const interface_core_1 = require("@antelopejs/interface-core");
+exports.ConfigureProject = (0, interface_core_1.InterfaceFunction)();
+exports.AddModule = (0, interface_core_1.InterfaceFunction)();
+exports.ConfigureModule = (0, interface_core_1.InterfaceFunction)();
+exports.CreateLocalModule = (0, interface_core_1.InterfaceFunction)();
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA8ElD,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"}

package/dist/resources.d.ts

@@ -48,6 +48,7 @@ export interface CreateResourceInput {
     seeds?: Record<string, unknown>[];
     location?: ResourceLocation;
     routes?: ResourceRoute[];
+    module?: string;
 }
 export interface ResourceFieldStructure extends Partial<FieldAspects> {
     name: string;
@@ -75,6 +76,7 @@ export interface ResourceSummary {
         database: string;
         dataApi: string;
     };
+    sourceModule?: string;
 }
 export interface DeleteResourceOpts extends MutationOpts {
     keepData?: boolean;

package/dist/resources.js.map

@@ -1 +1 @@
-{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAgNlD,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;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"}

package/dist/results.d.ts

@@ -14,10 +14,10 @@ export interface TypecheckError {
     message: string;
 }
 export interface OpWarning {
-    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed";
+    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed" | "data_kept" | "page_not_written" | "relation_missing";
     message: string;
 }
-export type DuplicateScope = "page" | "siblings" | "category" | "resource" | "query";
+export type DuplicateScope = "page" | "siblings" | "category" | "resource" | "query" | "module";
 export type BuilderError = {
     code: "not_found";
     ref: string;

package/dist/structure.d.ts

@@ -55,6 +55,7 @@ export interface PageSummary {
     icon?: string;
     order?: number;
     hidden?: boolean;
+    sourceModule?: string;
 }
 export interface CategorySummary {
     ref: CategoryRef;

package/docs/1.introduction.md

@@ -1,44 +1,14 @@
 # DMS Builder Documentation
 
-## Overview
+Use `@antelopejs/interface-dms-builder` to create and edit DMS pages from a backend module or a tool. The operations write ordinary TypeScript into your project; there is no separate database of page definitions.
 
-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).
+If you want to edit a page with the mouse instead, start with the [visual builder guide](https://dms.antelopejs.com/docs/modules/builder/introduction).
 
 ## Quick Start
 
-The example creates a page under the root `pages` category and puts a KPI card on it.
+This example creates a **Revenue** page with a **Total revenue** card. Run it once from a backend module after the builder is available, in a development project that loads both `@antelopejs/dms` and `@antelopejs/dms-builder`. Installing the interface package alone does not provide the implementation.
+
+The project must already have a `pages` category. Use `ListCategories()` to find yours, or [create a category](./4.page-operations.md) first. Choose an unused page name: running a creation twice returns `duplicate_name`.
 
 ```typescript
 import {
@@ -75,6 +45,25 @@ for (const change of block.changes) {
 }
 ```
 
+After the backend reloads, open `/revenue` as a tenant owner. You should see the page and its card; the card has no revenue data yet. [Queries](./6.queries.md) connects a card to a resource when you are ready for real numbers.
+
+Each call saves independently. If `CreatePage` succeeds but `AddBlock` fails, the empty page remains; fix the block configuration and retry that call, not the page creation.
+
+## How an edit reaches your files
+
+A *block* is one DMS component, such as a card or a table. Adding one writes a factory call into a `PageController` class, either as a static field or as a child of another block. The builder parses the source, stages the edit in memory and typechecks the project before writing it. A type error anywhere in the project can therefore block the edit.
+
+Operations are `InterfaceFunction` exports from `@antelopejs/interface-core`. Expected failures return values you can inspect:
+
+```typescript
+// Success: { ok: true, data, changes, warnings? }
+// Failure: { ok: false, error }
+```
+
+Listing operations such as `ListPages` return their value directly. See [Results and errors](./8.results-and-errors.md) for the full contract. When you read before writing, pass the structure's `version` as `expectedVersion` so another editor's work is not overwritten.
+
+Hand-written declarations remain editable when the builder recognizes their shape. Otherwise, it marks them *opaque*: you can inspect them without asking the builder to rewrite code it does not understand. Use [Drafts and preview](./9.drafts-and-preview.md) when an editor needs to save a whole block tree in one transaction.
+
 ## 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

package/docs/10.a-chart-without-code.md

@@ -1,30 +1,18 @@
 # A Chart Without Code
 
-The journey the no-code data sources were built for, end to end: someone picks a
-resource, a measure and a grouping, sees their own data, saves, and reopens the
-page to find it as they left it. No route written, no endpoint typed.
+Build an editor that lets someone choose a table, a measure and a grouping, then
+save a chart without writing its data route by hand. This walkthrough follows the
+interface calls behind the visual builder; it is not a standalone script.
 
-This page follows what the engine does underneath, so a consumer building that
-experience knows which call belongs where.
+![The visual builder with a chart selected and its settings open](./images/editor-selected.png)
 
-## What the block asks for
+You need an existing `/shop/board` page and an `order` resource with numeric
+`amount`, date `createdAt` and `status` fields. Run these calls inside a project
+that loads the builder. Use a disposable page for the save example: its draft
+replaces the page's existing blocks.
 
-A block declares the shape of answer it can read, next to its factory:
-
-```typescript
-fetchUrl: ui(z.string().optional(), {
-  label: "Data source",
-  group: "data",
-  widget: "dataSource",
-  responseShape: "card",
-  periodOption: "periodScope",
-});
-```
-
-An editor reads that from the catalog and offers only calculations whose answer
-the block can display — a series cannot be wired into a slot that renders one
-number — and knows which of the block's own options carries the period, so
-binding a source writes both in one patch.
+The result is a revenue chart grouped by month. Start with all paid orders;
+add period controls and comparison only after this first chart works.
 
 ## Show the data before writing anything
 
@@ -50,13 +38,19 @@ const preview = await PreviewQuery({
     response: "card",
   },
 });
+if (preview.ok) {
+  console.log(preview.data.body); // Chart-card data from the current rows
+  console.log(preview.data.truncated);
+} else {
+  console.error(preview.error);
+}
 ```
 
-Nothing has been written at this point: no route, no model method, no file. The
-numbers on screen are the ones the saved page will show, because the calculation
-previewed and the calculation written are the same plan rendered two ways — and
-`preview.data.body` is the envelope the route will serve, arranged by the same
-helper, so the card's headline figure is previewed rather than guessed at.
+Nothing has been written yet. On success, `preview.data.body` has the response
+shape the chart card reads, including its headline figure. The saved route uses
+the same calculation, but its values can change as rows change. Check `truncated`
+before treating a limited preview as a complete result. For a per-tenant resource,
+also pass the tenant id in `PreviewQuery`'s `tenant` option.
 
 ## Save the block and its data together
 
@@ -64,9 +58,12 @@ The query travels in the page draft, so one save writes the block, the model
 method and the route in a single transaction:
 
 ```typescript
-import { SetPageBlocks } from "@antelopejs/interface-dms-builder";
+import { GetPageStructure, SetPageBlocks } from "@antelopejs/interface-dms-builder";
 
-await SetPageBlocks("/shop/board", {
+const current = await GetPageStructure("/shop/board");
+if (!current.ok) throw new Error(current.error.code);
+
+const saved = await SetPageBlocks("/shop/board", {
   blocks: [
     {
       name: "revenueCard",
@@ -74,7 +71,6 @@ await SetPageBlocks("/shop/board", {
       config: {
         title: "Revenue",
         fetchUrl: "/dms/pages/shop/board/stats/revenue-chart",
-        periodScope: "page",
         chart: {
           $block: { type: "ChartArea", config: { xaxisType: "category" } },
         },
@@ -92,21 +88,18 @@ await SetPageBlocks("/shop/board", {
         groupBy: "createdAt",
         bucket: "month",
         timezone: "Europe/Brussels",
-        where: [
-          { field: "status", op: "eq", value: "paid" },
-          { field: "createdAt", op: "ge", value: { $param: { name: "from" } } },
-          { field: "createdAt", op: "le", value: { $param: { name: "to" } } },
-        ],
+        where: [{ field: "status", op: "eq", value: "paid" }],
       },
       response: "card",
-      compare: true,
     },
   ],
-});
+}, { expectedVersion: current.data.version });
+if (!saved.ok) throw new Error(saved.error.code);
 ```
 
-Either all of it lands or none of it does. A draft that fails on its query leaves
-the blocks as they were.
+After the backend reloads, open `/shop/board` as a tenant owner. The card reads
+`/dms/pages/shop/board/stats/revenue-chart` and shows the saved calculation.
+Either the blocks and query save together or neither changes.
 
 Two details the engine will hold you to. The block and the query cannot share a
 name: both become members of the page class, so a query named after the block it
@@ -115,7 +108,18 @@ what it is and the query for what it answers. And a `ChartCard` requires the
 chart it wraps, so a config without `chart` fails the save on `typecheck_failed`
 rather than on a validation message.
 
-## What ends up in the project
+## Reference: add a period and comparison
+
+The first example intentionally has no period filter. To make the chart follow a
+page period, add `periodScope: "page"` to the card, bind `from` and `to` in the
+query's date filters, and supply the page's period selector. Set `compare: true`
+only when requests also supply `compareFrom` and `compareTo`. Pass the same filters
+and arguments to `PreviewQuery` to preview that period, rather than all paid orders.
+See [request-time bindings](./6.queries.md#bind-a-value-at-request-time).
+
+With those period filters added, the generated code has the following shape.
+These fragments illustrate the model method and route; they are not extra files
+you need to write for the walkthrough.
 
 A method on the resource's model:
 
@@ -171,11 +175,15 @@ the measure's own word, and a reader who never asked for one would be shown "sum
 produced them, so the editor reopens filled in rather than empty:
 
 ```typescript
+import { GetPageStructure } from "@antelopejs/interface-dms-builder";
+
 const structure = await GetPageStructure("/shop/board");
-const source = structure.data.queries.find((q) => q.name === "revenueChart");
-// source.template === "series"
-// source.response === "card"
-// source.params  === the parameters above, with the ordering made explicit
+if (structure.ok) {
+  const source = structure.data.queries.find((q) => q.name === "revenueChart");
+  console.log(source?.template); // "series"
+  console.log(source?.response); // "card"
+  console.log(source?.params); // Saved parameters, including explicit ordering
+}
 ```
 
 That read-back is what makes the journey repeatable rather than one-way. It is
@@ -187,9 +195,28 @@ rewrite it.
 
 | Guarantee | Where it comes from |
 | --- | --- |
-| The preview matches the saved page | One `QueryPlan`, rendered by the emitter and run by the executor |
+| Preview and saved queries use the same calculation | One `QueryPlan`, rendered by the emitter and run by the executor; rows and preview limits can differ |
 | The block and its data save together | `PageDraft.queries`, written in the page's transaction |
 | Reopening shows what was configured | The chain reads back into its parameters |
 | A developer's edit survives | An unreadable chain is opaque, and opaque is never rewritten |
 | The data is not public | The route carries the page's permission |
 | A tenant reads its own rows | The model provider is chosen from the resource's schema |
+
+## Reference: what the block asks for
+
+A block declares the response shape it can read beside its factory. The editor
+uses this catalog metadata to offer compatible calculations and find the option
+that controls the period:
+
+```typescript
+fetchUrl: ui(z.string().optional(), {
+  label: "Data source",
+  group: "data",
+  widget: "dataSource",
+  responseShape: "card",
+  periodOption: "periodScope",
+});
+```
+
+This is a schema fragment for a block author, not configuration to pass to
+`AddBlock`. An editor consumer reads it from [the catalog](./3.catalog.md).

package/docs/11.external-databases.md

@@ -0,0 +1,150 @@
+# External Databases
+
+## Overview
+
+A DMS project can show pages over a database it does not own: a client's PostgreSQL, read and written live through a postgres module in external mode. The builder takes such a database in four moves, each an operation:
+
+1. **Wire it** into `antelope.config.ts` with `ConfigureProject`: the provider module, a local module for its tables, and the builder's catalog connection.
+2. **Analyse it** with `AnalyseDatabase`, which reads the catalog and proposes a mapping by fixed rules. It writes nothing.
+3. **Decide** the proposal: a person in the builder's *Database* workspace, or an assistant through these operations.
+4. **Map it** with `MapResources`, which writes table classes, controllers and TableView pages into the module bound to the database.
+
+The builder reaches the database through `@antelopejs/interface-database-catalog`, a connection declared on its own module entry. It never connects with credentials of its own.
+
+## Wire the Project
+
+`ConfigureProject(steps, opts?)` applies its steps to `antelope.config.ts` as one edit. Every step is validated before anything is written, and a refused step writes nothing. With `{ dryRun: true }` it answers the changes it would make, as `OpResult.changes`, so a caller can show the diff before writing.
+
+| Step | Writes |
+| --- | --- |
+| `AddModule` | a module entry, refusing an id that exists |
+| `ConfigureModule` | merges config, `importOverrides` (pins and connection ids), `exportPriority` and env variable names into an entry |
+| `CreateLocalModule` | scaffolds a local module and adds its entry |
+
+`env` takes variable names, never values: each is added to `envOverrides`, and to `.env.example` when the project has one.
+
+```typescript
+import { ConfigureProject } from "@antelopejs/interface-dms-builder";
+
+const catalog = "@antelopejs/interface-database-catalog";
+
+const result = await ConfigureProject([
+  {
+    op: "AddModule",
+    id: "postgres-erp",
+    entry: {
+      source: { type: "package", package: "@antelopejs/postgres", version: "^0.2.0" },
+      config: { mode: "external", statementTimeoutMs: 30000 },
+      env: { url: "ERP_DATABASE_URL" },
+    },
+  },
+  {
+    op: "CreateLocalModule",
+    id: "erp-tables",
+    path: "modules/erp-tables",
+    entry: {
+      importOverrides: [{ interface: "@antelopejs/interface-database", source: "postgres-erp" }],
+    },
+  },
+  {
+    op: "ConfigureModule",
+    id: "mongodb",
+    entry: { exportPriority: { "@antelopejs/interface-database": 1 } },
+  },
+  {
+    op: "ConfigureModule",
+    id: "dms-builder",
+    entry: { importOverrides: [{ interface: catalog, source: "postgres-erp", id: "erp" }] },
+  },
+]);
+```
+
+The connection exists once the project restarts with the variable set.
+
+## Analyse a Database
+
+`AnalyseDatabase({ connection, module, schemas? })` starts a job and answers it at once: profiling a database takes a while. `GetAnalysis(id)` answers the job's `progress` while it runs, then its `proposal`, or its `error`.
+
+```typescript
+import { AnalyseDatabase, GetAnalysis } from "@antelopejs/interface-dms-builder";
+
+const started = await AnalyseDatabase({ connection: "erp", module: "erp-tables" });
+if (started.ok) {
+  const state = await GetAnalysis(started.data.id);
+  // state.data.status: "running" | "done" | "failed"
+}
+```
+
+- One job runs per connection. Starting another while one runs answers the running one.
+- A finished job is kept until the next one on its connection, or a restart.
+- Relations the module has mapped, or recorded as excluded, are not proposed again.
+- Above 200 relations to profile, the proposal holds a single `schemas` question instead, and the analysis runs again with `schemas`.
+
+## Read a Proposal
+
+A `MappingProposal` is a `MapResources` input in which every choice says where it came from:
+
+```typescript
+interface Proposed<T> {
+  value: T;
+  rule: string;            // "R6", "L1", "F5"…
+  kind: "fact" | "default";
+}
+```
+
+A **fact** follows from the catalog with no judgement. A **default** is a judgement to check.
+
+| Rule | When | Then |
+| --- | --- | --- |
+| R1 | the catalog says unmappable | excluded, with its reason |
+| R2 | no key | stats only: table class and model, no page |
+| R3 | no rows | excluded |
+| R4 | a framework's or a migration tool's table | excluded |
+| R5 | keyed by its two foreign keys | stats only |
+| R6 | keyed, with rows and a label | TableView |
+| R7 | keyed, no label, referenced | TableView labelled by its key, and a `label` question |
+| R8 | keyed, no label, not referenced, with a time axis | stats only |
+| R9 | anything else | a `purpose` question, nothing proposed |
+| L1, L2 | the label by name, then by order; titles from short comments, else from names | |
+| F1–F5 | columns no type reads and secrets left out; the first declaration; declared foreign keys and references found whole as relation columns | |
+| W1 | every TableView | read-only |
+
+Each field also carries the declarations its column `accepts`, and its profile's aggregates: traits, nulls, distinct values, range and categories. Never a row.
+
+What the rules could not decide is in `open`, each item with its options and what the proposal holds meanwhile. A `purpose` item carries the `resource` it would map, should the answer be to map it.
+
+## Map Relations
+
+`MapResources(input)` reads the descriptions of the relations through the builder's connection, checks every choice against them, and writes in one typechecked transaction. Then it creates the connection's category `pages.<connection>` and the TableView pages.
+
+```typescript
+import { MapResources } from "@antelopejs/interface-dms-builder";
+
+const result = await MapResources({
+  module: "erp-tables",
+  connection: "erp",
+  resources: [
+    {
+      relation: "erp.customers",
+      label: "name",
+      title: "Customers",
+      tableView: true,
+      writable: false,
+      fields: [{ column: "name", searchable: true }, { column: "segment", filterable: true }],
+    },
+  ],
+  excluded: [{ relation: "erp.audit_log", reason: "a log" }],
+});
+```
+
+- **Names are the database's own.** `_id` is declared only where the relation has a key, and nothing creates or alters a table.
+- **Relation columns** point at a relation of the batch, or one the module mapped before, by its single-column key.
+- **Mapping again** a relation already mapped rewrites it from the new choices. Its page is created, kept or removed as `tableView` says.
+- **`excluded`** is recorded in the module's `package.json`, so the next analysis does not propose those relations. Mapping one later removes it from the record.
+- **In a mapped module**, `CreateResource` and `AddField` are refused, since its tables are the database's. `DeleteResource` keeps the client's rows and warns `data_kept`.
+
+## Next Steps
+
+- [Resources](./5.resources.md): the resources a mapping writes are ordinary ones, read the same way.
+- [Queries](./6.queries.md): stats over a mapped relation name it by its ref.
+- [Results and Errors](./8.results-and-errors.md): branch on what every operation answers.

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

@@ -2,7 +2,7 @@
 
 ## 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.
+Every builder operation identifies its target with a string ref. This page covers `PageRef` for a page, `BlockPath` for a block inside it, and `CategoryRef` for a menu category. [Resources](./5.resources.md) and [Queries](./6.queries.md) define their own refs.
 
 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).
 
@@ -102,7 +102,7 @@ The DMS also accepts an `Action` there. That is a live object rather than data,
 
 ## 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.
+`EditablePageMeta` is the subset of `PageMeta` that `ConfigurePage` accepts as a patch: `displayName`, `icon`, `category`, `order`, `description`, `hidden`, `permission` and `live`. `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).
 
@@ -127,6 +127,7 @@ const patch: Partial<EditablePageMeta> = {
 | `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. |
+| `meta` | `Record<string, unknown>` | Child metadata beyond `slot`, such as `{ colSpan: 2 }`. Keep it when constructing a draft from the tree. |
 | `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. |

package/docs/6.queries.md

@@ -1,8 +1,29 @@
 # Queries
 
-## Overview
+## Count rows without writing a route
 
-A query is derived data: a count, a sum, an average taken over a resource's rows and served from a page. `AddQuery` compiles a query template into a method on the resource's model and a route on the page's controller, so a block on that page can fetch its data without you writing either half.
+A query gives a page data to display: a count, a total or a series of points. With an existing `/books` page and a `book` resource, this example creates a route that counts the books:
+
+```typescript
+import { AddQuery } from "@antelopejs/interface-dms-builder";
+
+const result = await AddQuery("/books", {
+  name: "bookCount",
+  resource: "book",
+  template: "count",
+});
+if (result.ok) {
+  console.log(result.data.route); // "/dms/pages/books/stats/book-count"
+} else {
+  console.error(result.error);
+}
+```
+
+After the backend reloads, a signed-in user with access to `/books` can request that URL through the frontend. It returns `{ "value": N }`, where `N` is the number of rows. The operation writes a model method and a page route; it does not add a visible block. Use the returned `route` as the block's `fetchUrl`.
+
+Choose an unused query name. For an editor that must preview before saving, use [PreviewQuery and page drafts](./9.drafts-and-preview.md) instead of calling `AddQuery` on each change.
+
+## Query reference
 
 The route is guarded with the page's own permission, as a parameter decorator on that route alone: whoever may open the page may read what it derives, and no other route on the controller is affected.
 
@@ -198,7 +219,7 @@ await AddQuery("/dashboard", {
     where: [{ field: "status", op: "eq", value: "paid" }],
   },
 });
-// GET /dashboard/stats/monthly-revenue
+// GET /dms/pages/dashboard/stats/monthly-revenue
 // { series: [{ x: 202601, y: 1250 }, { x: 202602, y: 980 }] }
 ```
 
@@ -217,7 +238,7 @@ await AddQuery("/dashboard", {
 Three rules worth planning for:
 
 - **A series is always ordered.** Databases return groups in no particular order — MongoDB scrambles them — so an ordering is emitted whether or not you ask for one. Omitting `orderBy` gives a timeline: the group, ascending.
-- **Omitting `timezone` buckets in UTC**, which moves every row near a period boundary into its neighbour. Pass the zone the reader thinks in.
+- **Omitting `timezone` buckets in UTC.** A row near a period boundary may belong to a different bucket in the reader's local time. Pass the zone the reader uses for reporting.
 - **A top N is an ordering plus a limit**, not a separate template: `orderBy: "measure"`, `direction: "desc"`, `limit: 5`.
 
 There is no week bucket. Neither database adapter exposes an ISO week, and deriving one from the day of the year puts the first days of January in the previous year's week — a wrong week being worse than a missing one.
@@ -264,7 +285,7 @@ await AddQuery("/dashboard", {
   response: "card",
   compare: true,
 });
-// GET /dashboard/stats/revenue?from=…&to=…&compareFrom=…&compareTo=…
+// GET /dms/pages/dashboard/stats/revenue?from=…&to=…&compareFrom=…&compareTo=…
 // { value, series, previousValue, delta, comparisonSeries }
 ```
 
@@ -320,11 +341,12 @@ A query that no longer parses still reports its `endpoint`, `resource` and `mode
 
 ```typescript
 import { GetPageStructure } from "@antelopejs/interface-dms-builder";
+import { pageRoutePath } from "@antelopejs/interface-dms/page";
 
 const result = await GetPageStructure("/books");
 if (result.ok) {
   const editable = result.data.queries.filter((query) => !query.opaque);
-  const urls = result.data.queries.map((query) => `/books${query.endpoint}`);
+  const urls = result.data.queries.map((query) => pageRoutePath("/books", query.endpoint));
 }
 ```
 

package/docs/7.values.md

@@ -4,10 +4,11 @@
 
 Configuration values are plain JSON by default. `AddBlockInput.config`, a `ConfigureBlock` patch, a page's `permission` — all of it is written to source exactly as you pass it, as a literal.
 
-Some values are not literals. A Form field's `type` is a `new DefaultDataTypes.StringType(...)` instance; a `TableView`'s controller is a class identifier with an import behind it. Three sentinel object shapes cover those cases: `DataTypeValue` for a DataType instance, `RefValue` for a builder-generated class, and `ExprValue` for a raw expression the builder cannot model. Each is recognized wherever a config value is read, at any depth — inside an array, inside a nested object.
+Some options need TypeScript values rather than JSON literals. A form field needs a DataType instance, a relation needs a controller class, and a chart card needs a nested chart. The structured encodings below let the builder write those values and their imports. Use a raw `$expr` only as an escape hatch; drafts and query parameters reject it.
 
 ```typescript
 import type {
+  BlockValue,
   DataTypeValue,
   ExprValue,
   RefValue,
@@ -21,6 +22,7 @@ import type {
 | A string, number, boolean, array or object | The value itself, as JSON. |
 | A value the catalog marks `x-dataType` | `DataTypeValue` |
 | A reference to a builder-generated resource class | `RefValue` |
+| A nested component in an option marked `x-component` | `BlockValue` |
 | Anything else that must reach the source as code | `ExprValue` |
 
 The catalog is what tells you which option needs which: an option marked `x-dataType` in a block's `ConfigSchema` takes a `DataTypeValue`, and nothing else. See [Catalog](./3.catalog.md).
@@ -103,15 +105,11 @@ await ConfigureBlock("/revenue#total", {
 
 Two constraints come with it:
 
-- The referenced symbol must already be importable in the target file. Unlike the other two sentinels, `$expr` adds no import.
+- The referenced symbol must already be in scope in the target file. `$expr` adds no import.
 - `$expr` is refused inside a query's parameters — a query's values are data, and a raw expression would put uncheckable code inside a model body. See [Queries](./6.queries.md).
 
 Consumers that run the builder in a restricted mode may refuse `$expr` outright, since arbitrary code defeats the structured guarantees the rest of the surface provides. `RefValue` is allowed in that mode precisely because it is validated; prefer it whenever the value you need is a generated class.
 
-## Next Steps
-
-- [Results and Errors](./8.results-and-errors.md) - Branch on an operation's result and read its diagnostics
-
 ## Nest a Block in a Config Value
 
 A few options hold a component rather than data — a `ChartCard`'s `chart`, marked `x-component` in the catalog. `BlockValue` is how you write one: the builder emits the nested factory call and adds its import.
@@ -128,3 +126,7 @@ const chart: BlockValue = {
 `type` is a catalog key, like `AddBlockInput.type`; an unknown one is rejected with `invalid_config`. Read-back is symmetrical: a nested factory call whose callee is a known block type comes back as a `$block` sentinel rather than as `$expr`, so the value stays editable.
 
 Most nesting does *not* go through config — it goes through `.child`, which you express with `AddBlockInput.parent` or with `BlockDraft.children`. Reach for `$block` only where the catalog marks an option `x-component`.
+
+## Next Steps
+
+- [Results and Errors](./8.results-and-errors.md) - Branch on an operation's result and read its diagnostics

package/docs/9.drafts-and-preview.md

@@ -1,18 +1,29 @@
 # Drafts and Preview
 
-## Overview
+Use `PreviewLayout` to inspect a page draft without writing files, then `SetPageBlocks` to save its complete block tree in one transaction. A successful preview does not mean the draft compiles: the write performs that check.
 
-The per-block operations — `AddBlock`, `ConfigureBlock`, `MoveBlock`, `RemoveBlock` — each rewrite the page file, typecheck the project and write to disk. That is the right shape for an agent applying one edit at a time, and the wrong shape for an editor: a visual builder holds a whole page in memory, and replaying twenty edits at save time would mean twenty typechecks and twenty chances to stop half way.
+> **Warning:** `SetPageBlocks` replaces the whole block tree. Blocks you omit are removed. For one small change to an existing page, use `ConfigureBlock` instead.
 
-`SetPageBlocks` is the declarative counterpart. You hand it the page's whole block tree and it writes that tree: one transaction, one typecheck, one `changes` list. `PreviewLayout` is its read-only twin — it serializes a draft through the real `dms-base` factories so you can render it without writing anything.
+## Preview one card
+
+With an existing `/dashboard` page, this read-only example returns a serialized KPI card. An editor can render `preview.data.components.total`; no source file changes.
 
 ```typescript
-import {
-  PreviewLayout,
-  SetPageBlocks,
-} from "@antelopejs/interface-dms-builder";
+import { PreviewLayout } from "@antelopejs/interface-dms-builder";
+
+const preview = await PreviewLayout("/dashboard", {
+  blocks: [{ name: "total", type: "KpiCard", config: { title: "Total revenue" } }],
+});
+if (preview.ok) {
+  console.log(preview.data.components.total);
+  console.log(preview.data.degraded);
+} else {
+  console.error(preview.error);
+}
 ```
 
+The per-block operations each save immediately. A visual editor usually holds edits locally and calls `SetPageBlocks` once, so the block tree and its queries either pass one typecheck together or remain unchanged.
+
 ## Describe a Draft
 
 `PageDraft` is a page as you want it written.
@@ -40,7 +51,11 @@ await SetPageBlocks("/shop/board", {
     {
       name: "revenueChart",
       type: "ChartCard",
-      config: { title: "Revenue", fetchUrl: "/dms/pages/shop/board/stats/revenue" },
+      config: {
+        title: "Revenue",
+        fetchUrl: "/dms/pages/shop/board/stats/revenue",
+        chart: { $block: { type: "ChartArea", config: { xaxisType: "category" } } },
+      },
     },
   ],
   queries: [
@@ -72,7 +87,7 @@ await SetPageBlocks("/shop/board", {
 
 A whole-tree write has to answer for blocks the builder can read but not rewrite: a `CustomComponent`, a block behind a computed expression, anything `GetPageStructure` reported with `editable: false`. `preserve` is that answer — the block is matched by name among its siblings and its source text is written back untouched.
 
-Round-tripping a page therefore means keeping every block you did not edit, marking the opaque ones:
+To change only the page title, preserve every top-level block, including its children. This avoids reconstructing editable blocks from only part of their configuration:
 
 ```typescript
 import {
@@ -82,22 +97,32 @@ import {
 
 const structure = await GetPageStructure("/dashboard");
 if (structure.ok) {
-  const blocks = structure.data.blocks.map((block) =>
-    block.editable
-      ? { name: block.name, type: block.type as string, config: block.config }
-      : { name: block.name, preserve: true },
-  );
-  await SetPageBlocks("/dashboard", { blocks }, {
+  const blocks = structure.data.blocks.map((block) => ({
+    name: block.name,
+    preserve: true,
+  }));
+  const result = await SetPageBlocks("/dashboard", {
+    page: { displayName: "Revenue" },
+    blocks,
+  }, {
     expectedVersion: structure.data.version,
   });
+  if (!result.ok) console.error(result.error);
 }
 ```
 
+When you do edit a block, supply its full draft, including its `children`, `slot`, `meta` and `controller` where applicable. Do not reduce a block tree to names and configuration objects: omitted children are deleted.
+
 A `preserve` block whose name matches nothing on disk is rejected with `invalid_config`.
 
 ## Write a Whole Page
 
 ```typescript
+import { GetPageStructure, SetPageBlocks } from "@antelopejs/interface-dms-builder";
+
+const structure = await GetPageStructure("/dashboard");
+if (!structure.ok) throw new Error(structure.error.code);
+
 const result = await SetPageBlocks(
   "/dashboard",
   {
@@ -124,10 +149,13 @@ const result = await SetPageBlocks(
       },
     ],
   },
-  { expectedVersion: "8826e812c4f58d51" },
+  { expectedVersion: structure.data.version },
 );
+if (!result.ok) throw new Error(result.error.code);
 ```
 
+Read the version immediately before preparing the draft. If the write returns `stale`, read the page again and review the other editor's changes before retrying.
+
 On success the result carries the staged `changes` and the page's new `version`, ready to be passed as the next `expectedVersion`.
 
 Blocks absent from the draft are removed. Static members that are not blocks are left where they are, and named imports nothing references any more are dropped, so a page shrinks cleanly rather than accumulating dead imports.
@@ -179,7 +207,13 @@ const result = await PreviewQuery({
     name: "revenue",
     resource: "order",
     template: "series",
-    params: { op: "sum", field: "amount", groupBy: "createdAt", bucket: "month" },
+    params: {
+      op: "sum", field: "amount", groupBy: "createdAt", bucket: "month",
+      where: [
+        { field: "createdAt", op: "ge", value: { $param: { name: "from" } } },
+        { field: "createdAt", op: "lt", value: { $param: { name: "to" } } },
+      ],
+    },
   },
   args: { from: "2026-01-01T00:00:00.000Z", to: "2026-09-01T00:00:00.000Z" },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms-builder",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "AntelopeJS interface for the DMS builder: create and edit pages, blocks, resources and queries in a DMS project from another module.",
   "keywords": [
     "antelopejs",