canopycms 0.4.0 → 0.5.0

package/dist/editor/fields/use-reference-options.js

@@ -0,0 +1,121 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { createApiClient } from '../../api/client.js';
+import { getErrorMessage } from '../../utils/error.js';
+import { useOptionalApiClient } from '../context/index.js';
+/** The id a stored reference holds: the id itself, or a resolved read's `{ id, … }`. */
+export const extractId = (val) => {
+    if (typeof val === 'string')
+        return val;
+    if (val && typeof val === 'object' && 'id' in val && typeof val.id === 'string')
+        return val.id;
+    return '';
+};
+/** Label for a set value the options omit (a restricted, missing or unlisted target). */
+export function unlistedReferenceLabel(value, id) {
+    if (value && typeof value === 'object' && 'unavailable' in value && value.unavailable === true) {
+        if ('reason' in value && value.reason === 'restricted' && 'title' in value) {
+            return `Restricted entry: ${String(value.title)}`;
+        }
+        return `Missing entry (${id})`;
+    }
+    return `Unavailable entry (${id})`;
+}
+/** `optionSort` as the reference-options endpoint's `sort`, `sortField` and `sortDir` params. */
+function sortParams(sort) {
+    if (sort === undefined)
+        return {};
+    if (typeof sort === 'string')
+        return { sort };
+    return {
+        sort: 'field',
+        sortField: sort.field,
+        ...(sort.direction && { sortDir: sort.direction }),
+    };
+}
+/**
+ * The entries a reference field offers: `staticOptions` as given, else one request per field to
+ * the reference-options endpoint, made again only when the query or the API client changes, or on
+ * `retry`.
+ */
+export function useReferenceOptions({ staticOptions, collections, entryTypes, displayField, branch, optionSort, }) {
+    // `null` outside an ApiClientProvider (some stories), so the fetch falls back to a
+    // default-configured client.
+    const contextApiClient = useOptionalApiClient();
+    const hasCollections = !!collections && collections.length > 0;
+    const hasEntryTypes = !!entryTypes && entryTypes.length > 0;
+    const needsFetch = !staticOptions && (hasCollections || hasEntryTypes);
+    const [fetched, setFetched] = useState([]);
+    const [loading, setLoading] = useState(needsFetch);
+    const [error, setError] = useState(null);
+    const [retryCount, setRetryCount] = useState(0);
+    // A changed query starts loading in the same render, so no stale option list shows meanwhile.
+    const [prevFetchKey, setPrevFetchKey] = useState('');
+    const fetchKey = needsFetch
+        ? `${collections?.join(',') ?? ''}:${entryTypes?.join(',') ?? ''}:${displayField}:${branch}:${JSON.stringify(optionSort ?? null)}`
+        : '';
+    if (fetchKey !== prevFetchKey) {
+        setPrevFetchKey(fetchKey);
+        if (needsFetch) {
+            setLoading(true);
+            setError(null);
+        }
+    }
+    // Keyed on `fetchKey`, not the `collections`/`entryTypes` arrays, which the parent rebuilds on
+    // every render, so those and `displayField`/`branch`/`optionSort` are left out of the deps on
+    // purpose.
+    // `active` drops a response a newer request or an unmount has superseded.
+    useEffect(() => {
+        if (!needsFetch)
+            return;
+        let active = true;
+        const apiClient = contextApiClient ?? createApiClient();
+        const params = { branch, displayField };
+        if (collections && collections.length > 0)
+            params.collections = collections.join(',');
+        if (entryTypes && entryTypes.length > 0)
+            params.entryTypes = entryTypes.join(',');
+        Object.assign(params, sortParams(optionSort));
+        apiClient.content
+            .getReferenceOptions(params)
+            .then((response) => {
+            if (!active)
+                return;
+            if (response.ok && response.data?.options) {
+                setFetched(response.data.options.map((opt) => ({
+                    value: opt.id,
+                    label: opt.label,
+                    ...(opt.noindex ? { noindex: opt.noindex } : {}),
+                })));
+            }
+            else {
+                setError(response.error || 'Failed to load reference options');
+            }
+        })
+            .catch((err) => {
+            if (!active)
+                return;
+            console.error('Failed to load reference options:', err);
+            setError(getErrorMessage(err));
+        })
+            .finally(() => {
+            if (!active)
+                return;
+            setLoading(false);
+        });
+        return () => {
+            active = false;
+        };
+    }, [needsFetch, fetchKey, retryCount, contextApiClient]);
+    const retry = () => {
+        setLoading(true);
+        setError(null);
+        setRetryCount((count) => count + 1);
+    };
+    return {
+        options: staticOptions ?? fetched,
+        loading: needsFetch && loading,
+        error: needsFetch ? error : null,
+        retry,
+    };
+}

package/dist/editor/form-outline.d.ts

@@ -7,7 +7,7 @@ import type { OutlineNode } from './FormHeader.js';
  */
 export declare function buildFormOutline(fields: readonly FieldConfig[], value: Record<string, unknown>, customTypes?: ReadonlySet<string>): OutlineNode[];
 /**
- * True when some field, at any depth, is a block field or a list of objects that the form draws
- * itself: a type in `customTypes` has a custom renderer.
+ * True when some field, at any depth, is a block field or a list of objects or references that the
+ * form draws itself: a type in `customTypes` has a custom renderer.
  */
 export declare function hasCollapsibleList(fields: readonly FieldConfig[], customTypes?: ReadonlySet<string>): boolean;

package/dist/editor/form-outline.js

@@ -49,8 +49,8 @@ export function buildFormOutline(fields, value, customTypes = new Set()) {
     return fields.map(nodeOf);
 }
 /**
- * True when some field, at any depth, is a block field or a list of objects that the form draws
- * itself: a type in `customTypes` has a custom renderer.
+ * True when some field, at any depth, is a block field or a list of objects or references that the
+ * form draws itself: a type in `customTypes` has a custom renderer.
  */
 export function hasCollapsibleList(fields, customTypes = new Set()) {
     return fields.some((field) => {
@@ -58,6 +58,8 @@ export function hasCollapsibleList(fields, customTypes = new Set()) {
             return false;
         if (field.type === 'block')
             return true;
+        if (field.type === 'reference' && field.list === true)
+            return true;
         if (field.type === 'group') {
             return hasCollapsibleList(field.fields, customTypes);
         }

package/dist/editor/theme.js

@@ -377,6 +377,11 @@ const CANOPY_STYLES = `
 [data-combobox-selected] {
   --mantine-primary-color-filled: var(--canopy-primary-fill);
 }
+[data-combobox-selected] [data-canopy-option-badge] {
+  color: inherit;
+  background: transparent;
+  box-shadow: inset 0 0 0 1px currentColor;
+}
 .mantine-DateTimePicker-day[data-selected],
 .mantine-DateTimePicker-pickerControl[data-selected] {
   background-color: var(--canopy-primary-fill);

package/dist/entry-schema-registry.d.ts

@@ -18,7 +18,7 @@ import type { EntrySchemaRegistry } from './schema/types.js';
  * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: field names a path can spell, select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups inside object/block fields,
- * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement.
+ * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement, `maxItems` placement.
  *
  * @example
  * ```typescript

package/dist/entry-schema-registry.js

@@ -2,7 +2,7 @@ import { countTitleFields, findInvalidTitleFields, findTitleFieldsInLists, } fro
 import { countBodyFields, findInvalidBodyFields, findReservedBodyFieldName, } from './utils/body-field.js';
 import { RESOLVED_REFERENCE_KEYS, RESTRICTED_REFERENCE_MARKER } from './entry-schema.js';
 import { flattenGroupFields } from './utils/flatten-group-fields.js';
-import { ensureFieldNamesSpellInPaths, ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureItemTitleFieldsExist, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, ensureMarkdownFieldOptions, ensureStampOnPublishPlacement, } from './config/validation.js';
+import { ensureFieldNamesSpellInPaths, ensureSelectFieldsHaveOptions, ensureReferenceFieldsHaveScope, ensureItemTitleFieldsExist, ensureNoFlattenedFieldNameCollisions, ensureNoGroupsInsideComplexFields, ensureMarkdownFieldOptions, ensureMaxItemsPlacement, ensureStampOnPublishPlacement, } from './config/validation.js';
 /** Look up a field's type by dotted path (e.g., "meta.order").
  * Groups are transparent — their children are searched at the same path level. */
 function findFieldType(fields, dottedPath) {
@@ -41,7 +41,7 @@ function findFieldType(fields, dottedPath) {
  * `RESOLVED_REFERENCE_KEYS`; a top-level or inline-group field named `unavailable`. This is also the one
  * place the shared field-shape checks run: field names a path can spell, select fields must have options,
  * reference fields must have `collections` or `entryTypes`, no inline groups inside object/block fields,
- * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement.
+ * no field-name collisions after group flattening, valid `mdxAllow`, `stampOnPublish` placement, `maxItems` placement.
  *
  * @example
  * ```typescript
@@ -102,6 +102,7 @@ export function createEntrySchemaRegistry(registry) {
         ensureNoGroupsInsideComplexFields(schema);
         ensureMarkdownFieldOptions(schema);
         ensureStampOnPublishPlacement(schema, `Entry schema registry entry "${key}"`);
+        ensureMaxItemsPlacement(schema, `Entry schema registry entry "${key}"`);
         ensureNoFlattenedFieldNameCollisions(schema, `entry schema "${key}"`);
     }
     return registry;

package/dist/entry-schema.d.ts

@@ -372,7 +372,8 @@ export declare const defineInlineFieldGroup: <const T extends {
  *
  * **Flat by default** — an inline group, stored at the top level of the content file with no data
  * key of its own. `group: 'seo'` nests them under that key instead, and the same
- * `{ group: 'seo' }` must then be passed to `extractSeoFields` / `entryToMetadata`.
+ * `{ group: 'seo' }` must then be set as `seo` in `defineCanopyConfig`, or passed to
+ * `extractSeoFields` and the free `entryToMetadata`.
  *
  * @example
  * // Flat (recommended): frontmatter carries `metaTitle:` at the top level.
@@ -461,8 +462,9 @@ export declare function defineSeoFieldGroup(opts?: SeoFieldGroupOptions & {
 }): InlineSeoFieldGroup;
 export declare function defineSeoFieldGroup<const G extends string>(opts: SeoFieldGroupOptions & {
     /**
-     * Nest the fields under this data key instead of storing them flat. Must match the `group`
-     * option passed to `extractSeoFields` / `entryToMetadata`.
+     * Nest the fields under this data key instead of storing them flat. Must match
+     * `CanopyConfig.seo.group`, or the `group` passed to `extractSeoFields` and the free
+     * `entryToMetadata`.
      */
     group: G;
 }): NestedSeoFieldGroup<G>;

package/dist/entry-schema.js

@@ -101,7 +101,8 @@ export const defineInlineFieldGroup = (group) => ({ ...group, type: 'group' });
  *
  * **Flat by default** — an inline group, stored at the top level of the content file with no data
  * key of its own. `group: 'seo'` nests them under that key instead, and the same
- * `{ group: 'seo' }` must then be passed to `extractSeoFields` / `entryToMetadata`.
+ * `{ group: 'seo' }` must then be set as `seo` in `defineCanopyConfig`, or passed to
+ * `extractSeoFields` and the free `entryToMetadata`.
  *
  * @example
  * // Flat (recommended): frontmatter carries `metaTitle:` at the top level.

package/dist/reference-resolver.d.ts

@@ -1,10 +1,26 @@
+import type { ReferenceOptionSort } from './config/index.js';
 import type { ContentStore } from './content-store.js';
 import type { ContentIdIndex } from './content-id-index.js';
 import { type LogicalPath } from './paths/index.js';
+import { type SeoFieldLocation } from './static/seo.js';
 export interface ReferenceOption {
     id: string;
     label: string;
     collection: string;
+    /**
+     * Present when the target is `noindex` at `config.seo`'s location, so a page that lists only
+     * indexed entries won't show it. `fieldLabel` is the editor label of the target's own noindex
+     * field, so the picker can name the setting in the words the editor sees on that entry.
+     */
+    noindex?: {
+        fieldLabel: string;
+    };
+}
+export interface LoadReferenceOptionsSettings {
+    /** Where entries keep their SEO fields: `CanopyConfig.seo`. */
+    seo?: SeoFieldLocation;
+    /** Default `'label'`. */
+    sort?: ReferenceOptionSort;
 }
 /**
  * Loads the options a reference field's picker offers. Resolving a stored reference to its
@@ -24,6 +40,7 @@ export declare class ReferenceResolver {
      *   logical path (`entryLogicalPath`) before it is read. Returning false skips the entry entirely --
      *   no file I/O, no label, no option -- so a caller who can't read a path never
      *   triggers a read for content they won't be allowed to see anyway.
+     * @param settings - The SEO location the `noindex` marker reads, and the option order.
      */
-    loadReferenceOptions(collections?: LogicalPath[], displayField?: string, search?: string, entryTypes?: string[], canAccess?: (logicalPath: LogicalPath) => boolean): Promise<ReferenceOption[]>;
+    loadReferenceOptions(collections?: LogicalPath[], displayField?: string, search?: string, entryTypes?: string[], canAccess?: (logicalPath: LogicalPath) => boolean, settings?: LoadReferenceOptionsSettings): Promise<ReferenceOption[]>;
 }

package/dist/reference-resolver.js

@@ -1,6 +1,8 @@
 import nodePath from 'node:path';
 import { extractSlugFromFilename, extractEntryTypeFromFilename } from './content-id-index.js';
-import { entryLogicalPath } from './paths/index.js';
+import { sortByOrder } from './content-listing.js';
+import { entryLogicalPath, } from './paths/index.js';
+import { DEFAULT_SEO_FIELD_NAMES, isNoindexEntry } from './static/seo.js';
 /**
  * Loads the options a reference field's picker offers. Resolving a stored reference to its
  * target is `ContentStore`'s job (`read()`, `resolveReferenceTarget`).
@@ -20,9 +22,13 @@ export class ReferenceResolver {
      *   logical path (`entryLogicalPath`) before it is read. Returning false skips the entry entirely --
      *   no file I/O, no label, no option -- so a caller who can't read a path never
      *   triggers a read for content they won't be allowed to see anyway.
+     * @param settings - The SEO location the `noindex` marker reads, and the option order.
      */
-    async loadReferenceOptions(collections, displayField = 'title', search, entryTypes, canAccess) {
-        const options = [];
+    async loadReferenceOptions(collections, displayField = 'title', search, entryTypes, canAccess, settings = {}) {
+        const loaded = [];
+        const sort = settings.sort ?? 'label';
+        const sortField = typeof sort === 'object' ? sort.field : undefined;
+        const noindexLabels = new NoindexFieldLabels(this.store.getSchemaItems(), settings.seo);
         let candidates;
         if (collections && collections.length > 0) {
             const results = await Promise.all(collections.map((col) => this.store.getCollectionEntryPaths(col)));
@@ -60,10 +66,15 @@ export class ReferenceResolver {
                 if (search && !label.toLowerCase().includes(search.toLowerCase())) {
                     continue;
                 }
-                options.push({
-                    id,
-                    label,
-                    collection: location.collection,
+                const option = { id, label, collection: location.collection };
+                if (isNoindexEntry(doc.data, settings.seo)) {
+                    const entryType = extractEntryTypeFromFilename(filename) ?? '';
+                    option.noindex = { fieldLabel: noindexLabels.get(location.collection, entryType) };
+                }
+                loaded.push({
+                    option,
+                    contentId: id,
+                    sortValue: sortField === undefined ? undefined : sortValueAt(doc.data, sortField),
                 });
             }
             catch (error) {
@@ -75,6 +86,162 @@ export class ReferenceResolver {
                 continue;
             }
         }
-        return options.sort((a, b) => a.label.localeCompare(b.label));
+        if (sort === 'collection')
+            return sortByCollection(loaded, this.store.getSchemaItems());
+        if (typeof sort === 'object')
+            return sortByField(loaded, sort.direction ?? 'asc');
+        return loaded.map((l) => l.option).sort(byLabel);
+    }
+}
+const byLabel = (a, b) => a.label.localeCompare(b.label);
+/**
+ * The value at a dotted path, read through own properties only so a path like `__proto__`
+ * reads nothing. A non-blank string, a finite number or a valid date counts as a value; a date
+ * becomes its ISO string, since md/mdx frontmatter parses an unquoted `YYYY-MM-DD` as a `Date`.
+ */
+function sortValueAt(data, path) {
+    let current = data;
+    for (const segment of path.split('.')) {
+        if (typeof current !== 'object' || current === null || Array.isArray(current))
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    if (typeof current === 'number')
+        return Number.isFinite(current) ? current : undefined;
+    if (typeof current === 'string')
+        return current.trim() || undefined;
+    if (current instanceof Date) {
+        return Number.isNaN(current.getTime()) ? undefined : current.toISOString();
+    }
+    return undefined;
+}
+/**
+ * Numbers before strings, so a field typed differently across entry types still sorts in one
+ * consistent order; numbers compare numerically, strings as plain text, which orders ISO dates.
+ */
+function compareValues(a, b) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    if (typeof a === 'number')
+        return -1;
+    if (typeof b === 'number')
+        return 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Entries with no value go first under `desc` and last under `asc`: newest-first then puts an
+ * entry whose date is not yet stamped at the top, where an editor queueing it looks.
+ */
+function sortByField(loaded, direction) {
+    const sign = direction === 'desc' ? -1 : 1;
+    return loaded
+        .sort((a, b) => {
+        if (a.sortValue === undefined || b.sortValue === undefined) {
+            if (a.sortValue !== b.sortValue) {
+                const aMissingFirst = direction === 'desc';
+                return (a.sortValue === undefined) === aMissingFirst ? -1 : 1;
+            }
+        }
+        else {
+            const byValue = compareValues(a.sortValue, b.sortValue) * sign;
+            if (byValue !== 0)
+                return byValue;
+        }
+        return byLabel(a.option, b.option);
+    })
+        .map((l) => l.option);
+}
+/**
+ * One group per collection in content-tree order: a collection, then each subcollection in its
+ * parent's `order`. Within a group, options follow the collection's own `order`, then label.
+ */
+function sortByCollection(loaded, schemaItems) {
+    const collections = [...schemaItems].filter((item) => item.type === 'collection');
+    const byPath = new Map(collections.map((c) => [c.logicalPath, c]));
+    const children = new Map();
+    const roots = [];
+    for (const collection of collections) {
+        const parent = collection.parentPath;
+        if (parent === undefined || !byPath.has(parent)) {
+            roots.push(collection);
+        }
+        else {
+            children.set(parent, [...(children.get(parent) ?? []), collection]);
+        }
+    }
+    const treeOrder = [];
+    const visit = (siblings, order) => {
+        for (const collection of sortByOrder([...siblings], order, (c) => c.name)) {
+            treeOrder.push(collection);
+            visit(children.get(collection.logicalPath) ?? [], collection.order);
+        }
+    };
+    visit(roots, undefined);
+    const groups = new Map();
+    for (const item of loaded) {
+        const path = item.option.collection;
+        groups.set(path, [...(groups.get(path) ?? []), item]);
+    }
+    const result = [];
+    const appendGroup = (path, order) => {
+        const group = groups.get(path);
+        if (!group)
+            return;
+        groups.delete(path);
+        result.push(...sortByOrder(group, order, (l) => l.option.label).map((l) => l.option));
+    };
+    for (const collection of treeOrder)
+        appendGroup(collection.logicalPath, collection.order);
+    // A collection missing from the schema still gets a group, after the known ones.
+    for (const path of [...groups.keys()].sort())
+        appendGroup(path, undefined);
+    return result;
+}
+/**
+ * The editor label of each entry type's noindex field, found where `seo` says the flag lives:
+ * a top-level field (inline groups are transparent), or a field inside the object named by
+ * `seo.group`. Falls back to the field's name when the schema has no such field.
+ */
+class NoindexFieldLabels {
+    constructor(schemaItems, seo) {
+        this.seo = seo;
+        this.cache = new Map();
+        this.entryTypes = [...schemaItems].filter((item) => item.type === 'entry-type');
+        this.fieldName = seo?.fields?.noindex || DEFAULT_SEO_FIELD_NAMES.noindex;
+    }
+    get(collection, entryType) {
+        const key = `${collection}\0${entryType}`;
+        const cached = this.cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const schema = this.entryTypes.find((item) => item.parentPath === collection && item.name === entryType)?.schema;
+        const label = (schema && this.findLabel(schema)) ?? this.fieldName;
+        this.cache.set(key, label);
+        return label;
+    }
+    findLabel(schema) {
+        let fields = schema;
+        if (this.seo?.group) {
+            const group = findField(schema, this.seo.group);
+            fields = group?.type === 'object' ? group.fields : undefined;
+        }
+        const field = fields && findField(fields, this.fieldName);
+        return field ? (field.label ?? field.name) : undefined;
+    }
+}
+/** A field by data name, looking through inline groups, which store no key of their own. */
+function findField(fields, name) {
+    for (const field of fields) {
+        if (field.type === 'group') {
+            const inner = findField(field.fields, name);
+            if (inner)
+                return inner;
+        }
+        else if (field.name === name) {
+            return field;
+        }
     }
+    return undefined;
 }

package/dist/schema/schema-store.d.ts

@@ -164,14 +164,14 @@ declare const updateEntryTypeInputSchema: z.ZodObject<{
     default?: boolean | undefined;
     format?: "mdx" | "md" | "json" | "yaml" | undefined;
     label?: string | undefined;
-    schema?: string | undefined;
     maxItems?: number | undefined;
+    schema?: string | undefined;
 }, {
     default?: boolean | undefined;
     format?: "mdx" | "md" | "json" | "yaml" | undefined;
     label?: string | undefined;
-    schema?: string | undefined;
     maxItems?: number | undefined;
+    schema?: string | undefined;
 }>;
 /**
  * Thrown when a schema mutation cannot proceed because the per-branch

package/dist/static/index.d.ts

@@ -101,11 +101,13 @@ type StaticBuildContext = Pick<CanopyBuildContext, 'listEntries'> & Partial<Pick
  * when you actually mean to — omission should be a decision, not an oversight.
  *
  * `noindex` is NOT applied here: an entry that must not be advertised must still be built. Apply
- * `isNoindexEntry` at the advertising surface (as `generateContentSitemap` does).
+ * `isNoindexEntry` at the advertising surface (as `generateContentSitemap` does), at the SEO
+ * location in `CanopyConfig.seo`.
  *
  * @example
- * const entries = await collectRoutableEntries(await getCanopyForBuild())
- * const published = entries.filter((e) => !isNoindexEntry(e.data))
+ * const ctx = await getCanopyForBuild()
+ * const entries = await collectRoutableEntries(ctx)
+ * const published = entries.filter((e) => !isNoindexEntry(e.data, ctx.services.config.seo))
  */
 export declare function collectRoutableEntries<T = Record<string, unknown>>(ctx: StaticBuildContext, options?: CollectRoutableEntriesOptions<T>): Promise<RoutableEntry<T>[]>;
 /**
@@ -206,7 +208,9 @@ export declare function warnUnsafeMarkdown(items: readonly BuildScanItem[], phas
  *
  * Fails the build rather than silently skipping the offending entry: a page that silently
  * disappears from a static build is a worse failure mode than a red build. Lists every
- * offending entry so one build catches every abandoned scaffold, not just the first.
+ * offending entry so one build catches every abandoned scaffold, not just the first. An
+ * over-`maxItems` list gets its own line per list, with the fix; the abandoned-scaffold advice
+ * appears only when some entry has another kind of error.
  */
 export declare function assertBuildEntriesValid(items: readonly BuildScanItem[], phaseLabel: string): void;
 /**

package/dist/static/index.js

@@ -68,11 +68,13 @@ async function enumerateRoutableEntries(ctx, rootPath, phaseLabel, resolveRefere
  * when you actually mean to — omission should be a decision, not an oversight.
  *
  * `noindex` is NOT applied here: an entry that must not be advertised must still be built. Apply
- * `isNoindexEntry` at the advertising surface (as `generateContentSitemap` does).
+ * `isNoindexEntry` at the advertising surface (as `generateContentSitemap` does), at the SEO
+ * location in `CanopyConfig.seo`.
  *
  * @example
- * const entries = await collectRoutableEntries(await getCanopyForBuild())
- * const published = entries.filter((e) => !isNoindexEntry(e.data))
+ * const ctx = await getCanopyForBuild()
+ * const entries = await collectRoutableEntries(ctx)
+ * const published = entries.filter((e) => !isNoindexEntry(e.data, ctx.services.config.seo))
  */
 export async function collectRoutableEntries(ctx, options = {}) {
     const entries = await enumerateRoutableEntries(ctx, options.rootPath, 'routable entry enumeration', options.resolveReferences);
@@ -283,22 +285,45 @@ export function warnUnsafeMarkdown(items, phaseLabel, siteAllow) {
  *
  * Fails the build rather than silently skipping the offending entry: a page that silently
  * disappears from a static build is a worse failure mode than a red build. Lists every
- * offending entry so one build catches every abandoned scaffold, not just the first.
+ * offending entry so one build catches every abandoned scaffold, not just the first. An
+ * over-`maxItems` list gets its own line per list, with the fix; the abandoned-scaffold advice
+ * appears only when some entry has another kind of error.
  */
 export function assertBuildEntriesValid(items, phaseLabel) {
     const invalid = findInvalidEntries(items);
     if (invalid.length === 0)
         return;
-    const lines = invalid.map(({ entryPath, errors }) => {
-        const [first, ...rest] = errors;
-        const summary = rest.length > 0
-            ? `${first.fieldPath}: ${first.message} (+${rest.length} more)`
-            : `${first.fieldPath}: ${first.message}`;
-        return `  - ${entryPath} — ${summary}`;
-    });
+    const lines = [];
+    let hasOverCap = false;
+    let hasOrdinary = false;
+    for (const { entryPath, errors } of invalid) {
+        const ordinary = errors.filter((e) => e.maxItems === undefined);
+        if (ordinary.length > 0) {
+            hasOrdinary = true;
+            const [first, ...rest] = ordinary;
+            const summary = rest.length > 0
+                ? `${first.fieldPath}: ${first.message} (+${rest.length} more)`
+                : `${first.fieldPath}: ${first.message}`;
+            lines.push(`  - ${entryPath} — ${summary}`);
+        }
+        for (const { fieldPath, maxItems } of errors) {
+            if (maxItems === undefined)
+                continue;
+            hasOverCap = true;
+            lines.push(`  - ${entryPath} — ${fieldPath}: ${maxItems.count} items, but maxItems is ${maxItems.cap}`);
+        }
+    }
+    const advice = [];
+    if (hasOverCap) {
+        advice.push(`A list over its maxItems: open the entry in the editor and remove a pick from that list (or remove items) until it holds at most maxItems, then rebuild. ` +
+            `This usually happens when two branches each add one item to the same list and are merged one after the other.`);
+    }
+    if (hasOrdinary) {
+        advice.push(`${hasOverCap ? 'The other errors are' : 'These are'} likely abandoned create-scaffolds (empty entries left behind when a create was started but never finished). ` +
+            `Finish editing the entry (fill in its required fields) or delete the abandoned draft, then rebuild.`);
+    }
     throw new Error(`CanopyCMS static build: found ${invalid.length} schema-invalid ${invalid.length === 1 ? 'entry' : 'entries'} during ${phaseLabel}:\n${lines.join('\n')}\n` +
-        `These are likely abandoned create-scaffolds (empty entries left behind when a create was started but never finished). ` +
-        `Finish editing the entry (fill in its required fields) or delete the abandoned draft, then rebuild.`);
+        advice.join('\n'));
 }
 /**
  * Find every `urlPath` claimed by two or more entries.

package/dist/static/seo.d.ts

@@ -72,14 +72,16 @@ export type SeoFieldLocation = Pick<ExtractSeoFieldsOptions, 'fields' | 'group'>
  */
 export declare function extractSeoFields(entryData: unknown, opts?: ExtractSeoFieldsOptions): SeoFields;
 /**
- * THE `noindex` predicate. Every surface that suppresses an entry must route through this one
- * function rather than re-deriving the flag:
+ * THE `noindex` predicate. Every surface that reads the flag routes through this one function,
+ * with `opts` taken from `CanopyConfig.seo` (canopycms-next's free helpers take it as an
+ * argument instead), rather than re-deriving it:
  *
  * - the page's own `robots: { index: false }` (canopycms-next's `entryToMetadata`),
- * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`), and
- * - exclusion from AI content (`ai/generate.ts`, unless `exclude.noindex: false`).
+ * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`),
+ * - exclusion from AI content (`ai/generate.ts`, unless `exclude.noindex: false`), and
+ * - the marker on a reference picker's option (`ReferenceResolver.loadReferenceOptions`).
  *
- * Those surfaces shipping from one predicate is the point. Derived separately, a `noindex` entry
+ * One predicate at one configured location is the point. Derived separately, a `noindex` entry
  * stays advertised in one surface while correctly absent from another, and nothing warns.
  *
  * NOT applied to enumeration: `noindex` means "don't advertise this", not "don't build this".