@byline/core 4.2.0 → 4.4.0

package/dist/@types/admin-types.d.ts

@@ -270,7 +270,12 @@ export interface CollectionAdminConfig<T = any> {
      */
     layout?: LayoutDefinition;
     /**
-     * Per-field rendering overrides, keyed by field name.
+     * Per-field rendering overrides, keyed by schema path: a top-level field
+     * name (`title`) or a dotted, index-free path through `group` / `array`
+     * structure fields (`files.filesGroup.publicationFile`). Paths address
+     * field *declarations*, never item instances (no `[0]` indices), and never
+     * traverse a `blocks` field — blocks take their overrides from the
+     * blockType-keyed `ClientConfig.blockAdmin` registry instead.
      * Placement is no longer expressed here — see the layout primitives above.
      */
     fields?: Record<string, FieldAdminConfig>;
@@ -405,25 +410,31 @@ export declare function defineAdmin<T = any>(schema: CollectionDefinition, confi
  * collection genuinely needs different presentation for "the same" block,
  * define a second block with a distinct `blockType`.
  *
- * v1 scope: `fields` keys address the block's **top-level** field names only —
- * the same limitation `CollectionAdminConfig.fields` has for collections.
- * Fields nested inside a group/array within the block inherit site-wide
- * defaults.
+ * `fields` keys are **schema paths** relative to the block root: a top-level
+ * field name (`quoteText`) or a dotted path through `group` / `array`
+ * structure fields (`faq.answer`). Schema paths are index-free — they address
+ * field *declarations*, not item instances (`faq.answer`, never
+ * `faq[0].answer`) — the same notation `upload` validation and the upload
+ * executor use. Paths never traverse a nested `blocks` field: an inner block
+ * resolves its own `blockAdmin` registry entry wherever it renders.
  */
 export interface BlockAdminConfig {
     /** Must match the `blockType` of the corresponding `defineBlock()` definition. */
     blockType: string;
     /**
      * Per-field rendering overrides (`components` slots, richtext `editor`),
-     * keyed by the block's top-level field names. Same shape and semantics as
+     * keyed by index-free schema paths relative to the block root (`alt`,
+     * `faq.answer`). Same shape and semantics as
      * `CollectionAdminConfig.fields`.
      */
     fields?: Record<string, FieldAdminConfig>;
 }
 /**
  * Type-safe factory for creating a `BlockAdminConfig` linked to a block
- * schema. Sets `blockType` from the block's `blockType` and constrains the
- * `fields` keys to the block's own top-level field names.
+ * schema. Sets `blockType` from the block's `blockType`. `fields` keys
+ * autocomplete the block's top-level field names; nested declarations are
+ * addressed with dotted, index-free schema paths (`faq.answer`), validated
+ * against the block's field tree at boot (`validateBlockAdminConfigs`).
  *
  * Lives on the admin side of the schema/admin split: block schema files stay
  * React-free and tsx-loadable, while this config may carry React component
@@ -444,5 +455,11 @@ export interface BlockAdminConfig {
  * ```
  */
 export declare function defineBlockAdmin<B extends Block>(block: B, config: {
-    fields?: Partial<Record<Extract<keyof BlockFieldData<B>, string>, FieldAdminConfig>>;
+    /**
+     * Keyed by schema path relative to the block root. Top-level field names
+     * autocomplete; nested fields are addressed with dotted, index-free
+     * paths (`faq.answer`) — accepted as plain strings here and resolved
+     * against the block's field tree at boot.
+     */
+    fields?: Partial<Record<Extract<keyof BlockFieldData<B>, string> | (string & {}), FieldAdminConfig>>;
 }): BlockAdminConfig;

package/dist/@types/admin-types.js

@@ -17,8 +17,10 @@ export function defineAdmin(schema, config) {
 }
 /**
  * Type-safe factory for creating a `BlockAdminConfig` linked to a block
- * schema. Sets `blockType` from the block's `blockType` and constrains the
- * `fields` keys to the block's own top-level field names.
+ * schema. Sets `blockType` from the block's `blockType`. `fields` keys
+ * autocomplete the block's top-level field names; nested declarations are
+ * addressed with dotted, index-free schema paths (`faq.answer`), validated
+ * against the block's field tree at boot (`validateBlockAdminConfigs`).
  *
  * Lives on the admin side of the schema/admin split: block schema files stay
  * React-free and tsx-loadable, while this config may carry React component

package/dist/@types/collection-types.d.ts

@@ -1152,9 +1152,15 @@ export interface CollectionDefinition {
      *
      * Receives the same minimal document shape as
      * `CollectionAdminConfig.preview.url` (`PreviewDocument`-style envelope:
-     * top-level columns plus `fields`) so the two hooks can share an
-     * implementation today and `preview.url` can default to
-     * `buildDocumentPath` in a later pass.
+     * top-level columns plus `fields`), so the two hooks can share an
+     * implementation. `preview.url` already defaults to this hook when
+     * omitted — see `resolvePreviewUrl` in `@byline/host-tanstack-start` —
+     * so the admin Preview button and the public path agree by construction.
+     *
+     * Note the `null` return is read differently by the two surfaces:
+     * `resolvePreviewUrl` hides the Preview affordance, while the richtext
+     * walker treats it as "no path could be built" and falls through to the
+     * generic `/${collectionPath}/${path}` compose.
      */
     buildDocumentPath?: (doc: {
         id: string;

package/dist/config/attach-hooks.js

@@ -1,3 +1,4 @@
+import { formatDeclarationPath, walkFieldDeclarations } from '../paths/index.js';
 const registryCollectionHooks = new WeakMap();
 const registryUploadHooks = new WeakMap();
 /**
@@ -97,31 +98,25 @@ function assertOwnershipIntact(label, current, owned) {
 }
 function indexUploadFields(collection, uploadFields) {
     const leafPaths = new Map();
-    const walk = (fields, prefix) => {
-        for (const field of fields) {
-            assertDotFreeSegment(field.name, `field name "${field.name}" in collection "${collection.path}"`);
-            const path = [...prefix, field.name];
-            if ((field.type === 'file' || field.type === 'image') && field.upload !== undefined) {
-                const canonical = [collection.path, ...path].join('.');
-                const previous = leafPaths.get(field.name);
-                if (previous !== undefined) {
-                    throw new Error(`Collection "${collection.path}" has duplicate upload-capable leaf name "${field.name}" at "${previous}" and "${canonical}". Upload leaf names must be unique within a collection.`);
-                }
-                leafPaths.set(field.name, canonical);
-                uploadFields.set(canonical, field);
-            }
-            if (field.type === 'group' || field.type === 'array') {
-                walk(field.fields, path);
-            }
-            else if (field.type === 'blocks') {
-                for (const block of field.blocks) {
-                    assertDotFreeSegment(block.blockType, `block type "${block.blockType}" in collection "${collection.path}"`);
-                    walk(block.fields, [...path, block.blockType]);
-                }
-            }
+    walkFieldDeclarations(collection.fields, (field, segments) => {
+        assertDotFreeSegment(field.name, `field name "${field.name}" in collection "${collection.path}"`);
+        if ((field.type !== 'file' && field.type !== 'image') || field.upload === undefined)
+            return;
+        const canonical = `${collection.path}.${formatDeclarationPath(segments)}`;
+        const previous = leafPaths.get(field.name);
+        if (previous !== undefined) {
+            throw new Error(`Collection "${collection.path}" has duplicate upload-capable leaf name "${field.name}" at "${previous}" and "${canonical}". Upload leaf names must be unique within a collection.`);
         }
-    };
-    walk(collection.fields, []);
+        leafPaths.set(field.name, canonical);
+        uploadFields.set(canonical, field);
+    }, {
+        // Every block is checked, including one declaring no fields — such a
+        // block never reaches the field visitor, so inferring block types from
+        // field segments alone would silently stop validating them.
+        onBlock: (block) => {
+            assertDotFreeSegment(block.blockType, `block type "${block.blockType}" in collection "${collection.path}"`);
+        },
+    });
 }
 function assertDotFreeSegment(segment, label) {
     if (segment.length === 0 || segment.includes('.')) {

package/dist/config/routes.test.node.js

@@ -24,13 +24,7 @@ describe('resolveRoutes', () => {
             signIn: '/sign-in',
         });
     });
-    it.each([
-        '/../cms',
-        '/cms?next=x',
-        '/cms#section',
-        '/cms\\users',
-        '/%63ms',
-    ])('rejects a non-segment admin route of %j', (admin) => {
+    it.each(['/../cms', '/cms?next=x', '/cms#section', '/cms\\users', '/%63ms'])('rejects a non-segment admin route of %j', (admin) => {
         expect(() => resolveRoutes({ admin })).toThrow(/routes\.admin/);
     });
     it('normalizes and validates the API route too', () => {

package/dist/config/validate-admin-configs.d.ts

@@ -22,8 +22,9 @@ import type { BlockAdminConfig, CollectionAdminConfig, CollectionDefinition } fr
  *     are unique within an admin config and don't shadow schema field names.
  *  5. Nesting — `tabSets` only appear in `layout.main`; rows contain only
  *     schema field names; groups exclude tabSets and nested groups.
- *  6. `fields` map sanity — every key in `admin.fields` matches a top-level
- *     schema field name.
+ *  6. `fields` map sanity — every key in `admin.fields` is a dotted,
+ *     index-free schema path resolving to a field declaration (top-level
+ *     name or a path through group/array fields; never through blocks).
  *  7. `defaultSort` sanity — `field` resolves to a top-level schema field
  *     or a document-level column (`createdAt` / `updatedAt` / `path`), the
  *     direction (when given) is `asc` | `desc`, and the option is rejected
@@ -43,9 +44,11 @@ export declare function validateAdminConfigs(admins: readonly CollectionAdminCon
  *     `type: 'blocks'` field across the registered collections (blocks have
  *     no global registry; the collections walk is the source of truth).
  *  2. Uniqueness — no two entries share a `blockType`.
- *  3. `fields` map sanity — every key matches a top-level field name of the
- *     block (when the same `blockType` appears in several collections, the
- *     union of their top-level field names is accepted).
+ *  3. `fields` map sanity — every key is a dotted, index-free schema path
+ *     resolving to a field declaration of the block (top-level name or a
+ *     path through group/array fields; never through a nested blocks field).
+ *     When the same `blockType` appears in several collections, a key is
+ *     accepted if it resolves in any declaration site (union semantics).
  *
  * Throws a plain `Error` for the same reason `validateAdminConfigs` does —
  * this runs at startup, before the logger is necessarily wired up.

package/dist/config/validate-admin-configs.js

@@ -5,6 +5,39 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { resolveDeclarationPath, walkFieldDeclarations, } from '../paths/index.js';
+/**
+ * Resolve a `fields{}` override key against a field set.
+ *
+ * Admin override keys are declaration paths with one deliberate narrowing:
+ * they may not traverse a `blocks` field at all, even correctly qualified by
+ * block type. Fields inside a block take their overrides from the
+ * blockType-keyed `blockAdmin` registry, so that one registration applies
+ * wherever the block renders.
+ */
+function resolveSchemaPath(fields, path) {
+    return resolveDeclarationPath(fields, path, { blocks: 'forbidden' }).status;
+}
+/**
+ * Shared validation for a `fields{}` override map (collection- or block-level):
+ * keys must be dotted, index-free schema paths that resolve to a field
+ * declaration without traversing a `blocks` field. `subject` names the config
+ * in error messages (`Collection "docs"` / `Block "faqBlock"`).
+ */
+function validateFieldAdminKeys(keys, resolve, fail) {
+    for (const key of keys) {
+        if (key.includes('[')) {
+            fail(`\`fields["${key}"]\` contains an item index. Field override keys are index-free schema paths addressing field declarations (e.g. "faq.answer"), not instance paths (e.g. "faq[0].answer").`);
+        }
+        const resolution = resolve(key);
+        if (resolution === 'blocks') {
+            fail(`\`fields["${key}"]\` traverses a \`type: 'blocks'\` field. Blocks resolve their own overrides from the blockType-keyed \`blockAdmin\` registry — register a block admin config for the inner block instead.`);
+        }
+        if (resolution === 'unresolved') {
+            fail(`\`fields["${key}"]\` does not resolve to a field declaration. Keys are dotted, index-free schema paths whose intermediate segments are \`group\` / \`array\` fields (e.g. "faq.answer").`);
+        }
+    }
+}
 /**
  * Validate every admin config in a configuration.
  *
@@ -21,8 +54,9 @@
  *     are unique within an admin config and don't shadow schema field names.
  *  5. Nesting — `tabSets` only appear in `layout.main`; rows contain only
  *     schema field names; groups exclude tabSets and nested groups.
- *  6. `fields` map sanity — every key in `admin.fields` matches a top-level
- *     schema field name.
+ *  6. `fields` map sanity — every key in `admin.fields` is a dotted,
+ *     index-free schema path resolving to a field declaration (top-level
+ *     name or a path through group/array fields; never through blocks).
  *  7. `defaultSort` sanity — `field` resolves to a top-level schema field
  *     or a document-level column (`createdAt` / `updatedAt` / `path`), the
  *     direction (when given) is `asc` | `desc`, and the option is rejected
@@ -52,9 +86,11 @@ export function validateAdminConfigs(admins, collections) {
  *     `type: 'blocks'` field across the registered collections (blocks have
  *     no global registry; the collections walk is the source of truth).
  *  2. Uniqueness — no two entries share a `blockType`.
- *  3. `fields` map sanity — every key matches a top-level field name of the
- *     block (when the same `blockType` appears in several collections, the
- *     union of their top-level field names is accepted).
+ *  3. `fields` map sanity — every key is a dotted, index-free schema path
+ *     resolving to a field declaration of the block (top-level name or a
+ *     path through group/array fields; never through a nested blocks field).
+ *     When the same `blockType` appears in several collections, a key is
+ *     accepted if it resolves in any declaration site (union semantics).
  *
  * Throws a plain `Error` for the same reason `validateAdminConfigs` does —
  * this runs at startup, before the logger is necessarily wired up.
@@ -62,34 +98,21 @@ export function validateAdminConfigs(admins, collections) {
 export function validateBlockAdminConfigs(blockAdmins, collections) {
     if (blockAdmins == null || blockAdmins.length === 0)
         return;
-    // Collect blockType → union of top-level field names across every
-    // declaration site (including blocks nested inside groups/arrays/blocks).
-    const blockFieldNames = new Map();
-    const walkBlock = (block) => {
-        let names = blockFieldNames.get(block.blockType);
-        if (names == null) {
-            names = new Set();
-            blockFieldNames.set(block.blockType, names);
-        }
-        for (const field of block.fields) {
-            if ('name' in field)
-                names.add(field.name);
-        }
-        walkFields(block.fields);
-    };
-    const walkFields = (fields) => {
-        for (const field of fields) {
-            if (field.type === 'blocks') {
-                for (const block of field.blocks)
-                    walkBlock(block);
-            }
-            else if ('fields' in field && Array.isArray(field.fields)) {
-                walkFields(field.fields);
-            }
-        }
-    };
+    // Collect blockType → declaration sites across every registered collection
+    // (including blocks nested inside groups/arrays/blocks). Structural drift
+    // between same-blockType declarations is possible, so keys validate against
+    // the union of sites.
+    const blocksByType = new Map();
     for (const collection of collections) {
-        walkFields(collection.fields);
+        walkFieldDeclarations(collection.fields, () => { }, {
+            onBlock: (block) => {
+                const sites = blocksByType.get(block.blockType);
+                if (sites == null)
+                    blocksByType.set(block.blockType, [block]);
+                else
+                    sites.push(block);
+            },
+        });
     }
     const seen = new Set();
     for (const entry of blockAdmins) {
@@ -99,17 +122,28 @@ export function validateBlockAdminConfigs(blockAdmins, collections) {
         }
         seen.add(entry.blockType);
         // Rule 1 — block pairing.
-        const names = blockFieldNames.get(entry.blockType);
-        if (names == null) {
+        const sites = blocksByType.get(entry.blockType);
+        if (sites == null) {
             throw new Error(`Block admin config "${entry.blockType}" has no matching block (no \`type: 'blocks'\` field of any registered collection declares a block with \`blockType: '${entry.blockType}'\`).`);
         }
-        // Rule 3 — `fields` keys must be top-level field names of the block.
+        // Rule 3 — `fields` keys must be schema paths resolving within the block
+        // (union across declaration sites). 'blocks' beats 'unresolved' in the
+        // union so the traversal error surfaces when any site has the nested
+        // blocks field the key tried to walk through.
         if (entry.fields != null) {
-            for (const key of Object.keys(entry.fields)) {
-                if (!names.has(key)) {
-                    throw new Error(`Block "${entry.blockType}": \`fields["${key}"]\` references a name that is not a top-level field of the block. Per-field overrides apply only to the block's top-level fields.`);
+            validateFieldAdminKeys(Object.keys(entry.fields), (key) => {
+                let best = 'unresolved';
+                for (const block of sites) {
+                    const resolution = resolveSchemaPath(block.fields, key);
+                    if (resolution === 'ok')
+                        return 'ok';
+                    if (resolution === 'blocks')
+                        best = 'blocks';
                 }
-            }
+                return best;
+            }, (msg) => {
+                throw new Error(`Block "${entry.blockType}": ${msg}`);
+            });
         }
     }
 }
@@ -272,13 +306,10 @@ function validateOne(admin, collectionsByPath) {
             }
         }
     }
-    // Rule 6 — `fields` map keys must match top-level schema field names.
+    // Rule 6 — `fields` map keys must be schema paths resolving to a field
+    // declaration of the collection.
     if (admin.fields != null) {
-        for (const key of Object.keys(admin.fields)) {
-            if (!topLevelFieldNames.has(key)) {
-                fail(`\`fields["${key}"]\` references a name that is not a top-level schema field. Per-field overrides apply only to top-level schema fields.`);
-            }
-        }
+        validateFieldAdminKeys(Object.keys(admin.fields), (key) => resolveSchemaPath(collection.fields, key), fail);
     }
     // Rule 2 + 3 — layout: name resolution + bookkeeping (every schema field
     // placed exactly once). Skipped when no `layout` is declared (the

package/dist/config/validate-admin-configs.test.node.js

@@ -199,7 +199,63 @@ describe('validateAdminConfigs', () => {
             ...baseAdmin,
             fields: { nonexistent: {} },
         };
-        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/not a top-level schema field/);
+        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/does not resolve to a field declaration/);
+    });
+    // Rule 6 — dotted schema-path keys. A dedicated collection with nested
+    // structure: files (array) → filesGroup (group) → leaf fields, plus a
+    // blocks field to prove traversal through blocks is rejected.
+    const nestedCollection = {
+        path: 'library',
+        labels: { singular: 'Item', plural: 'Items' },
+        useAsPath: 'title',
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            {
+                name: 'files',
+                label: 'Files',
+                type: 'array',
+                fields: [
+                    {
+                        name: 'filesGroup',
+                        type: 'group',
+                        fields: [
+                            { name: 'publicationFile', label: 'File', type: 'file' },
+                            { name: 'notes', label: 'Notes', type: 'richText' },
+                        ],
+                    },
+                ],
+            },
+            {
+                name: 'sections',
+                label: 'Sections',
+                type: 'blocks',
+                blocks: [
+                    {
+                        blockType: 'proseBlock',
+                        fields: [{ name: 'body', label: 'Body', type: 'richText' }],
+                    },
+                ],
+            },
+        ],
+    };
+    const nestedAdmin = (fields) => ({
+        slug: 'library',
+        fields: fields,
+    });
+    it('accepts a dotted fields key through array and group declarations', () => {
+        expect(() => validateAdminConfigs([nestedAdmin({ 'files.filesGroup.notes': {} })], [nestedCollection])).not.toThrow();
+    });
+    it('rejects a dotted fields key whose leaf does not exist', () => {
+        expect(() => validateAdminConfigs([nestedAdmin({ 'files.filesGroup.missing': {} })], [nestedCollection])).toThrow(/does not resolve to a field declaration/);
+    });
+    it('rejects a dotted fields key that walks through a value field', () => {
+        expect(() => validateAdminConfigs([nestedAdmin({ 'title.anything': {} })], [nestedCollection])).toThrow(/does not resolve to a field declaration/);
+    });
+    it('rejects a fields key carrying an item index', () => {
+        expect(() => validateAdminConfigs([nestedAdmin({ 'files[0].filesGroup.notes': {} })], [nestedCollection])).toThrow(/index-free schema paths/);
+    });
+    it('rejects a fields key that traverses a blocks field', () => {
+        expect(() => validateAdminConfigs([nestedAdmin({ 'sections.body': {} })], [nestedCollection])).toThrow(/blockAdmin/);
     });
     // Rule 7 — defaultSort sanity.
     it('accepts a defaultSort on a schema field', () => {
@@ -345,8 +401,42 @@ describe('validateBlockAdminConfigs', () => {
         expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock' }, { blockType: 'quoteBlock' }], [blockCollection])).toThrow(/registered more than once/);
     });
     // Rule 3 — fields map sanity.
-    it('rejects a fields key that is not a top-level field of the block', () => {
-        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { doesNotExist: {} } }], [blockCollection])).toThrow(/not a top-level field of the block/);
+    it('rejects a fields key that is not a field of the block', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { doesNotExist: {} } }], [blockCollection])).toThrow(/does not resolve to a field declaration/);
+    });
+    // Rule 3 — dotted schema-path keys inside a block (array-in-block, the
+    // FAQBlock shape).
+    const faqBlock = {
+        blockType: 'faqBlock',
+        fields: [
+            {
+                name: 'faq',
+                label: 'Questions',
+                type: 'array',
+                fields: [
+                    { name: 'question', label: 'Question', type: 'text' },
+                    { name: 'answer', label: 'Answer', type: 'richText' },
+                ],
+            },
+        ],
+    };
+    const faqCollection = {
+        path: 'docs',
+        labels: { singular: 'Doc', plural: 'Docs' },
+        useAsPath: 'title',
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            { name: 'content', label: 'Content', type: 'blocks', blocks: [faqBlock] },
+        ],
+    };
+    it('accepts a dotted fields key addressing a field inside an array in the block', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'faqBlock', fields: { 'faq.answer': {} } }], [faqCollection])).not.toThrow();
+    });
+    it('rejects a dotted fields key whose leaf is not declared in the block', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'faqBlock', fields: { 'faq.missing': {} } }], [faqCollection])).toThrow(/does not resolve to a field declaration/);
+    });
+    it('rejects a block fields key carrying an item index', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'faqBlock', fields: { 'faq[0].answer': {} } }], [faqCollection])).toThrow(/index-free schema paths/);
     });
     it('accepts the union of field names when a blockType appears in several collections', () => {
         const other = {

package/dist/config/validate-collections.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { formatDeclarationPath, walkFieldDeclarations } from '../paths/index.js';
 import { fieldTypeToStore } from '../storage/field-store-map.js';
 /**
  * Field names that cannot be declared in a collection schema because they
@@ -61,37 +62,27 @@ function hasLocalizedField(fields) {
     });
     return found;
 }
+/** Every field declaration, for checks that don't care where it sits. */
 function walkFields(fields, visit) {
-    for (const field of fields) {
+    walkFieldDeclarations(fields, (field) => {
         visit(field);
-        if (field.type === 'group' || field.type === 'array') {
-            walkFields(field.fields, visit);
-        }
-        else if (field.type === 'blocks') {
-            for (const block of field.blocks) {
-                walkFields(block.fields, visit);
-            }
-        }
-    }
+    });
 }
 /**
- * Path-aware variant of `walkFields` — visits every field with its dotted
- * schema path (e.g. `files.filesGroup.generateThumbnail`) so validation
+ * Path-aware variant of `walkFields` — visits every field with its
+ * declaration path (e.g. `files.filesGroup.generateThumbnail`) so validation
  * errors can point at the exact declaration site.
+ *
+ * Delegates to the shared grammar's canonical walk. It previously descended
+ * into blocks without recording the block type, which made the emitted path
+ * ambiguous whenever two blocks in one field declared the same field name —
+ * both rendered as `content.alt`, and the message could not say which was at
+ * fault. `walkFieldDeclarations` carries the block type through.
  */
-function walkFieldsWithPath(fields, visit, prefix = '') {
-    for (const field of fields) {
-        const fieldPath = prefix === '' ? field.name : `${prefix}.${field.name}`;
-        visit(field, fieldPath);
-        if (field.type === 'group' || field.type === 'array') {
-            walkFieldsWithPath(field.fields, visit, fieldPath);
-        }
-        else if (field.type === 'blocks') {
-            for (const block of field.blocks) {
-                walkFieldsWithPath(block.fields, visit, fieldPath);
-            }
-        }
-    }
+function walkFieldsWithPath(fields, visit) {
+    walkFieldDeclarations(fields, (field, segments) => {
+        visit(field, formatDeclarationPath(segments));
+    });
 }
 /**
  * Top-level field names a collection's `search` config references (body +
@@ -114,6 +105,52 @@ function searchReferencedFieldNames(collection) {
     }
     return names;
 }
+/**
+ * Enforce that every field named by a collection's `search` config resolves.
+ *
+ * `buildSearchDocument` looks each name up among the collection's **top-level**
+ * fields and silently skips anything it cannot resolve, so an unrecognised or
+ * dotted name produced a collection that indexed less than its author thought
+ * — with no error at boot and no signal at index time.
+ *
+ * Nested content is reachable, but by naming its top-level *container*: a
+ * `group` / `array` / `blocks` field named in `search.body` is walked
+ * recursively and every nested text leaf is flattened into the body. What is
+ * not supported is addressing one specific nested declaration, which is why a
+ * dotted path is rejected outright rather than accepted and ignored.
+ */
+function validateSearchFields(collection) {
+    const search = collection.search;
+    if (search == null)
+        return;
+    const topLevel = (name) => collection.fields.find((f) => 'name' in f && f.name === name);
+    const check = (name, option) => {
+        if (name.includes('.')) {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.${option}\` but search config addresses top-level fields only. To index content nested inside a \`group\` / \`array\` / \`blocks\` field, name the top-level container — it is walked recursively and every nested text leaf is flattened into the body.`);
+        }
+        const field = topLevel(name);
+        if (field == null) {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.${option}\` but no top-level field with that name exists.`);
+        }
+        return field;
+    };
+    for (const decl of search.body ?? []) {
+        check(typeof decl === 'string' ? decl : decl.field, 'body');
+    }
+    for (const decl of search.facets ?? []) {
+        const name = typeof decl === 'string' ? decl : decl.field;
+        const field = check(name, 'facets');
+        if (field.type !== 'relation') {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.facets\` but field "${name}" has type "${field.type}". Facets are controlled-vocabulary references — name a \`relation\` field.`);
+        }
+    }
+    for (const name of search.filters ?? []) {
+        const field = check(name, 'filters');
+        if (field.type === 'group' || field.type === 'array' || field.type === 'blocks') {
+            throw new Error(`Collection "${collection.path}" names '${name}' in \`search.filters\` but field "${name}" has type "${field.type}". Filters project a single scalar value — name a value field.`);
+        }
+    }
+}
 /**
  * Enforce the `virtual` field constraints for one collection. See
  * `BaseField.virtual` in field-types.ts for the contract these rules back:
@@ -236,6 +273,7 @@ export function validateCollections(collections) {
         if (collection.tree === true && collection.orderable === true) {
             throw new Error(`Collection "${collection.path}" sets both \`tree: true\` and \`orderable: true\`. A document-tree collection owns ordering on the tree edge (per-parent), so \`byline_documents.order_key\` is inert — set only \`tree: true\`.`);
         }
+        validateSearchFields(collection);
         validateVirtualFields(collection);
         validateUploadLocations(collection);
     }