@byline/core 4.16.0 → 4.18.0

package/dist/config/attach-hooks.d.ts

@@ -1,11 +1,11 @@
-import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, FileField, ImageField, ServerHooksConfig, UploadHooks, UploadHooksLoader } from '../@types/index.js';
-type CollectionHookValue = CollectionHooks | CollectionHooksLoader;
+import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, FileField, ImageField, ServerHooksConfig, SingletonHooks, SingletonHooksLoader, UploadHooks, UploadHooksLoader } from '../@types/index.js';
+type DocumentHookValue = CollectionHooks | CollectionHooksLoader | SingletonHooks | SingletonHooksLoader;
 type UploadHookValue = UploadHooks | UploadHooksLoader;
 type UploadField = ImageField | FileField;
 export type HookAttachmentOperation = {
     kind: 'collection';
     target: CollectionDefinition;
-    hooks: CollectionHookValue | undefined;
+    hooks: DocumentHookValue | undefined;
 } | {
     kind: 'upload';
     target: UploadField;

package/dist/config/attach-hooks.js

@@ -1,3 +1,4 @@
+import { assertHooksMatchDefinition } from '../@types/collection-types.js';
 import { formatDeclarationPath, walkFieldDeclarations } from '../paths/index.js';
 const registryCollectionHooks = new WeakMap();
 const registryUploadHooks = new WeakMap();
@@ -61,6 +62,8 @@ export function commitHookAttachment(operations) {
 }
 function planCollectionAttachment(collection, requested, operations) {
     const owned = registryCollectionHooks.get(collection);
+    assertInlineHookFamily(collection, collection.hooks);
+    assertInlineHookFamily(collection, requested);
     assertOwnershipIntact(`collection "${collection.path}"`, collection.hooks, owned);
     if (requested === undefined) {
         if (owned !== undefined) {
@@ -75,6 +78,11 @@ function planCollectionAttachment(collection, requested, operations) {
         operations.push({ kind: 'collection', target: collection, hooks: requested });
     }
 }
+function assertInlineHookFamily(definition, hooks) {
+    if (hooks !== undefined && typeof hooks !== 'function') {
+        assertHooksMatchDefinition(definition, hooks);
+    }
+}
 function planUploadAttachment(path, field, requested, operations) {
     const owned = registryUploadHooks.get(field);
     assertOwnershipIntact(`upload field "${path}"`, field.upload?.hooks, owned);

package/dist/config/attach-hooks.test.node.js

@@ -9,6 +9,14 @@ function collection(path = 'documents') {
         fields: [{ name: 'title', type: 'text' }],
     };
 }
+function singleton(path = 'site-settings') {
+    return {
+        singleton: true,
+        path,
+        label: 'Site settings',
+        fields: [{ name: 'title', type: 'text' }],
+    };
+}
 function nestedUploadCollection() {
     const nested = { name: 'asset', type: 'file', upload: {} };
     const arrayFile = { name: 'publicationFile', type: 'file', upload: {} };
@@ -37,6 +45,57 @@ function nestedUploadCollection() {
     };
 }
 describe('server hook attachment', () => {
+    it('rejects inline hooks from the wrong resource family at startup', () => {
+        const singletonDefinition = singleton();
+        singletonDefinition.hooks = { beforeCreate: () => { } };
+        expect(() => prepareHookAttachment({ collections: [singletonDefinition] })).toThrow(/singleton.*beforeCreate/i);
+        const collectionDefinition = collection();
+        const singletonHooks = { beforeSave: () => { } };
+        expect(() => prepareHookAttachment({
+            collections: [collectionDefinition],
+            hooks: { collections: { documents: singletonHooks } },
+        })).toThrow(/collection.*beforeSave/i);
+    });
+    it('accepts well-formed inline singleton hooks and resolves them unchanged', async () => {
+        const definition = singleton();
+        const hooks = {
+            beforeSave: vi.fn((_context) => { }),
+        };
+        definition.hooks = hooks;
+        expect(prepareHookAttachment({ collections: [definition] })).toEqual([]);
+        expect(await resolveHooks(definition)).toBe(hooks);
+    });
+    it('defers loader-family validation until first resolution', async () => {
+        const definition = singleton();
+        const loader = vi.fn(() => Promise.resolve({ beforeCreate: () => { } }));
+        definition.hooks = loader;
+        expect(() => prepareHookAttachment({ collections: [definition] })).not.toThrow();
+        await expect(resolveHooks(definition)).rejects.toThrow(/singleton.*beforeCreate/i);
+    });
+    it('resolves and caches a well-formed singleton hook loader', async () => {
+        const definition = singleton();
+        const hooks = {
+            beforeSave: vi.fn((_context) => { }),
+        };
+        const loader = vi.fn(() => Promise.resolve(hooks));
+        definition.hooks = loader;
+        expect(await resolveHooks(definition)).toBe(hooks);
+        expect(await resolveHooks(definition)).toBe(hooks);
+        expect(loader).toHaveBeenCalledOnce();
+    });
+    it('validates a reused loader against the current definition on every resolution', async () => {
+        const hooks = {
+            beforeSave: vi.fn((_context) => { }),
+        };
+        const loader = vi.fn(() => Promise.resolve(hooks));
+        const singletonDefinition = singleton();
+        singletonDefinition.hooks = loader;
+        const collectionDefinition = collection();
+        collectionDefinition.hooks = loader;
+        expect(await resolveHooks(singletonDefinition)).toBe(hooks);
+        await expect(resolveHooks(collectionDefinition)).rejects.toThrow(/collection.*beforeSave/i);
+        expect(loader).toHaveBeenCalledOnce();
+    });
     it('prepares without mutation, then attaches collection and canonical nested upload hooks', async () => {
         const { definition, nested, arrayFile, blockFile } = nestedUploadCollection();
         const collectionHooks = {};

package/dist/config/config-hooks.test.node.js

@@ -1,8 +1,12 @@
 import { afterEach, describe, expect, it } from 'vitest';
-import { defineAdminConfig, defineServerConfig, getCollectionDefinition } from './config.js';
+import { defineAdmin, defineSingletonAdmin } from '../@types/admin-types.js';
+import { defineCollection, defineSingleton } from '../@types/collection-types.js';
+import { defineAdminConfig, defineServerConfig, getCollectionAdminConfig, getCollectionDefinition, getSingletonAdminConfig, } from './config.js';
 const SERVER_CONFIG = Symbol.for('__byline_server_config__');
+const ADMIN_CONFIG = Symbol.for('__byline_admin_config__');
 const CLIENT_CONFIG = Symbol.for('__byline_client_config__');
 const previousServer = globalThis[SERVER_CONFIG];
+const previousAdmin = globalThis[ADMIN_CONFIG];
 const previousClient = globalThis[CLIENT_CONFIG];
 afterEach(() => {
     const globals = globalThis;
@@ -10,6 +14,10 @@ afterEach(() => {
         delete globals[SERVER_CONFIG];
     else
         globals[SERVER_CONFIG] = previousServer;
+    if (previousAdmin === undefined)
+        delete globals[ADMIN_CONFIG];
+    else
+        globals[ADMIN_CONFIG] = previousAdmin;
     if (previousClient === undefined)
         delete globals[CLIENT_CONFIG];
     else
@@ -53,3 +61,28 @@ describe('collection definition config preference', () => {
         expect(getCollectionDefinition('docs')?.hooks).toBe(hooks);
     });
 });
+describe('admin resource config lookup', () => {
+    it('returns only the admin config matching the requested resource kind', () => {
+        const pages = defineCollection({
+            path: 'pages',
+            labels: { singular: 'Page', plural: 'Pages' },
+            fields: [{ name: 'title', label: 'Title', type: 'text' }],
+        });
+        const settings = defineSingleton({
+            path: 'site-settings',
+            label: 'Site settings',
+            fields: [{ name: 'title', label: 'Title', type: 'text' }],
+        });
+        const pagesAdmin = defineAdmin(pages, {});
+        const settingsAdmin = defineSingletonAdmin(settings, {});
+        defineAdminConfig({
+            collections: [pages, settings],
+            admin: [pagesAdmin, settingsAdmin],
+            i18n,
+        });
+        expect(getCollectionAdminConfig(pages.path)).toBe(pagesAdmin);
+        expect(getCollectionAdminConfig(settings.path)).toBeNull();
+        expect(getSingletonAdminConfig(settings.path)).toBe(settingsAdmin);
+        expect(getSingletonAdminConfig(pages.path)).toBeNull();
+    });
+});

package/dist/config/config.d.ts

@@ -1,4 +1,4 @@
-import type { AdminConfig, CollectionAdminConfig, CollectionDefinition, ResolvedAdminConfig, ResolvedServerConfig, ServerConfig } from '../@types/index.js';
+import type { AdminConfig, CollectionAdminConfig, CollectionDefinition, ResolvedAdminConfig, ResolvedServerConfig, ServerConfig, SingletonAdminConfig } from '../@types/index.js';
 /**
  * Resolve a collection definition by `path`. Returns `null` either when
  * no config has been registered (e.g. unit tests, isolated tooling) or
@@ -12,6 +12,7 @@ import type { AdminConfig, CollectionAdminConfig, CollectionDefinition, Resolved
  */
 export declare const getCollectionDefinition: (path: string) => CollectionDefinition | null;
 export declare const getCollectionAdminConfig: (slug: string) => CollectionAdminConfig | null;
+export declare const getSingletonAdminConfig: (slug: string) => SingletonAdminConfig | null;
 export declare function defineAdminConfig(config: AdminConfig): ResolvedAdminConfig;
 export declare function defineServerConfig<TAdminStore = unknown>(config: ServerConfig<TAdminStore>): ResolvedServerConfig<TAdminStore>;
 /** Resolve and validate server config without replacing the registered singleton. */

package/dist/config/config.js

@@ -51,12 +51,20 @@ export const getCollectionDefinition = (path) => {
         return null;
     return config.collections.find((collection) => collection.path === path) ?? null;
 };
-export const getCollectionAdminConfig = (slug) => {
+const getAdminResourceConfig = (slug) => {
     const adminConfig = getAdminConfigInstance();
     if (adminConfig == null)
         return null;
     return adminConfig.admin?.find((admin) => admin.slug === slug) ?? null;
 };
+export const getCollectionAdminConfig = (slug) => {
+    const admin = getAdminResourceConfig(slug);
+    return admin?.singleton === true ? null : admin;
+};
+export const getSingletonAdminConfig = (slug) => {
+    const admin = getAdminResourceConfig(slug);
+    return admin?.singleton === true ? admin : null;
+};
 export function defineAdminConfig(config) {
     validateCollections(config.collections);
     validateAdminConfigs(config.admin, config.collections, config.collectionGroups);

package/dist/config/group-collections.d.ts

@@ -5,30 +5,31 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionAdminConfig, CollectionGroupDefinition } from '../@types/admin-types.js';
+import type { AdminResourceConfig, CollectionGroupDefinition } from '../@types/admin-types.js';
 import type { CollectionDefinition } from '../@types/collection-types.js';
 /**
  * One renderable section of the admin dashboard: a heading (or none) and the
- * collections beneath it.
+ * document resources beneath it. The public `collections` member name remains
+ * for backwards compatibility and may contain both resource kinds.
  */
-export interface CollectionGroupBucket {
+export interface CollectionGroupBucket<TDefinition extends CollectionDefinition = CollectionDefinition> {
     /** Registry key, or `null` for the leading ungrouped band. */
     name: string | null;
     /** Heading text, or `null` when the band renders without a heading. */
     label: string | null;
-    collections: CollectionDefinition[];
+    collections: TDefinition[];
 }
 /**
- * Bucket collections into ordered dashboard sections.
+ * Bucket collections and singletons into ordered dashboard sections.
  *
  * Rules:
  *  - The ungrouped band is emitted first, and omitted entirely when empty.
  *  - Declared groups follow in `collectionGroups` order.
  *  - A declared group with no members is skipped, so no heading ever appears
  *    above an empty section.
- *  - Collection declaration order is preserved within each bucket.
+ *  - Resource declaration order is preserved within each bucket.
  *  - An absent or empty registry yields a single ungrouped bucket holding every
- *    collection — the flat grid Byline rendered before groups existed.
+ *    resource — the flat grid Byline rendered before groups existed.
  *
  * This function is deliberately total: a `group` naming no declared entry is
  * treated as ungrouped rather than throwing. `validateCollectionGroups` rejects
@@ -37,9 +38,9 @@ export interface CollectionGroupBucket {
  * outcome.
  *
  * It takes no actor and knows nothing about abilities. Callers that need to
- * hide collections filter the `collections` argument first — see
+ * hide resources filter the `collections` argument first — see
  * `filterReadableCollections`. That ordering is what makes a group whose
  * members are all hidden disappear along with its heading: it arrives here with
  * no members and is skipped by the rule above.
  */
-export declare function groupCollectionsForAdmin(collections: readonly CollectionDefinition[], admin: readonly CollectionAdminConfig[] | undefined, collectionGroups: readonly CollectionGroupDefinition[] | undefined): CollectionGroupBucket[];
+export declare function groupCollectionsForAdmin<TDefinition extends CollectionDefinition>(collections: readonly TDefinition[], admin: readonly AdminResourceConfig[] | undefined, collectionGroups: readonly CollectionGroupDefinition[] | undefined): CollectionGroupBucket<TDefinition>[];

package/dist/config/group-collections.js

@@ -6,16 +6,16 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Bucket collections into ordered dashboard sections.
+ * Bucket collections and singletons into ordered dashboard sections.
  *
  * Rules:
  *  - The ungrouped band is emitted first, and omitted entirely when empty.
  *  - Declared groups follow in `collectionGroups` order.
  *  - A declared group with no members is skipped, so no heading ever appears
  *    above an empty section.
- *  - Collection declaration order is preserved within each bucket.
+ *  - Resource declaration order is preserved within each bucket.
  *  - An absent or empty registry yields a single ungrouped bucket holding every
- *    collection — the flat grid Byline rendered before groups existed.
+ *    resource — the flat grid Byline rendered before groups existed.
  *
  * This function is deliberately total: a `group` naming no declared entry is
  * treated as ungrouped rather than throwing. `validateCollectionGroups` rejects
@@ -24,7 +24,7 @@
  * outcome.
  *
  * It takes no actor and knows nothing about abilities. Callers that need to
- * hide collections filter the `collections` argument first — see
+ * hide resources filter the `collections` argument first — see
  * `filterReadableCollections`. That ordering is what makes a group whose
  * members are all hidden disappear along with its heading: it arrives here with
  * no members and is skipped by the rule above.

package/dist/config/group-collections.test.node.js

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { describe, expect, it } from 'vitest';
+import { defineSingleton, } from '../@types/index.js';
 import { groupCollectionsForAdmin } from './group-collections.js';
 const define = (path) => ({
     path,
@@ -17,6 +18,11 @@ const news = define('news');
 const images = define('images');
 const authors = define('authors');
 const categories = define('categories');
+const settings = defineSingleton({
+    path: 'site-settings',
+    label: 'Site settings',
+    fields: [{ name: 'title', label: 'Title', type: 'text' }],
+});
 const groups = [
     { name: 'media', label: 'Media' },
     { name: 'authorities', label: 'People & Organisations' },
@@ -64,6 +70,14 @@ describe('groupCollectionsForAdmin', () => {
         const result = groupCollectionsForAdmin([more, images], [...admin, { slug: 'videos', group: 'media' }], groups);
         expect(result[0]?.collections).toEqual([more, images]);
     });
+    it('groups singleton and multi-collection resources together in declaration order', () => {
+        const resourceAdmin = [
+            ...admin,
+            { singleton: true, slug: settings.path, group: 'media' },
+        ];
+        const result = groupCollectionsForAdmin([images, settings], resourceAdmin, groups);
+        expect(result[0]?.collections).toEqual([images, settings]);
+    });
     it('places a collection with no admin config in the ungrouped band', () => {
         const result = groupCollectionsForAdmin([pages, images], admin, groups);
         expect(result[0]).toEqual({ name: null, label: null, collections: [pages] });

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

@@ -5,14 +5,14 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { BlockAdminConfig, CollectionAdminConfig, CollectionDefinition, CollectionGroupDefinition } from '../@types/index.js';
+import type { AdminResourceConfig, BlockAdminConfig, CollectionDefinition, CollectionGroupDefinition } from '../@types/index.js';
 /**
  * Validate the dashboard collection-group registry and every reference to it.
  *
  * Enforced rules:
  *  1. Each `collectionGroups` entry has a non-blank `name` and `label`.
  *  2. No two entries share a `name`.
- *  3. Every `CollectionAdminConfig.group` names a declared entry. This single
+ *  3. Every admin resource's `group` names a declared entry. This single
  *     rule covers both a typographical error and the case where `group` was set
  *     but the registry was never declared.
  *
@@ -20,7 +20,7 @@ import type { BlockAdminConfig, CollectionAdminConfig, CollectionDefinition, Col
  * configuration validation runs at startup, before the logger and error
  * registry are necessarily wired up.
  */
-export declare function validateCollectionGroups(collectionGroups: readonly CollectionGroupDefinition[] | undefined, admins: readonly CollectionAdminConfig[] | undefined): void;
+export declare function validateCollectionGroups(collectionGroups: readonly CollectionGroupDefinition[] | undefined, admins: readonly AdminResourceConfig[] | undefined): void;
 /**
  * Validate every admin config in a configuration.
  *
@@ -53,7 +53,7 @@ export declare function validateCollectionGroups(collectionGroups: readonly Coll
  * validation runs at startup, before the logger and error registry are
  * necessarily wired up.
  */
-export declare function validateAdminConfigs(admins: readonly CollectionAdminConfig[] | undefined, collections: readonly CollectionDefinition[], collectionGroups?: readonly CollectionGroupDefinition[]): void;
+export declare function validateAdminConfigs(admins: readonly AdminResourceConfig[] | undefined, collections: readonly CollectionDefinition[], collectionGroups?: readonly CollectionGroupDefinition[]): void;
 /**
  * Validate every block admin config in a configuration.
  *

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

@@ -5,7 +5,21 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { isSingleton } from '../@types/collection-types.js';
 import { resolveDeclarationPath, walkFieldDeclarations, } from '../paths/index.js';
+function completeCollectionOnlyAdminKeys(keys) {
+    return keys;
+}
+/** Runtime counterpart to `SingletonAdminConfig`'s collection-only `never` members. */
+const COLLECTION_ONLY_ADMIN_KEYS = completeCollectionOnlyAdminKeys([
+    'columns',
+    'defaultSort',
+    'defaultColumns',
+    'itemView',
+    'itemViewSort',
+    'listView',
+    'listActions',
+]);
 /**
  * Resolve a `fields{}` override key against a field set.
  *
@@ -44,7 +58,7 @@ function validateFieldAdminKeys(keys, resolve, fail) {
  * Enforced rules:
  *  1. Each `collectionGroups` entry has a non-blank `name` and `label`.
  *  2. No two entries share a `name`.
- *  3. Every `CollectionAdminConfig.group` names a declared entry. This single
+ *  3. Every admin resource's `group` names a declared entry. This single
  *     rule covers both a typographical error and the case where `group` was set
  *     but the registry was never declared.
  *
@@ -58,7 +72,7 @@ export function validateCollectionGroups(collectionGroups, admins) {
         const name = typeof group.name === 'string' ? group.name.trim() : '';
         const label = typeof group.label === 'string' ? group.label.trim() : '';
         if (name === '') {
-            throw new Error('A `collectionGroups` entry has a blank `name`. Each entry needs a non-empty key for `CollectionAdminConfig.group` to reference.');
+            throw new Error('A `collectionGroups` entry has a blank `name`. Each entry needs a non-empty key for an admin resource `group` to reference.');
         }
         if (label === '') {
             throw new Error(`Collection group "${name}" has a blank \`label\`. The label is the heading rendered above the group on the dashboard.`);
@@ -76,7 +90,7 @@ export function validateCollectionGroups(collectionGroups, admins) {
         const known = declared.size === 0
             ? '`collectionGroups` was not declared, or is empty'
             : `declared groups: ${[...declared].map((name) => `"${name}"`).join(', ')}`;
-        throw new Error(`Collection "${admin.slug}": \`group: '${admin.group}'\` does not name a declared collection group (${known}). Add it to \`AdminConfig.collectionGroups\`, or remove the \`group\` property.`);
+        throw new Error(`Admin resource "${admin.slug}": \`group: '${admin.group}'\` does not name a declared collection group (${known}). Add it to \`AdminConfig.collectionGroups\`, or remove the \`group\` property.`);
     }
 }
 /**
@@ -198,12 +212,29 @@ function validateOne(admin, collectionsByPath) {
     // Rule 1 — slug pairing.
     const collection = collectionsByPath.get(admin.slug);
     if (collection == null) {
+        if (admin.singleton === true) {
+            throw new Error(`Singleton admin config "${admin.slug}" has no matching singleton definition (no singleton with \`path: '${admin.slug}'\` was registered).`);
+        }
         throw new Error(`Admin config "${admin.slug}" has no matching collection (no collection with \`path: '${admin.slug}'\` was registered).`);
     }
+    if (admin.singleton === true && !isSingleton(collection)) {
+        throw new Error(`Singleton admin config "${admin.slug}" targets a collection definition. Register it with \`defineAdmin\`, or point it at a singleton definition.`);
+    }
+    if (admin.singleton !== true && isSingleton(collection)) {
+        throw new Error(`Collection admin config "${admin.slug}" targets a singleton definition. Register it with \`defineSingletonAdmin\`, or point it at a multi-collection definition.`);
+    }
     const slug = admin.slug;
     const fail = (msg) => {
-        throw new Error(`Collection "${slug}": ${msg}`);
+        const resource = admin.singleton === true ? 'Singleton' : 'Collection';
+        throw new Error(`${resource} "${slug}": ${msg}`);
     };
+    if (admin.singleton === true) {
+        for (const key of COLLECTION_ONLY_ADMIN_KEYS) {
+            if (Object.hasOwn(admin, key)) {
+                fail(`\`${key}\` is not allowed on a singleton admin config.`);
+            }
+        }
+    }
     // Top-level schema field names — the population subject to placement
     // bookkeeping. Fields nested inside group/array/blocks are rendered by
     // their parent widget and are not addressable from layout.
@@ -221,7 +252,7 @@ function validateOne(admin, collectionsByPath) {
             return;
         const { field, direction } = spec;
         const documentColumns = new Set(['createdAt', 'updatedAt', 'path']);
-        if (collection.orderable === true) {
+        if (!isSingleton(collection) && collection.orderable === true) {
             fail(`${optionName} is not allowed on an orderable collection — manual ordering owns the sort (order_key asc).`);
         }
         if (typeof field !== 'string' || field.length === 0) {
@@ -234,8 +265,10 @@ function validateOne(admin, collectionsByPath) {
             fail(`${optionName}.direction must be 'asc' or 'desc' (got "${String(direction)}").`);
         }
     };
-    validateSortSpec(admin.defaultSort, 'defaultSort');
-    validateSortSpec(admin.itemViewSort, 'itemViewSort');
+    if (admin.singleton !== true) {
+        validateSortSpec(admin.defaultSort, 'defaultSort');
+        validateSortSpec(admin.itemViewSort, 'itemViewSort');
+    }
     // Build primitive lookup tables.
     const tabSets = admin.tabSets ?? [];
     const rows = admin.rows ?? [];

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

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { describe, expect, it } from 'vitest';
+import { defineSingleton, defineSingletonAdmin, } from '../@types/index.js';
 import { validateAdminConfigs, validateBlockAdminConfigs } from './validate-admin-configs.js';
 const collection = {
     path: 'news',
@@ -33,6 +34,19 @@ const baseAdmin = {
     rows: [{ name: 'titles', fields: ['text1', 'text2'] }],
     layout: { main: ['main'] },
 };
+const singleton = defineSingleton({
+    path: 'site-settings',
+    label: 'Site settings',
+    fields: [
+        { name: 'title', label: 'Title', type: 'text' },
+        {
+            name: 'seo',
+            label: 'SEO',
+            type: 'group',
+            fields: [{ name: 'description', label: 'Description', type: 'textArea' }],
+        },
+    ],
+});
 describe('validateAdminConfigs', () => {
     it('accepts a valid admin config (baseline)', () => {
         expect(() => validateAdminConfigs([baseAdmin], [collection])).not.toThrow();
@@ -40,6 +54,36 @@ describe('validateAdminConfigs', () => {
     it('is a no-op when admins is undefined', () => {
         expect(() => validateAdminConfigs(undefined, [collection])).not.toThrow();
     });
+    it('accepts a singleton admin config and dotted field override path', () => {
+        const admin = defineSingletonAdmin(singleton, {
+            fields: { 'seo.description': {} },
+            layout: { main: ['title', 'seo'] },
+        });
+        expect(() => validateAdminConfigs([admin], [collection, singleton])).not.toThrow();
+    });
+    it('rejects an unknown singleton field override path at startup', () => {
+        const admin = defineSingletonAdmin(singleton, { fields: { 'seo.missing': {} } });
+        expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/does not resolve to a field declaration/);
+    });
+    it('rejects list-only singleton options from untyped callers', () => {
+        const admin = {
+            ...defineSingletonAdmin(singleton, {}),
+            columns: [{ fieldName: 'title', label: 'Title' }],
+        };
+        expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/columns.*not allowed on a singleton admin config/);
+    });
+    it('rejects a singleton admin config targeting a multi-collection', () => {
+        const admin = { ...defineSingletonAdmin(singleton, {}), slug: collection.path };
+        expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/targets a collection definition/);
+    });
+    it('rejects a singleton admin config with no matching definition', () => {
+        const admin = { ...defineSingletonAdmin(singleton, {}), slug: 'missing-settings' };
+        expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/no matching singleton definition/);
+    });
+    it('rejects a multi-collection admin config targeting a singleton', () => {
+        const admin = { slug: singleton.path };
+        expect(() => validateAdminConfigs([admin], [collection, singleton])).toThrow(/targets a singleton definition/);
+    });
     // Rule 1 — slug pairing.
     it('rejects an admin config whose slug has no matching collection', () => {
         const orphan = { slug: 'nonexistent', layout: { main: [] } };

package/dist/config/validate-collections.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { isSingleton } from '../@types/collection-types.js';
 import { formatDeclarationPath, walkFieldDeclarations } from '../paths/index.js';
 import { fieldTypeToStore } from '../storage/field-store-map.js';
 /**
@@ -48,6 +49,23 @@ const USE_AS_PATH_SOURCE_TYPES = new Set([
     'integer',
     'counter',
 ]);
+function completeCollectionOnlyOptions(keys) {
+    return keys;
+}
+/** Runtime counterpart to the singleton definition's collection-only `never` members. */
+const COLLECTION_ONLY_OPTIONS = completeCollectionOnlyOptions([
+    'labels',
+    'orderable',
+    'tree',
+    'useAsPath',
+    'useAsTitle',
+    'search',
+    'listSearch',
+    'advertiseLocales',
+    'showStats',
+    'linksInEditor',
+    'buildDocumentPath',
+]);
 /**
  * True when any field in the tree (at any nesting depth) is `localized`.
  * Used to gate `advertiseLocales` — advertising content locales is only
@@ -239,13 +257,38 @@ function validateVirtualFields(collection) {
  * necessarily wired up.
  */
 export function validateCollections(collections) {
+    const definitionsByPath = new Map();
+    for (const collection of collections) {
+        if (definitionsByPath.has(collection.path)) {
+            throw new Error(`Two definitions are registered on path "${collection.path}". Collections and singletons share one path namespace, so a collection and a singleton cannot both be called "${collection.path}".`);
+        }
+        definitionsByPath.set(collection.path, collection);
+    }
     for (const collection of collections) {
+        if (isSingleton(collection)) {
+            for (const option of COLLECTION_ONLY_OPTIONS) {
+                if (collection[option] !== undefined) {
+                    throw new Error(`Singleton "${collection.path}" sets \`${option}\`, which is a multi-document collection option. A singleton holds at most one document, so there is no list to sort, search, or paginate and no public slug. Remove \`${option}\`.`);
+                }
+            }
+            if (typeof collection.label !== 'string') {
+                throw new Error(`Singleton "${collection.path}" must declare a \`label\`. Singletons have no plural form, so they use \`label\` rather than \`labels\`.`);
+            }
+        }
         walkFields(collection.fields, (field) => {
             if ('name' in field && RESERVED_FIELD_NAMES.has(field.name)) {
                 const hint = RESERVED_FIELD_HINTS[field.name] ?? '';
                 throw new Error(`Collection "${collection.path}" declares a field named "${field.name}", which is a reserved system attribute.${hint ? ` ${hint}` : ''}`);
             }
         });
+        walkFieldsWithPath(collection.fields, (field, fieldPath) => {
+            if (field.type !== 'relation')
+                return;
+            const target = definitionsByPath.get(field.targetCollection);
+            if (target == null || !isSingleton(target))
+                return;
+            throw new Error(`Field "${fieldPath}" on "${collection.path}" targets "${target.path}", which is a singleton. A singleton holds at most one document and is not a relation target in this release — reference its values directly instead.`);
+        });
         if (collection.useAsPath != null) {
             const source = collection.fields.find((f) => 'name' in f && f.name === collection.useAsPath);
             if (source == null) {