@byline/core 4.1.0 → 4.2.0

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

@@ -5,8 +5,8 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionDefinition, WorkflowStatus } from './collection-types.js';
-import type { FieldComponentSlots, RichTextEditorComponent } from './field-types.js';
+import type { BlockFieldData, CollectionDefinition, WorkflowStatus } from './collection-types.js';
+import type { Block, FieldComponentSlots, RichTextEditorComponent } from './field-types.js';
 /**
  * Props passed to a custom list-view component registered via
  * `CollectionAdminConfig.listView`.
@@ -229,6 +229,25 @@ export interface CollectionAdminConfig<T = any> {
      * the field directly, so the deprecated `picker` alias keeps working.
      */
     itemView?: ColumnDefinition<T>[];
+    /**
+     * Sort applied when this collection's documents are listed through the
+     * **item view** surfaces (currently the relation picker modal) —
+     * independent of the main list view's {@link defaultSort}. A media
+     * library, for example, can keep its list view newest-first while the
+     * picker orders by title:
+     *
+     * ```ts
+     * itemViewSort: { field: 'title' },
+     * ```
+     *
+     * Same shape and boot validation as `defaultSort`: `field` must be a
+     * top-level schema field or a document column (`createdAt` / `updatedAt` /
+     * `path`), `direction` defaults to `'asc'`, and the option is rejected on
+     * `orderable: true` collections (manual ordering owns their order
+     * everywhere). Falls back to `defaultSort` → `created_at desc` when
+     * omitted.
+     */
+    itemViewSort?: ListDefaultSort<T>;
     /**
      * @deprecated Renamed to {@link itemView}. Kept as a backwards-compatible
      * alias — `itemView` wins when both are present. Read both via
@@ -374,3 +393,56 @@ export interface ListActionComponentProps {
  * Sets `slug` from the schema's `path`.
  */
 export declare function defineAdmin<T = any>(schema: CollectionDefinition, config: Omit<CollectionAdminConfig<T>, 'slug'>): CollectionAdminConfig<T>;
+/**
+ * Admin UI configuration for a block — the block-scoped analogue of
+ * `CollectionAdminConfig`, carrying **rendering overrides only**.
+ *
+ * Linked to a `Block` by `blockType` matching the block's `blockType`, and
+ * registered site-wide on `ClientConfig.blockAdmin`. Because blocks are
+ * cross-collection units (the same `defineBlock()` object is typically shared
+ * by several collections, and codegen dedupes their contracts structurally),
+ * a block's admin config applies wherever the block renders. If one
+ * 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.
+ */
+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
+     * `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.
+ *
+ * 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
+ * references (editor overrides, slot components). Keep them in separate
+ * files — the admin file imports the schema, never the reverse.
+ *
+ * @example
+ * ```ts
+ * // quote-block.admin.ts (admin-side — may import React)
+ * import { defineBlockAdmin } from '@byline/core'
+ * import { QuoteBlock } from './quote-block.js'
+ *
+ * export const QuoteBlockAdmin = defineBlockAdmin(QuoteBlock, {
+ *   fields: {
+ *     quoteText: { editor: PlainLexicalEditor },
+ *   },
+ * })
+ * ```
+ */
+export declare function defineBlockAdmin<B extends Block>(block: B, config: {
+    fields?: Partial<Record<Extract<keyof BlockFieldData<B>, string>, FieldAdminConfig>>;
+}): BlockAdminConfig;

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

@@ -15,3 +15,32 @@ export function defineAdmin(schema, config) {
         ...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.
+ *
+ * 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
+ * references (editor overrides, slot components). Keep them in separate
+ * files — the admin file imports the schema, never the reverse.
+ *
+ * @example
+ * ```ts
+ * // quote-block.admin.ts (admin-side — may import React)
+ * import { defineBlockAdmin } from '@byline/core'
+ * import { QuoteBlock } from './quote-block.js'
+ *
+ * export const QuoteBlockAdmin = defineBlockAdmin(QuoteBlock, {
+ *   fields: {
+ *     quoteText: { editor: PlainLexicalEditor },
+ *   },
+ * })
+ * ```
+ */
+export function defineBlockAdmin(block, config) {
+    return {
+        blockType: block.blockType,
+        fields: config.fields,
+    };
+}

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

@@ -82,6 +82,28 @@ export interface UploadConfig {
      * Omit to allow all types.
      */
     mimeTypes?: string[];
+    /**
+     * Declarative storage location (key scope) for this field's uploads,
+     * replacing the default `<collectionPath>/` scope. Nested segments are
+     * allowed — e.g. `'publications/covers'`, `'news/attachments'`. Providers
+     * keep their own entropy and filename sanitisation beneath it
+     * (`<location>/<filename>-<suffix>.<ext>`), so collision behaviour is unchanged.
+     *
+     * Precedence: a `beforeStore` hook returning `{ storagePath }` (written
+     * verbatim) → `location` → the collection-path default. A `{ filename }`
+     * hook override keeps composing with `location`. Use `location` for
+     * static scoping; hooks remain the tool for *dynamic* keys (per-document
+     * serials, tenant prefixes).
+     *
+     * Boot-validated: POSIX-style forward slashes; segments of
+     * `A–Z a–z 0–9 . _ -`; no leading/trailing/duplicate slashes; no `.` or
+     * `..` segments.
+     *
+     * Note: changing `location` later does not move previously stored objects
+     * (same as renaming via hooks) — existing documents keep their recorded
+     * `storagePath`.
+     */
+    location?: string;
     /** Maximum file size in bytes. Omit for no limit. */
     maxFileSize?: number;
     /**
@@ -546,7 +568,7 @@ export interface DeleteContext {
 }
 /**
  * Context passed to the `afterTreeChange` hook — the structural-change
- * invalidation event for `tree: true` collections (docs/04-collections/03-document-trees.md).
+ * invalidation event for `tree: true` collections (docs/04-collections/04-document-trees.md).
  *
  * Tree mutations are document-grain and **unversioned**, so the normal
  * version-write invalidation (`afterCreate` / `afterUpdate` / `afterStatusChange`)
@@ -594,11 +616,11 @@ export interface TreeChangeContext {
  *     override is threaded into `storage.upload(...)`, so generated
  *     image variants automatically inherit the new prefix. The storage
  *     provider still derives the final key (e.g. local storage prefixes
- *     `<collection>/<uuid>-` for collision avoidance).
+ *     `<collection>/<basename>-<suffix>.<ext>` for collision avoidance).
  *   - Take **full control of the storage key** by returning
  *     `{ storagePath }` — a fully-qualified, POSIX-style path (no
  *     leading slash) that is threaded into `storage.upload(...)` as
- *     `targetStoragePath` and written **verbatim**: no UUID prefix, no
+ *     `targetStoragePath` and written **verbatim**: no entropy suffix, no
  *     collection namespace, no provider rewriting. The hook assumes
  *     responsibility for sanitisation and collision avoidance (see
  *     `UploadFileOptions.targetStoragePath`). Generated image variants
@@ -657,7 +679,7 @@ export interface BeforeStoreContext {
  *                           provider still derives the final key.
  *   - `{ storagePath }`   → take full control of the storage key: written
  *                           verbatim via `UploadFileOptions.targetStoragePath`
- *                           (no UUID prefix / provider rewriting). May be
+ *                           (no entropy suffix / provider rewriting). May be
  *                           combined with `filename`; without it, the stored
  *                           filename defaults to the path's basename.
  *   - `{ error }`         → reject the upload; surfaces as
@@ -787,7 +809,7 @@ export declare function resolveUploadHooks(hooks: UploadHooks | UploadHooksLoade
  * by populate. A hook that performs its own reads should thread this
  * context back in via `client.collection(...).findById(id, { _readContext:
  * readContext })` so the visited set and read budget are preserved —
- * essential to foreclose the A→B→A loop (see `docs/04-collections/02-relationships.md`).
+ * essential to foreclose the A→B→A loop (see `docs/04-collections/03-relationships.md`).
  */
 export interface AfterReadContext {
     /** The raw reconstructed document. Mutate in place — changes persist. */
@@ -906,7 +928,7 @@ export interface CollectionHooks {
      * (`removeFromTree`), or the promote-children-to-root that accompanies a
      * delete. Tree writes mint no document version, so this is the only
      * invalidation signal for them. Fires once per write with the full affected
-     * set ({@link TreeChangeContext}). See docs/04-collections/03-document-trees.md.
+     * set ({@link TreeChangeContext}). See docs/04-collections/04-document-trees.md.
      */
     afterTreeChange?: CollectionHookSlot<TreeChangeContext>;
     /**
@@ -1200,7 +1222,7 @@ export interface CollectionDefinition {
      * touch no user fields. Do **not** also declare a `parent` relation field; the
      * tree owns structure (a topic that genuinely belongs in two places is a
      * cross-link relation field, never a second tree edge). See
-     * docs/04-collections/03-document-trees.md.
+     * docs/04-collections/04-document-trees.md.
      */
     tree?: boolean;
     /**

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

@@ -649,7 +649,7 @@ export interface IDocumentCommands {
      * **before** (its right neighbour). Either may be null — `{}` appends as the
      * only/last child, `beforeDocumentId` alone appends after it, `afterDocumentId`
      * alone prepends before it. Both are resolved within the *target* parent
-     * group. See docs/04-collections/03-document-trees.md.
+     * group. See docs/04-collections/04-document-trees.md.
      */
     placeTreeNode(params: {
         collectionId: string;
@@ -664,7 +664,7 @@ export interface IDocumentCommands {
      * Remove a document's edge row, returning it to the *unplaced* state (in the
      * collection, but not in the tree). Distinct from document deletion — the
      * document and its content are untouched. No-op when the node is already
-     * unplaced. See docs/04-collections/03-document-trees.md.
+     * unplaced. See docs/04-collections/04-document-trees.md.
      */
     removeFromTree(params: {
         collectionId: string;
@@ -774,7 +774,7 @@ export interface IDocumentQueries {
      *
      * Source-locale only: this resolves the single canonical slug, which is the
      * only path row a document has today. When per-locale paths land (see
-     * docs/04-collections/04-document-paths.md → "Phase — per-locale paths"), the write-side hook
+     * docs/04-collections/05-document-paths.md → "Phase — per-locale paths"), the write-side hook
      * contexts that consume this must be enriched to carry the locale each path
      * was derived under (or the full `locale → path` set) — a single canonical
      * `path` is no longer sufficient for per-localised-URL cache/CDN purges.
@@ -1009,7 +1009,7 @@ export interface IDocumentQueries {
      * parent, increasing toward the root). Empty for a root or unplaced node.
      *
      * Backs breadcrumbs and the read-time hierarchical-URL canonicalization
-     * (docs/04-collections/03-document-trees.md). Depth-bounded as a backstop against pathological
+     * (docs/04-collections/04-document-trees.md). Depth-bounded as a backstop against pathological
      * key state even though the write-path cycle guard prevents true cycles.
      *
      * **Status-at-edge.** `readMode: 'published'` joins
@@ -1036,7 +1036,7 @@ export interface IDocumentQueries {
      * `order_key`. `parentDocumentId: null` returns the collection's root nodes.
      * Scoped to `collectionId` so root reads (which have no parent to scope by)
      * stay within the collection. One level only — the recursive subtree read is
-     * a separate query. See docs/04-collections/03-document-trees.md.
+     * a separate query. See docs/04-collections/04-document-trees.md.
      */
     getTreeChildren(params: {
         collectionId: string;
@@ -1047,7 +1047,7 @@ export interface IDocumentQueries {
     }>>;
     /**
      * Resolve a single node's placement state in the tree, distinguishing the
-     * three tri-states (docs/04-collections/03-document-trees.md → "Node placement"):
+     * three tri-states (docs/04-collections/04-document-trees.md → "Node placement"):
      *
      *   - **Unplaced** (no edge row) → `{ placed: false, parentDocumentId: null }`
      *   - **Root** (edge row, null parent) → `{ placed: true,  parentDocumentId: null }`
@@ -1084,7 +1084,7 @@ export interface IDocumentQueries {
      * `byline_current_published_documents` and drops any node without a current
      * published version; because the walk only recurses through *included*
      * nodes, an unpublished node's entire subtree is omitted — the spine is
-     * broken and descendants are not promoted (see docs/04-collections/03-document-trees.md).
+     * broken and descendants are not promoted (see docs/04-collections/04-document-trees.md).
      * `readMode: 'any'` (the default) includes every current, non-deleted node.
      * Optional `filters` enforce `beforeRead` at every edge with the same
      * no-promotion semantics. Depth-bounded by `maxDepth` as a backstop.

package/dist/@types/field-data-types.d.ts

@@ -44,6 +44,7 @@ type BaseFieldDataTypes = {
     richText: JsonValue;
     select: never;
     textArea: string;
+    code: string;
     text: string;
     time: string;
     relation: RelatedDocumentValue;

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

@@ -334,6 +334,41 @@ export interface TextAreaField extends LocalizableField {
         rules?: ValidationRule[];
     };
 }
+/**
+ * A dedicated source-code field. Stores a plain string (text store — no
+ * migration relative to `text` / `textArea`); the admin renders a
+ * lazily-loaded CodeMirror editor with syntax highlighting.
+ */
+export interface CodeField extends LocalizableField {
+    type: 'code';
+    defaultValue?: DefaultValue<string>;
+    /**
+     * Default syntax-highlight language for the admin editor (e.g.
+     * `'typescript'`, `'json'`, `'markdown'`). Unknown or omitted values render
+     * as plain text. Presentation-only — never persisted with the value.
+     */
+    language?: string;
+    /**
+     * Name of a SIBLING field (same group/block level) whose string value
+     * drives the editor's highlight language at runtime — typically a `select`
+     * of languages next to the code field. Takes precedence over `language`
+     * when the sibling has a value. Presentation-only.
+     *
+     * @example
+     * ```ts
+     * fields: [
+     *   { name: 'language', type: 'select', options: [ ... ] },
+     *   { name: 'code', type: 'code', languageField: 'language' },
+     * ]
+     * ```
+     */
+    languageField?: string;
+    validation?: {
+        minLength?: number;
+        maxLength?: number;
+        rules?: ValidationRule[];
+    };
+}
 export interface CheckboxField extends NonlocalizableField {
     type: 'checkbox';
     defaultValue?: DefaultValue<boolean>;
@@ -539,7 +574,7 @@ export interface ImageField extends NonlocalizableField {
     upload?: UploadConfig;
 }
 export type StructureField = GroupField | ArrayField | BlocksField;
-export type ValueField = TextField | TextAreaField | CheckboxField | BooleanField | SelectField | RichTextField | TimeField | DateField | DateTimeField | FloatField | IntegerField | DecimalField | CounterField | JsonField | ObjectField | RelationField | FileField | ImageField;
+export type ValueField = TextField | TextAreaField | CodeField | CheckboxField | BooleanField | SelectField | RichTextField | TimeField | DateField | DateTimeField | FloatField | IntegerField | DecimalField | CounterField | JsonField | ObjectField | RelationField | FileField | ImageField;
 export type Field = StructureField | ValueField;
 export type FieldSet = readonly Field[];
 export type ValueFieldType = ValueField['type'];

package/dist/@types/site-config.d.ts

@@ -7,7 +7,8 @@
  */
 import type { SessionProvider } from '@byline/auth';
 import type { SlugifierFn } from '../utils/slugify.js';
-import type { CollectionAdminConfig } from './admin-types.js';
+import type { FilenameSlugifierFn } from '../utils/slugify-filename.js';
+import type { BlockAdminConfig, CollectionAdminConfig } from './admin-types.js';
 import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, UploadHooks, UploadHooksLoader } from './collection-types.js';
 import type { IDbAdapter } from './db-types.js';
 import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn, RichTextToTextFn } from './field-types.js';
@@ -147,6 +148,15 @@ export type TranslationBundleShape = Readonly<{
 export interface ClientConfig extends BaseConfig {
     /** Admin UI configuration for collections (client-side only). */
     admin?: CollectionAdminConfig[];
+    /**
+     * Admin UI configuration for blocks, keyed by `blockType` — the block-scoped
+     * analogue of `admin`. Because blocks are shared across collections, an
+     * entry applies wherever its block renders (any collection, any nesting).
+     * Boot-validated against the blocks declared in `collections`.
+     *
+     * @see BlockAdminConfig
+     */
+    blockAdmin?: BlockAdminConfig[];
     /**
      * Installation-wide slugifier — the **client-side** copy, used by the
      * admin path-widget to render the live `path` preview (create-mode
@@ -274,6 +284,23 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      * `defineClientConfig`. See {@link ClientConfig.slugifier}.
      */
     slugifier?: SlugifierFn;
+    /**
+     * Installation-wide upload defaults.
+     *
+     * `filenameSlugifier` — the filename parallel of {@link slugifier}: applied
+     * to every uploaded file's **base name** (extension split off, lowercased,
+     * and reattached by the framework) before the `beforeStore` hook chain and
+     * storage-key composition. Falls back to the default `slugifyFilename`
+     * from `@byline/core` when not set. Server-only — filenames are derived
+     * exclusively at write time, so no client copy is needed.
+     *
+     * The stored key's basename becomes
+     * `<slugified-base>-<6-char suffix>.<ext>` (see the storage providers), so
+     * this function decides the human-readable half of every stored filename.
+     */
+    uploads?: {
+        filenameSlugifier?: FilenameSlugifierFn;
+    };
     /**
      * Session provider for admin authentication. Optional in Phase 3 —
      * installations without a provider configured simply can't sign in

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

@@ -38,10 +38,23 @@ export interface UploadFileOptions {
      * Providers may use this to namespace storage paths.
      */
     collection?: string;
+    /**
+     * Declarative storage-key scope replacing the `collection` default —
+     * threaded from the field's `UploadConfig.location` (e.g.
+     * `'news/attachments'`, nested segments allowed). Providers use it exactly
+     * where they would have used `collection`, keeping their own entropy and
+     * filename sanitisation (unlike `targetStoragePath`, which is written
+     * verbatim and bypasses the collision guard). Ignored when
+     * `targetStoragePath` is set.
+     *
+     * Always POSIX-style (forward slashes), no leading/trailing slash —
+     * boot-validated on the schema side before it reaches providers.
+     */
+    location?: string;
     /**
      * Explicit, fully-qualified storage path / object key the provider must
      * write to verbatim. When set, providers MUST place the file at exactly
-     * this path — no UUID prefix, year/month rewrite, or `pathPrefix` injection.
+     * this path — no entropy suffix, year/month rewrite, or `pathPrefix` injection.
      *
      * Used by the image-variant pipeline (`generateImageVariants`) to write
      * sibling files alongside an already-stored original (e.g. so the

package/dist/codegen/fixtures/all-fields.d.ts

@@ -15,6 +15,11 @@ export declare const QuoteBlock: {
             readonly label: "Quoted";
             readonly value: "author's";
         }];
+    }, {
+        readonly name: "snippet";
+        readonly type: "code";
+        readonly language: "typescript";
+        readonly optional: true;
     }];
 };
 export declare const MediaBlock: {
@@ -67,6 +72,10 @@ export declare const AllFieldsCollection: {
     }, {
         readonly name: "textArea";
         readonly type: "textArea";
+    }, {
+        readonly name: "code";
+        readonly type: "code";
+        readonly language: "json";
     }, {
         readonly name: "boolean";
         readonly type: "boolean";
@@ -159,6 +168,11 @@ export declare const AllFieldsCollection: {
                     readonly label: "Quoted";
                     readonly value: "author's";
                 }];
+            }, {
+                readonly name: "snippet";
+                readonly type: "code";
+                readonly language: "typescript";
+                readonly optional: true;
             }];
         }, {
             readonly blockType: "media";
@@ -223,6 +237,10 @@ export declare const AllFieldsCollections: readonly [{
     }, {
         readonly name: "textArea";
         readonly type: "textArea";
+    }, {
+        readonly name: "code";
+        readonly type: "code";
+        readonly language: "json";
     }, {
         readonly name: "boolean";
         readonly type: "boolean";
@@ -315,6 +333,11 @@ export declare const AllFieldsCollections: readonly [{
                     readonly label: "Quoted";
                     readonly value: "author's";
                 }];
+            }, {
+                readonly name: "snippet";
+                readonly type: "code";
+                readonly language: "typescript";
+                readonly optional: true;
             }];
         }, {
             readonly blockType: "media";

package/dist/codegen/fixtures/all-fields.expected.d.ts

@@ -18,6 +18,7 @@ export type QuoteBlockData = {
     _type: "quote'block";
     quotation: string;
     "tone'choice"?: 'calm' | "author's" | undefined;
+    snippet?: string | undefined;
 };
 export type QuoteBlockDataAllLocales = {
     _id: string;
@@ -26,6 +27,7 @@ export type QuoteBlockDataAllLocales = {
         [locale: string]: string;
     };
     "tone'choice"?: 'calm' | "author's" | undefined;
+    snippet?: string | undefined;
 };
 export type AllFieldsFields = {
     integer: number;
@@ -38,6 +40,7 @@ export type AllFieldsFields = {
     text: string;
     localizedText: string;
     textArea: string;
+    code: string;
     boolean: boolean;
     checkbox: boolean;
     select: 'first' | "second's";
@@ -74,6 +77,7 @@ export type AllFieldsFieldsAllLocales = {
         [locale: string]: string;
     };
     textArea: string;
+    code: string;
     boolean: boolean;
     checkbox: boolean;
     select: 'first' | "second's";

package/dist/codegen/fixtures/all-fields.js

@@ -12,6 +12,7 @@ export const QuoteBlock = defineBlock({
                 { label: 'Quoted', value: "author's" },
             ],
         },
+        { name: 'snippet', type: 'code', language: 'typescript', optional: true },
     ],
 });
 export const MediaBlock = defineBlock({
@@ -35,6 +36,7 @@ export const AllFieldsCollection = defineCollection({
         { name: 'text', type: 'text' },
         { name: 'localizedText', type: 'text', localized: true },
         { name: 'textArea', type: 'textArea' },
+        { name: 'code', type: 'code', language: 'json' },
         { name: 'boolean', type: 'boolean' },
         { name: 'checkbox', type: 'checkbox' },
         {

package/dist/codegen/index.js

@@ -198,6 +198,7 @@ function analyze(collections) {
                 break;
             case 'boolean':
             case 'checkbox':
+            case 'code':
             case 'counter':
             case 'date':
             case 'datetime':
@@ -341,6 +342,7 @@ function emitBody(analysis) {
             case 'datetime':
                 value = ['Date'];
                 break;
+            case 'code':
             case 'decimal':
             case 'text':
             case 'textArea':

package/dist/config/config.js

@@ -1,6 +1,6 @@
 import { commitHookAttachment, prepareHookAttachment, } from './attach-hooks.js';
 import { resolveRoutes } from './routes.js';
-import { validateAdminConfigs } from './validate-admin-configs.js';
+import { validateAdminConfigs, validateBlockAdminConfigs } from './validate-admin-configs.js';
 import { validateCollections } from './validate-collections.js';
 // ---------------------------------------------------------------------------
 // Global config storage
@@ -71,6 +71,7 @@ export const resolveItemViewColumns = (config) => config?.itemView ?? config?.pi
 export function defineClientConfig(config) {
     validateCollections(config.collections);
     validateAdminConfigs(config.admin, config.collections);
+    validateBlockAdminConfigs(config.blockAdmin, config.collections);
     const resolved = { ...config, routes: resolveRoutes(config.routes) };
     setClientConfigInstance(resolved);
     return resolved;

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

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { CollectionAdminConfig, CollectionDefinition } from '../@types/index.js';
+import type { BlockAdminConfig, CollectionAdminConfig, CollectionDefinition } from '../@types/index.js';
 /**
  * Validate every admin config in a configuration.
  *
@@ -35,3 +35,19 @@ import type { CollectionAdminConfig, CollectionDefinition } from '../@types/inde
  * necessarily wired up.
  */
 export declare function validateAdminConfigs(admins: readonly CollectionAdminConfig[] | undefined, collections: readonly CollectionDefinition[]): void;
+/**
+ * Validate every block admin config in a configuration.
+ *
+ * Enforced rules (per `ClientConfig.blockAdmin` entry):
+ *  1. Block pairing — `blockType` matches a block declared on at least one
+ *     `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).
+ *
+ * Throws a plain `Error` for the same reason `validateAdminConfigs` does —
+ * this runs at startup, before the logger is necessarily wired up.
+ */
+export declare function validateBlockAdminConfigs(blockAdmins: readonly BlockAdminConfig[] | undefined, collections: readonly CollectionDefinition[]): void;