@antelopejs/interface-dms-builder 0.3.0 → 0.4.0

package/docs/8.results-and-errors.md

@@ -1,14 +1,18 @@
-# Results and Errors
+---
+title: "Results and errors"
+description: "The OpResult envelope every builder operation returns: the staged file changes, the warnings, the BuilderError codes with their payloads, and the expectedVersion check."
+mode: reference
+---
 
 ## Overview
 
-Every operation that can fail returns an `OpResult`. It is a discriminated union: `ok: true` carries the operation's data and the file changes it staged, `ok: false` carries a single `BuilderError`. Nothing throws for an expected failure — an unknown ref, a duplicate name, a config the engine cannot validate all come back as values.
+Every operation that can fail returns an `OpResult`. It is a discriminated union. `ok: true` carries the operation's data and the file changes it staged, and `ok: false` carries a single `BuilderError`. An expected failure comes back as a value and does not throw. An unknown ref, a duplicate name and a configuration the engine cannot validate are examples. The one known exception is an unknown block type inside a `$block` value passed to `AddBlock` or `ConfigureBlock`, which rejects the call, as [Value encodings](./7.values.md) describes.
 
-Mutations are transactional. The engine applies the edit in memory, typechecks the project, and only writes when the typecheck passes; a failure rolls the transaction back and returns `typecheck_failed`, so a rejected operation leaves no partial edit on disk.
+Mutations of source files are transactional. The engine applies the edit in memory, typechecks the project, and writes only when the typecheck passes. A failure rolls the transaction back and returns `typecheck_failed`, so a rejected operation leaves no partial edit on disk.
 
-## Branch on a Result
+## Branch on a result
 
-```typescript
+```typescript fragment
 import { GetPageStructure } from "@antelopejs/interface-dms-builder";
 
 const result = await GetPageStructure("/dashboard");
@@ -20,28 +24,28 @@ if (!result.ok) {
 const { blocks, version } = result.data;
 ```
 
-`OpResult<T>` is:
+`OpResult<T>` has two variants:
 
 | Variant | Fields |
 | --- | --- |
-| success | `ok: true`, `data: T`, `changes: FileChange[]`, `warnings?: OpWarning[]` |
-| failure | `ok: false`, `error: BuilderError` |
+| Success | `ok: true`, `data: T`, `changes: FileChange[]`, `warnings?: OpWarning[]` |
+| Failure | `ok: false`, `error: BuilderError` |
 
-`OpResult` defaults to `OpResult<void>`, which is what the operations that return nothing but a status use — `ConfigurePage`, `RemoveBlock`, `RemoveField` and the rest.
+`OpResult` defaults to `OpResult<void>`. The operations that return only a status use it, such as `ConfigureCategory`, `RemoveBlock` and `RemoveField`.
 
-Reads that use the envelope — `GetPageStructure`, `GetResourceStructure` — return an empty `changes` array on success. The listing operations (`ListPages`, `ListCategories`, `ListResources`, `ListQueryTemplates`, `GetCatalog`) do not use the envelope at all: they return their value directly, and `RefreshSourceIndex` returns `void`.
+The reads that use the envelope, such as `GetPageStructure` and `GetResourceStructure`, return an empty `changes` array on success. The listing operations (`ListPages`, `ListCategories`, `ListResources`, `ListQueryTemplates`, `ListDataSources` and `GetCatalog`) do not use the envelope. They return their value directly, and `RefreshSourceIndex` returns `void`.
 
-## Read the Staged Changes
+## Read the staged changes
 
-`changes` is what the operation wrote, one entry per file.
+`changes` lists what the operation wrote, one entry per file.
 
 | Field | Type | Description |
 | --- | --- | --- |
 | `path` | `string` | The file's absolute path. |
 | `kind` | `"create" \| "modify" \| "delete"` | What happened to the file. |
-| `diff` | `string` | The change as unified diff hunks (`@@ -a,b +c,d @@`, then lines prefixed with a space, `-` or `+`), with no file headers. Empty for a deletion. |
+| `diff` | `string` | The change as unified diff hunks (`@@ -a,b +c,d @@`, then lines that start with a space, `-` or `+`), with no file headers. Empty for a deleted file or folder. |
 
-A single operation usually touches more than one file — creating a page writes the page file and rewrites the barrel that exports it; creating a resource writes three files and rewrites a barrel.
+One operation often changes more than one file. Creating a page writes the page file and rewrites the barrel that exports it. Creating a resource writes three files and rewrites a barrel.
 
 ```typescript
 import { CreateResource } from "@antelopejs/interface-dms-builder";
@@ -57,16 +61,28 @@ if (result.ok) {
 }
 ```
 
-## Handle Warnings
+## Handle warnings
 
-`warnings` is present only when an otherwise successful operation has something non-fatal to report. It is optional: check for it rather than assuming an array.
+`warnings` is present only when a successful operation has something non-fatal to report. The field is optional, so it can be absent instead of an empty array.
 
 | Code | Raised when |
 | --- | --- |
-| `index_clamped` | An `AddBlock` or `MoveBlock` index fell outside the sibling range and was clamped into it. |
-| `datatype_fallback` | A field's DataType is not one the builder maps, so it is handled as a string. |
-| `data_not_dropped` | `DeleteResource` removed the source but could not clear the resource's table data. |
-| `display_not_proposed` | `MapResources` mapped a relation whose columns left `display` out, and neither a profile nor an analysis was there to propose a badge from, so its text columns were written plain. |
+| `index_clamped` | An `AddBlock` or `MoveBlock` index fell outside the sibling range, and the engine moved it to the nearest end. |
+| `datatype_fallback` | A field's DataType is not one the builder maps, so a resource stores it as a string, or a query filter compares it as a string. |
+| `data_not_dropped` | `DeleteResource` removed the source files but could not delete the rows of the resource's table. |
+| `data_kept` | `DeleteResource` deleted a resource that mirrors an external database. Its rows belong to that database and stay in place. |
+| `route_changed` | `ConfigurePage` moved a page to another category, so its route changed and links to the old route break. |
+| `query_opaque` | `SetPageBlocks` left alone a query on the page that a person took over by hand. |
+| `query_kept` | `SetPageBlocks` kept a query that the draft dropped, because a block still reads it. |
+| `page_not_written` | `MapResources` wrote a mapped relation's tables, but not its table view page. |
+| `relation_missing` | `GetMapping` found a relation that the module maps but the database no longer has, or that the role can no longer see. |
+| `module_not_loaded` | `MapResources` wrote the mapping, but the module it wrote into did not load again. The module was unloaded and did not start within the wait, or the runtime does not report it active. The message names the module, and the backend log holds the error. |
+| `setting_dropped` | `ConfigureTableView` or `MapResources` dropped a TableView setting that no longer holds, such as a default display the table no longer offers. |
+| `relation_skipped` | `MapResources` left out a relation of the batch because one of its choices was refused, and wrote the others. |
+| `display_dropped` | `MapResources` wrote a column plain because the display sent for it, or the tabs sent from it, do not suit the column. |
+| `field_flag_set` | `MapResources` or `ConfigureTableView` marked a column filterable or sortable, because a view, footer figure, tab or grouping needs it. |
+| `label_changed` | `MapResources` changed a relation's label to one the generated code can read, or dropped it when no column offers it. |
+| `display_not_proposed` | `MapResources` mapped a relation whose columns left `display` out, and no profile or analysis could propose a badge, so its text columns were written plain. |
 
 ```typescript
 import { AddBlock } from "@antelopejs/interface-dms-builder";
@@ -85,20 +101,20 @@ if (result.ok) {
 }
 ```
 
-## Handle Errors
+## Handle errors
 
-`BuilderError` is a union discriminated by `code`. Each variant carries exactly what you need to act on it.
+`BuilderError` is a union discriminated by `code`. Each variant carries the data needed to act on it.
 
 | Code | Payload | Meaning |
 | --- | --- | --- |
 | `not_found` | `ref: string` | The page, category, block, resource, field or query does not exist. |
 | `duplicate_name` | `name: string`, `scope: DuplicateScope` | The name is already taken within that scope. |
 | `invalid_config` | `issues: ValidationIssue[]` | The request's configuration did not validate. |
-| `opaque_target` | `path: BlockPath` | The target exists but the builder cannot rewrite it. |
-| `unsupported` | `detail: string` | The operation is valid but out of scope for the engine, and `detail` says why. |
+| `opaque_target` | `path: BlockPath` | The target exists, but the builder cannot rewrite it. For a field or a query, `path` holds the `FieldPath` or the `QueryRef`. |
+| `unsupported` | `detail: string` | The engine does not handle the request, and `detail` says why. |
 | `referential_integrity` | `blockedBy: string[]` | Something still depends on what you asked to delete. |
 | `stale` | `ref: string`, `currentVersion: string` | The file changed since the version you passed as `expectedVersion`. |
-| `typecheck_failed` | `diagnostics: TypecheckError[]` | The edit would not compile, and was rolled back. |
+| `typecheck_failed` | `diagnostics: TypecheckError[]` | The edit would not compile, and the engine rolled it back. |
 
 ```typescript
 import { AddBlock } from "@antelopejs/interface-dms-builder";
@@ -130,9 +146,9 @@ if (!result.ok) {
 }
 ```
 
-### Duplicate Scopes
+### Duplicate scopes
 
-`DuplicateScope` names the namespace the collision happened in, which tells you what to rename:
+`DuplicateScope` names the namespace the collision happened in, which tells you what to rename.
 
 | Scope | The name collided with |
 | --- | --- |
@@ -140,20 +156,21 @@ if (!result.ok) {
 | `siblings` | Another child of the same container block. |
 | `category` | Another category. |
 | `resource` | Another resource, or another field on the same resource. |
-| `query` | A member of the page controller, a route path already served by the page, or a member of the resource's model. |
+| `query` | A member of the page controller, a route path the page already serves, or a member of the resource's model. For a route path, `name` holds the endpoint. |
+| `module` | A module. The type declares this scope, and no operation returns it now. |
 
-### Validation Issues
+### Validation issues
 
-`ValidationIssue` addresses a failure by JSON pointer into the request:
+`ValidationIssue` addresses a failure by a JSON pointer into the request.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `pointer` | `string` | A JSON pointer into the offending input, e.g. `/where/0/op`. Empty when the failure is not tied to one key. |
-| `message` | `string` | What is wrong, and often what to call to find the valid values. |
+| `pointer` | `string` | A JSON pointer into the input that failed, such as `/where/0/op`. Empty when the failure is not tied to one key. |
+| `message` | `string` | What is wrong. It often names the operation that lists the valid values. |
 
-### Typecheck Errors
+### Typecheck errors
 
-`TypecheckError` is one TypeScript diagnostic from the in-memory typecheck gate:
+`TypecheckError` is one TypeScript diagnostic from the in-memory typecheck.
 
 | Field | Type | Description |
 | --- | --- | --- |
@@ -161,21 +178,21 @@ if (!result.ok) {
 | `line` | `number` | The line number. |
 | `message` | `string` | The diagnostic message. |
 
-Diagnostics are collected across the project, not just the file the operation edited, so a change that breaks a consumer elsewhere is caught before anything is written.
+The engine collects diagnostics across the whole project, outside `node_modules`, and not only in the file the operation edited. A change that breaks code elsewhere fails before anything is written.
 
-## Make a Write Conditional
+## Make a write conditional
 
-`MutationOpts` is the trailing options argument of version-checked mutations, not of every mutation.
+`MutationOpts` is the trailing options argument of the mutations that check a version. Not every mutation takes it.
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `expectedVersion` | `string` | The version the consumer last read. A mismatch fails with `stale`. |
+| `expectedVersion` | `string` | The version the caller last read. A mismatch fails with `stale`. |
 
-The operations that edit something that already exists take it: `ConfigurePage`, `DeletePage`, `AddBlock`, `ConfigureBlock`, `MoveBlock`, `RemoveBlock`, `DeleteResource`, `AddField`, `ConfigureField`, `RemoveField`, `AddQuery`, `ConfigureQuery` and `RemoveQuery`. The three creations — `CreatePage`, `CreateCategory` and `CreateResource` — take no options argument, and neither do `ConfigureCategory` and `DeleteCategory`.
+The operations that edit something that already exists take it: `ConfigurePage`, `DeletePage`, `AddBlock`, `ConfigureBlock`, `MoveBlock`, `RemoveBlock`, `SetPageBlocks`, `ConfigureResource`, `DeleteResource`, `AddField`, `ConfigureField`, `RemoveField`, `AddQuery`, `ConfigureQuery`, `RemoveQuery`, `ConfigureTableView` and `ComposePage`. The three creations, `CreatePage`, `CreateCategory` and `CreateResource`, take no options argument. Neither do `ConfigureCategory` and `DeleteCategory`.
 
-The version comes from the structure you read: `PageStructure.version` for a page operation, `ResourceStructure.version` for a resource one. Both are content hashes — of the page file, and of a resource's two generated files.
+The version comes from the structure you read. A page operation takes `PageStructure.version`, and a resource operation takes `ResourceStructure.version`. Both are content hashes, of the page file and of the resource's two generated files.
 
-```typescript
+```typescript fragment
 import {
   ConfigureBlock,
   GetPageStructure,
@@ -192,11 +209,11 @@ const write = await ConfigureBlock(
   { expectedVersion: read.data.version },
 );
 if (!write.ok && write.error.code === "stale") {
-  // `write.error.currentVersion` is what the file hashes to now:
-  // re-read the structure, re-decide, and retry.
+  // `write.error.currentVersion` is the file's hash now.
+  // Read the structure again, decide again, and retry.
 }
 ```
 
-Omitting `expectedVersion` writes unconditionally. Pass it whenever a human or another process may have touched the file between your read and your write.
+Without `expectedVersion`, the write is unconditional. Pass it when a person or another process can change the file between your read and your write.
 
-Two operations extend `MutationOpts` with options of their own: `ConfigureBlockOpts` adds `replace` and `meta`, described in [Page Operations](./4.page-operations.md), and `DeleteResourceOpts` adds `keepData`, described in [Resources](./5.resources.md).
+Two operations extend `MutationOpts` with options of their own. `ConfigureBlockOpts` adds `replace` and `meta`, described in [Page operations](./4.page-operations.md). `DeleteResourceOpts` adds `keepData`, described in [Resources](./5.resources.md).

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

@@ -1,12 +1,16 @@
-# Drafts and Preview
+---
+title: "Drafts and preview"
+description: "SetPageBlocks writes a page's whole block tree and its queries in one transaction, PreviewLayout serializes a draft without writing it, and PreviewQuery runs an unsaved query against the real table."
+mode: reference
+---
 
-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.
+`PreviewLayout` serializes a page draft without writing files. `SetPageBlocks` saves the draft's complete block tree in one transaction. A successful preview does not mean that the draft compiles, because only the write runs the typecheck.
 
 > **Warning:** `SetPageBlocks` replaces the whole block tree. Blocks you omit are removed. For one small change to an existing page, use `ConfigureBlock` instead.
 
 ## 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.
+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 } from "@antelopejs/interface-dms-builder";
@@ -22,26 +26,26 @@ if (preview.ok) {
 }
 ```
 
-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.
+Each per-block operation saves at once. A visual editor usually holds its edits locally and calls `SetPageBlocks` once. The block tree and its queries then pass one typecheck together, or the page stays unchanged.
 
-## Describe a Draft
+## Describe a draft
 
 `PageDraft` is a page as you want it written.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `page` | `Partial<EditablePageMeta>` | Metadata to patch alongside the blocks. Omit to leave it alone. |
-| `blocks` | `BlockDraft[]` | The top-level blocks, in the order they should appear. |
-| `queries` | `AddQueryInput[]` | The queries the page should serve, written with the blocks. Omit to leave the page's queries alone. |
+| `page` | `Partial<EditablePageMeta>` | Metadata to patch alongside the blocks. Omit it to leave the metadata alone. |
+| `blocks` | `BlockDraft[]` | The top-level blocks, in page order. |
+| `queries` | `AddQueryInput[]` | The queries the page serves, written with the blocks. Omit it to leave the page's queries alone. |
 
-A block and the data it reads are one edit, so they are one write: the blocks, the model methods and the routes land in a single transaction with a single typecheck, or none of them land.
+A block and the data it reads are one edit, so they are one write. The blocks, the model methods and the routes land in a single transaction with a single typecheck, or none of them land.
 
-Omitting `queries` is not the same as passing an empty array. Omitted leaves whatever the page already serves untouched — which is what a caller written before queries joined the draft keeps doing. An empty array says the page should serve none, and removes the generated ones.
+An omitted `queries` and an empty array differ. An omitted `queries` leaves the queries the page already serves untouched. An empty array says that the page serves none, and removes the generated ones. Two queries in a draft with the same name fail with `invalid_config`.
 
-Two things a draft never destroys silently:
+A draft never removes or rewrites these two kinds of query:
 
-- **A query edited past the grammar** is left exactly as it is, whether the draft still lists it or not. The engine reports `query_opaque` and moves on, because a chain it cannot read is one a human owns.
-- **A query the draft forgot** is kept when a block on the page still reads its URL, reported as `query_kept`. A draft that dropped a source a block depends on is a draft that would break that block, and keeping it is the recoverable side of the mistake.
+- **A query edited past the grammar.** The write leaves it exactly as it is, whether the draft still lists it or not, and reports a `query_opaque` warning. The builder cannot read the chain, so a person owns it.
+- **A query the draft left out while a block still reads it.** The write keeps the query when a block on the page still names its URL, and reports a `query_kept` warning. Removing the query would break that block.
 
 ```typescript
 import { SetPageBlocks } from "@antelopejs/interface-dms-builder";
@@ -74,20 +78,21 @@ await SetPageBlocks("/shop/board", {
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `name` | `string` | Static key (top-level) or `.child()` id (nested). Must be a valid identifier. |
-| `type` | `string` | A `BlockTypeDescriptor.type` from the catalog. Ignored when `preserve` is set. |
-| `config` | `Record<string, unknown>` | The factory's options. |
+| `name` | `string` | The static key (top level) or the `.child()` id (nested). Must be a valid identifier. |
+| `type` | `string` | A `BlockTypeDescriptor.type` from the catalog. Required unless `preserve` is set. On a preserved block, a `type` that differs from the one on disk is refused. |
+| `config` | `ConfigObject` | The factory's options. Leave out locked options, because the server keeps their source. A preserved block takes no `config`. |
+| `lockedOptions` | `Record<string, string>` | Read-only UI hints copied from `GetPageStructure`. The server derives option locks from its own source. |
 | `slot` | `string` | The slot the block sits in. |
-| `meta` | `Record<string, unknown>` | Child metadata emitted with `slot` — `{ colSpan: 2 }` on a grid child. |
+| `meta` | `ConfigObject` | Child metadata emitted with `slot`, such as `{ colSpan: 2 }` on a grid child. |
 | `controller` | `ResourceRef` | Required for a controller-leading type such as `TableView`. |
 | `children` | `BlockDraft[]` | Nested blocks, in `.child()` order. |
 | `preserve` | `boolean` | Write the block back exactly as it stands on disk. |
 
-## Carry an Opaque Block Through a Write
+## Carry an opaque block through a write
 
-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.
+A whole-tree write has to keep the blocks that the builder can read but not rewrite. These include a `CustomComponent`, a block behind a computed expression, and any block that `GetPageStructure` reported with `editable: false`. Set `preserve` on such a block. The write matches the block by name among its siblings and writes its source text back untouched. A locked block without `preserve` is refused.
 
-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:
+To change only the page title, preserve every top-level block. A preserved block keeps its children, so you do not rebuild editable blocks from part of their configuration:
 
 ```typescript
 import {
@@ -111,11 +116,13 @@ if (structure.ok) {
 }
 ```
 
-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.
+When you edit a block, supply its full draft, including its `children`, `slot`, `meta` and `controller` where they apply. Do not reduce a block tree to names and configuration objects, because the write deletes omitted children.
+
+The children of a preserved block are read-only. If a preserved block lists `children`, each child must also be preserved, with the names, slots and metadata it has on disk. A block with locked options keeps its type, its controller and the placement of its children, and the draft cannot copy it to another path.
 
 A `preserve` block whose name matches nothing on disk is rejected with `invalid_config`.
 
-## Write a Whole Page
+## Write a whole page
 
 ```typescript
 import { GetPageStructure, SetPageBlocks } from "@antelopejs/interface-dms-builder";
@@ -154,32 +161,35 @@ const result = await SetPageBlocks(
 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.
+Read the version immediately before you prepare the draft. If the write returns `stale`, read the page again and review the other editor's changes before you retry.
 
-On success the result carries the staged `changes` and the page's new `version`, ready to be passed as the next `expectedVersion`.
+On success, the result carries the staged `changes` and the page's new `version`. Pass that `version` 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.
+The write removes the blocks that the draft leaves out. It leaves static members that are not blocks where they are. It drops a named import that the file used before the write and no longer uses. An import that was already unused before the write stays.
 
-`$expr` is refused anywhere in a draft: a whole-tree write stays structured, and arbitrary code would defeat the guarantee. `$dataType`, `$ref` and `$block` are all accepted — see [Value Encodings](./7.values.md).
+`$expr` is refused anywhere in a draft, including `page` and a block's `meta`. A whole-tree write stays structured, and arbitrary code would break that guarantee. `$dataType`, `$ref` and `$block` are accepted. See [Value encodings](./7.values.md).
 
-## Read the Failures
+## Read the failures
 
-`SetPageBlocks` validates the whole draft before touching anything, so one call reports every problem at once, each addressed by a JSON pointer into the draft:
+`SetPageBlocks` validates the whole draft before it touches anything. One call reports every problem at once as an `invalid_config` issue, each addressed by a JSON pointer into the draft:
 
 | Pointer | Cause |
 | --- | --- |
 | `/blocks/1/name` | Not a valid identifier, or a duplicate among its siblings. |
-| `/blocks/2/type` | Unknown block type, or a child a container does not accept. |
-| `/blocks/0/controller` | A controller-leading type without one, or a controller on a type that takes none. |
+| `/blocks/2/type` | An unknown block type. |
+| `/blocks/2/children` | Children on a block type that takes none. |
+| `/blocks/2/children/0/type` | A child type that the container does not accept. |
+| `/blocks/0/controller` | A controller-leading type without a controller, or a controller on a type that takes none. |
 | `/blocks/3/config/title` | `$expr` inside a config value. |
+| `/blocks/4` | A `preserve` block with no match on disk, a locked block without `preserve`, or a change to a preserved block. |
 
-Beyond `invalid_config`, the write fails the same way the per-block operations do: `stale` when `expectedVersion` no longer matches, `typecheck_failed` when the emitted source does not compile — and then nothing is written. See [Results and Errors](./8.results-and-errors.md).
+Beyond `invalid_config`, the write fails the same way as the per-block operations. It returns `stale` when `expectedVersion` no longer matches, and `typecheck_failed` when the emitted source does not compile. In both cases nothing is written. See [Results and errors](./8.results-and-errors.md).
 
-## Preview a Draft
+## Preview a draft
 
-`PreviewLayout` serializes a draft the way the runtime would, by calling the same `dms-base` factories the emitted source would call. Nothing is typechecked and nothing reaches disk, so it is cheap enough to run on every edit.
+`PreviewLayout` serializes a draft the way the runtime would, through the block factories of `@antelopejs/interface-dms/base` that the emitted source calls. It runs no typecheck and writes nothing to disk, so an editor can run it on every edit.
 
-```typescript
+```typescript fragment
 const preview = await PreviewLayout("/dashboard", draft);
 if (preview.ok) {
   const grid = preview.data.components.kpis; // ComponentPreview
@@ -190,14 +200,22 @@ if (preview.ok) {
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `components` | `Record<string, ComponentPreview>` | The serialized tree, keyed by top-level block name — the shape the DMS frontend renders. |
-| `degraded` | `BlockPath[]` | Blocks the preview could not build faithfully. |
+| `components` | `Record<string, ComponentPreview>` | The serialized tree, keyed by top-level block name. The DMS frontend renders this shape. |
+| `degraded` | `BlockPath[]` | Blocks that the preview could not build faithfully. |
+
+A degraded block appears in `components` as a placeholder that names the reason. A block lands in `degraded` in these cases:
 
-A block lands in `degraded` when the preview cannot reach what the running page holds: a controller-leading block such as `TableView` (the DataAPI class lives in the app, not in the builder), a `$ref`, an `$expr`, a `preserve` block (which the draft does not describe), or a factory that threw. Render the last known-good layout for those rather than trusting the preview.
+- It is a `preserve` block, or a block with locked options, which the draft does not describe.
+- Its type is unknown.
+- It is a controller-leading block, such as `TableView`, with no `controller`, or with a resource whose DataAPI class the running app has not loaded. A table created a moment ago is not loaded until the app reloads.
+- Its config holds an `$expr`, or a `$ref` to a resource whose DataAPI class the running app has not loaded.
+- Its factory threw.
 
-## Preview a Query
+For a degraded block, render the last known-good layout rather than trust the preview.
 
-`PreviewLayout` says what the page will look like; `PreviewQuery` says what its blocks will be showing. It runs a query the caller has not saved and answers what its route would, so a source can be configured against real data before anything is written.
+## Preview a query
+
+`PreviewLayout` shows what the page looks like. `PreviewQuery` shows the data its blocks display. It runs a query that is not saved and answers what its route would, so an editor can configure a source against real data before anything is written.
 
 ```typescript
 import { PreviewQuery } from "@antelopejs/interface-dms-builder";
@@ -225,17 +243,35 @@ if (result.ok) {
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `query` | `AddQueryInput` | What to run. Validated the same way `AddQuery` validates it. |
-| `args` | `Record<string, unknown>` | Values the route would receive, by the name it exposes them under. A bound value with nothing supplied is refused rather than compared against nothing. |
-| `tenant` | `string` | Whose rows to read, for a resource in a per-tenant schema. |
+| `query` | `AddQueryInput` | The query to run. The template validates its parameters as it does for `AddQuery`. |
+| `args` | `ConfigObject` | The values the route would receive, under the names the route exposes. |
+| `tenant` | `string` | Whose rows to read, for a resource in a per-tenant schema. A resource in any other schema ignores it. |
+
+`QueryPreview` holds the route's own response body and how it is arranged:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `output` | `QueryOutputKind` | `"scalar"` or `"series"`, as `GetPageStructure` reports the saved query. |
+| `response` | `QueryArrangement` | Set only when a DMS helper arranged the body, the same condition under which read-back reports it. |
+| `body` | `QueryResponseBody` | What the route would return. |
+| `truncated` | `boolean` | `true` when the preview stopped at 500 points. |
+
+The body depends on the calculation and on `response`:
+
+- A scalar calculation answers `{ value }`, whatever `response` asks for.
+- A grouped calculation with no `response`, or with `response: "series"`, answers `{ series }` and leaves `response` unset.
+- `response: "card"`, `"value"` and `"items"` answer the body that `chartCardData`, `kpiCardData` and `topListData` from `@antelopejs/interface-dms/base/query-response` build. The generated route calls the same helper, so `"card"` answers a `ChartCardData`, headline figure included, and a block can take it directly.
 
-What comes back is the route's own response body, not a rendering of it: `body` is built by the same helper the generated route would call, and `output` and `response` report it the way `GetPageStructure` reports the saved query. Ask for `response: "card"` and the preview answers a `ChartCardData` — the headline figure included — so a block can be handed it directly. `response` is set only when a helper arranged the body, which is the same condition read-back reports it under; a plain `{ value }` or `{ series }` leaves it absent. An arrangement the installed DMS does not publish is refused as `unsupported` rather than answered as bare points, because saving that query would fail its typecheck on the very same helper.
+A query is filters, a grouping and a measure. It has no way to express a write, so a preview only reads. It stops at 500 points and sets `truncated`, so a chart that lost its tail says so.
 
-Read-only by construction: a query is filters, a grouping and a measure, and there is no way to spell a write in one. It stops at 500 points and sets `truncated`, because a chart that quietly lost its tail is worse than one that reports it. A database that refuses comes back as a failed `OpResult`, not as a rejection.
+`PreviewQuery` answers every failure as a failed `OpResult`, never as a rejected promise:
 
-## Next Steps
+- `not_found` for an unknown resource.
+- `invalid_config` for an unknown template or invalid parameters.
+- `unsupported` when the resource's schema is not registered, when a bound value has no argument in `args`, or when the database refuses the query.
 
-- [A Chart Without Code](./10.a-chart-without-code.md) - The journey these calls add up to
+## Next steps
 
-- [Results and Errors](./8.results-and-errors.md) - Branch on `OpResult` and handle `stale`
-- [Catalog](./3.catalog.md) - The block types, their schemas and their defaults
+- [A chart without code](./10.a-chart-without-code.md) follows these calls from the choice of a measure to the reopened page.
+- [Results and errors](./8.results-and-errors.md) shows how to branch on `OpResult` and handle `stale`.
+- [Catalog](./3.catalog.md) lists the block types, their schemas and their defaults.

package/docs/tsconfig.json

@@ -2,6 +2,10 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "rootDir": "..",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
     "composite": false,
     "incremental": false,
     "noEmit": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms-builder",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AntelopeJS interface for the DMS builder: create and edit pages, blocks, resources and queries in a DMS project from another module.",
   "keywords": [
     "antelopejs",
@@ -50,7 +50,7 @@
     "prepack": "pnpm run build"
   },
   "devDependencies": {
-    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/interface-core": ">=0.4.0 <1.0.0",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",