@byline/core 4.0.0 → 4.2.0

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;

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

@@ -44,6 +44,75 @@ export function validateAdminConfigs(admins, collections) {
         validateOne(admin, collectionsByPath);
     }
 }
+/**
+ * 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 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);
+            }
+        }
+    };
+    for (const collection of collections) {
+        walkFields(collection.fields);
+    }
+    const seen = new Set();
+    for (const entry of blockAdmins) {
+        // Rule 2 — uniqueness.
+        if (seen.has(entry.blockType)) {
+            throw new Error(`Block admin config "${entry.blockType}" is registered more than once in \`blockAdmin\`.`);
+        }
+        seen.add(entry.blockType);
+        // Rule 1 — block pairing.
+        const names = blockFieldNames.get(entry.blockType);
+        if (names == 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.
+        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.`);
+                }
+            }
+        }
+    }
+}
 function validateOne(admin, collectionsByPath) {
     // Rule 1 — slug pairing.
     const collection = collectionsByPath.get(admin.slug);
@@ -62,26 +131,30 @@ function validateOne(admin, collectionsByPath) {
         if ('name' in field)
             topLevelFieldNames.add(field.name);
     }
-    // Rule 7 — defaultSort sanity. The list read applies this spec verbatim
-    // (host list server fn → parseSort), so a bad field name would silently
-    // fall back to `created_at desc` at request time — fail loudly at boot
-    // instead.
-    if (admin.defaultSort != null) {
-        const { field, direction } = admin.defaultSort;
+    // Rule 7 — defaultSort / itemViewSort sanity. The list read applies these
+    // specs verbatim (host list server fn → parseSort), so a bad field name
+    // would silently fall back to `created_at desc` at request time — fail
+    // loudly at boot instead. Both options share one rule set.
+    const validateSortSpec = (spec, optionName) => {
+        if (spec == null)
+            return;
+        const { field, direction } = spec;
         const documentColumns = new Set(['createdAt', 'updatedAt', 'path']);
         if (collection.orderable === true) {
-            fail(`defaultSort is not allowed on an orderable collection — manual ordering owns the default sort (order_key asc).`);
+            fail(`${optionName} is not allowed on an orderable collection — manual ordering owns the sort (order_key asc).`);
         }
         if (typeof field !== 'string' || field.length === 0) {
-            fail(`defaultSort.field must be a non-empty string.`);
+            fail(`${optionName}.field must be a non-empty string.`);
         }
         if (!topLevelFieldNames.has(field) && !documentColumns.has(field)) {
-            fail(`defaultSort.field "${String(field)}" is not a top-level schema field or a document column (createdAt, updatedAt, path).`);
+            fail(`${optionName}.field "${String(field)}" is not a top-level schema field or a document column (createdAt, updatedAt, path).`);
         }
         if (direction != null && direction !== 'asc' && direction !== 'desc') {
-            fail(`defaultSort.direction must be 'asc' or 'desc' (got "${String(direction)}").`);
+            fail(`${optionName}.direction must be 'asc' or 'desc' (got "${String(direction)}").`);
         }
-    }
+    };
+    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,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { describe, expect, it } from 'vitest';
-import { validateAdminConfigs } from './validate-admin-configs.js';
+import { validateAdminConfigs, validateBlockAdminConfigs } from './validate-admin-configs.js';
 const collection = {
     path: 'news',
     labels: { singular: 'News', plural: 'News' },
@@ -238,6 +238,44 @@ describe('validateAdminConfigs', () => {
         };
         expect(() => validateAdminConfigs([admin], [orderableCollection])).toThrow(/not allowed on an orderable collection/);
     });
+    // Rule 7 — itemViewSort shares the defaultSort rule set.
+    it('accepts an itemViewSort on a schema field', () => {
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'title' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).not.toThrow();
+    });
+    it('accepts independent defaultSort and itemViewSort', () => {
+        const admin = {
+            ...baseAdmin,
+            defaultSort: { field: 'updatedAt', direction: 'desc' },
+            itemViewSort: { field: 'title' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).not.toThrow();
+    });
+    it('rejects an itemViewSort field that resolves to nothing', () => {
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'nonexistent' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/itemViewSort\.field "nonexistent"/);
+    });
+    it('rejects an itemViewSort direction outside asc/desc', () => {
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'title', direction: 'sideways' },
+        };
+        expect(() => validateAdminConfigs([admin], [collection])).toThrow(/itemViewSort\.direction must be 'asc' or 'desc'/);
+    });
+    it('rejects an itemViewSort on an orderable collection', () => {
+        const orderableCollection = { ...collection, orderable: true };
+        const admin = {
+            ...baseAdmin,
+            itemViewSort: { field: 'title' },
+        };
+        expect(() => validateAdminConfigs([admin], [orderableCollection])).toThrow(/not allowed on an orderable collection/);
+    });
     // Layout omitted — bookkeeping skipped, primitive declarations still checked.
     it('skips placement bookkeeping when layout is omitted', () => {
         const admin = {
@@ -258,3 +296,78 @@ describe('validateAdminConfigs', () => {
         expect(() => validateAdminConfigs([admin], [collection])).toThrow(/collides with a schema field/);
     });
 });
+describe('validateBlockAdminConfigs', () => {
+    const quoteBlock = {
+        blockType: 'quoteBlock',
+        fields: [
+            { name: 'quoteText', label: 'Quote', type: 'richText' },
+            { name: 'source', label: 'Source', type: 'text' },
+        ],
+    };
+    const heroBlock = {
+        blockType: 'heroBlock',
+        fields: [{ name: 'heading', label: 'Heading', type: 'text' }],
+    };
+    const blockCollection = {
+        path: 'pages',
+        labels: { singular: 'Page', plural: 'Pages' },
+        useAsPath: 'title',
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            { name: 'content', label: 'Content', type: 'blocks', blocks: [quoteBlock] },
+            {
+                name: 'meta',
+                label: 'Meta',
+                type: 'group',
+                fields: [
+                    // Blocks fields nested inside structure fields are still collected.
+                    { name: 'panels', label: 'Panels', type: 'blocks', blocks: [heroBlock] },
+                ],
+            },
+        ],
+    };
+    it('accepts a valid block admin config (baseline)', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { quoteText: {} } }], [blockCollection])).not.toThrow();
+    });
+    it('is a no-op when blockAdmins is undefined or empty', () => {
+        expect(() => validateBlockAdminConfigs(undefined, [blockCollection])).not.toThrow();
+        expect(() => validateBlockAdminConfigs([], [blockCollection])).not.toThrow();
+    });
+    // Rule 1 — block pairing.
+    it('rejects an entry whose blockType matches no declared block', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'missingBlock' }], [blockCollection])).toThrow(/no matching block/);
+    });
+    it('finds blocks declared inside nested structure fields', () => {
+        expect(() => validateBlockAdminConfigs([{ blockType: 'heroBlock', fields: { heading: {} } }], [blockCollection])).not.toThrow();
+    });
+    // Rule 2 — uniqueness.
+    it('rejects duplicate blockType entries', () => {
+        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('accepts the union of field names when a blockType appears in several collections', () => {
+        const other = {
+            path: 'docs',
+            labels: { singular: 'Doc', plural: 'Docs' },
+            useAsPath: 'title',
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'content',
+                    label: 'Content',
+                    type: 'blocks',
+                    blocks: [
+                        {
+                            blockType: 'quoteBlock',
+                            fields: [{ name: 'attribution', label: 'Attribution', type: 'text' }],
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(() => validateBlockAdminConfigs([{ blockType: 'quoteBlock', fields: { quoteText: {}, attribution: {} } }], [blockCollection, other])).not.toThrow();
+    });
+});

package/dist/config/validate-collections.js

@@ -237,5 +237,48 @@ export function validateCollections(collections) {
             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\`.`);
         }
         validateVirtualFields(collection);
+        validateUploadLocations(collection);
     }
 }
+/**
+ * Enforce the `upload.location` shape for every upload-capable field. The
+ * value is a declarative storage-key scope handed to storage providers
+ * (`<location>/<uuid>-<filename>`), so it must be a clean POSIX-style
+ * segment path:
+ *
+ *   - non-empty string, forward slashes only;
+ *   - no leading / trailing / duplicate slashes;
+ *   - segments of `A–Z a–z 0–9 . _ -` only (no spaces, no backslashes);
+ *   - no `.` or `..` segments (path traversal).
+ */
+function validateUploadLocations(collection) {
+    walkFieldsWithPath(collection.fields, (field, fieldPath) => {
+        if (field.type !== 'file' && field.type !== 'image')
+            return;
+        const location = field.upload?.location;
+        if (location === undefined)
+            return;
+        const fail = (reason) => {
+            throw new Error(`Collection "${collection.path}" field "${fieldPath}" has invalid \`upload.location\` ` +
+                `${JSON.stringify(location)}: ${reason}`);
+        };
+        if (typeof location !== 'string' || location.length === 0) {
+            fail('must be a non-empty string.');
+        }
+        if (location.startsWith('/') || location.endsWith('/')) {
+            fail('must not start or end with a slash.');
+        }
+        const segments = location.split('/');
+        for (const segment of segments) {
+            if (segment.length === 0) {
+                fail('must not contain duplicate slashes.');
+            }
+            if (segment === '.' || segment === '..') {
+                fail('must not contain `.` or `..` segments.');
+            }
+            if (!/^[A-Za-z0-9._-]+$/.test(segment)) {
+                fail(`segment "${segment}" contains unsupported characters (allowed: A–Z a–z 0–9 . _ -).`);
+            }
+        }
+    });
+}

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

@@ -452,4 +452,64 @@ describe('validateCollections', () => {
         };
         expect(() => validateCollections([collection])).toThrow(/listSearch.*virtual/s);
     });
+    // upload.location — declarative storage-key scope shape.
+    const withLocation = (location) => ({
+        ...baseCollection,
+        fields: [
+            { name: 'title', label: 'Title', type: 'text' },
+            { name: 'cover', label: 'Cover', type: 'image', optional: true, upload: { location } },
+        ],
+    });
+    it('accepts a single-segment upload.location', () => {
+        expect(() => validateCollections([withLocation('covers')])).not.toThrow();
+    });
+    it('accepts a nested upload.location', () => {
+        expect(() => validateCollections([withLocation('publications/covers')])).not.toThrow();
+    });
+    it('rejects an empty upload.location', () => {
+        expect(() => validateCollections([withLocation('')])).toThrow(/non-empty string/);
+    });
+    it('rejects a leading slash in upload.location', () => {
+        expect(() => validateCollections([withLocation('/covers')])).toThrow(/must not start or end with a slash/);
+    });
+    it('rejects a trailing slash in upload.location', () => {
+        expect(() => validateCollections([withLocation('covers/')])).toThrow(/must not start or end with a slash/);
+    });
+    it('rejects duplicate slashes in upload.location', () => {
+        expect(() => validateCollections([withLocation('a//b')])).toThrow(/must not contain duplicate slashes/);
+    });
+    it('rejects dot segments in upload.location', () => {
+        expect(() => validateCollections([withLocation('a/../b')])).toThrow(/must not contain `\.` or `\.\.` segments/);
+    });
+    it('rejects unsupported characters in upload.location', () => {
+        expect(() => validateCollections([withLocation('news attachments')])).toThrow(/unsupported characters/);
+    });
+    it('validates upload.location on fields nested inside blocks', () => {
+        const collection = {
+            ...baseCollection,
+            fields: [
+                { name: 'title', label: 'Title', type: 'text' },
+                {
+                    name: 'content',
+                    label: 'Content',
+                    type: 'blocks',
+                    blocks: [
+                        {
+                            blockType: 'attachmentsBlock',
+                            fields: [
+                                {
+                                    name: 'file',
+                                    label: 'File',
+                                    type: 'file',
+                                    optional: true,
+                                    upload: { location: 'bad//path' },
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(() => validateCollections([collection])).toThrow(/content\.file.*must not contain duplicate slashes/s);
+    });
 });

package/dist/host/host-request-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * The host-framework request bridge — the seam that makes the server-side
+ * client stack (`@byline/client/server`) host-agnostic.
+ *
+ * Everything request-scoped in that stack bottoms out in three
+ * primitives: "which request am I in" (identity for per-request
+ * memoization), "read a cookie", and "write a cookie" (admin session
+ * refresh rotates tokens). A host adapter implements those three over its
+ * framework's runtime and registers the bridge once at server boot;
+ * `@byline/client/server` is written against the interface and never
+ * imports a framework.
+ *
+ * Registration follows the same pattern as the config singletons in
+ * `config/config.ts`: a `Symbol.for` slot on `globalThis`, so every copy
+ * of this module (Vite SSR can resolve workspace-linked packages through
+ * different module graphs) shares the same state. Server-only by nature —
+ * hosts register from their boot path (side-effect imports guarantee
+ * registration before any request is handled), and nothing in a browser
+ * graph should ever reach for it.
+ */
+export interface HostCookieSetOptions {
+    httpOnly?: boolean;
+    sameSite?: 'lax' | 'strict' | 'none';
+    secure?: boolean;
+    path?: string;
+    maxAge?: number;
+}
+export interface HostRequestBridge {
+    /**
+     * A stable identity object for the current HTTP request, or `undefined`
+     * when running outside a request (seed scripts, background jobs, unit
+     * tests). Used purely as a WeakMap key for per-request memoization —
+     * never inspected.
+     */
+    getRequest(): object | undefined;
+    /** Read a request cookie. Returns `undefined` when not present. */
+    getCookie(name: string): string | undefined;
+    /** Write a response cookie (admin session refresh, preview toggles). */
+    setCookie(name: string, value: string, options?: HostCookieSetOptions): void;
+}
+/**
+ * Register the host adapter's bridge. Idempotent and last-write-wins —
+ * host adapters register from side-effect imports, which may evaluate
+ * more than once across module graphs.
+ */
+export declare function registerHostRequestBridge(bridge: HostRequestBridge): void;
+/** The registered bridge, or `undefined` when no host has registered one. */
+export declare function tryGetHostRequestBridge(): HostRequestBridge | undefined;
+/**
+ * The registered bridge, throwing with setup guidance when absent. Cookie
+ * reads/writes require a host; scripts and tests that have no request
+ * should pass an explicit `requestContext` to `createBylineClient`
+ * instead of using the request-bound getters.
+ */
+export declare function getHostRequestBridge(): HostRequestBridge;

package/dist/host/host-request-bridge.js

@@ -0,0 +1,38 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+const BYLINE_HOST_REQUEST_BRIDGE = Symbol.for('__byline_host_request_bridge__');
+/**
+ * Register the host adapter's bridge. Idempotent and last-write-wins —
+ * host adapters register from side-effect imports, which may evaluate
+ * more than once across module graphs.
+ */
+export function registerHostRequestBridge(bridge) {
+    ;
+    globalThis[BYLINE_HOST_REQUEST_BRIDGE] = bridge;
+}
+/** The registered bridge, or `undefined` when no host has registered one. */
+export function tryGetHostRequestBridge() {
+    return globalThis[BYLINE_HOST_REQUEST_BRIDGE] ?? undefined;
+}
+/**
+ * The registered bridge, throwing with setup guidance when absent. Cookie
+ * reads/writes require a host; scripts and tests that have no request
+ * should pass an explicit `requestContext` to `createBylineClient`
+ * instead of using the request-bound getters.
+ */
+export function getHostRequestBridge() {
+    const bridge = tryGetHostRequestBridge();
+    if (!bridge) {
+        throw new Error('No HostRequestBridge registered. A host adapter (e.g. ' +
+            '@byline/host-tanstack-start) must call registerHostRequestBridge() ' +
+            'at server boot before request-bound client getters can resolve ' +
+            'cookies. Scripts and tests should pass an explicit requestContext ' +
+            'to createBylineClient instead.');
+    }
+    return bridge;
+}

package/dist/index.d.ts

@@ -2,10 +2,11 @@ export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
 export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
-export { validateAdminConfigs } from './config/validate-admin-configs.js';
+export { validateAdminConfigs, validateBlockAdminConfigs, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
+export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
 export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { type BylineLogger, getLogger } from './lib/logger.js';
@@ -17,5 +18,6 @@ export * from './services/index.js';
 export * from './storage/index.js';
 export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, type SlugifierFn, type SlugifyContext, slugify, } from './utils/slugify.js';
+export { type FilenameSlugifierFn, type FilenameSlugifyContext, resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
 export * from './workflow/index.js';

package/dist/index.js

@@ -18,10 +18,11 @@ export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, bindReadContextAuthority, COLLECTION_ABILITY_VERBS, collectionAbilityKey, compileBeforeReadFilters, registerCollectionAbilities, } from './auth/index.js';
 export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, resolveItemViewColumns, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
-export { validateAdminConfigs } from './config/validate-admin-configs.js';
+export { validateAdminConfigs, validateBlockAdminConfigs, } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
+export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
 export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';
@@ -33,5 +34,6 @@ export * from './services/index.js';
 export * from './storage/index.js';
 export { normalizeRootRelativeRedirect } from './utils/root-relative-redirect.js';
 export { formatTextValue, looksLikeISODate, slugify, } from './utils/slugify.js';
+export { resolveUploadFilename, slugifyFilename, } from './utils/slugify-filename.js';
 export { getUploadFields, hasUploadField, isUploadField } from './utils/storage-utils.js';
 export * from './workflow/index.js';

package/dist/schemas/zod/builder.js

@@ -109,6 +109,17 @@ export const fieldToZodSchema = (field, strict = true) => {
             schema = textAreaSchema;
             break;
         }
+        case 'code': {
+            let codeSchema = z.string();
+            if (field.validation?.minLength) {
+                codeSchema = codeSchema.min(field.validation.minLength);
+            }
+            if (field.validation?.maxLength) {
+                codeSchema = codeSchema.max(field.validation.maxLength);
+            }
+            schema = codeSchema;
+            break;
+        }
         case 'integer':
             schema = z.number().int();
             break;

package/dist/services/build-search-document.js

@@ -122,7 +122,11 @@ function withBoost(field, decl) {
     const boost = typeof decl === 'string' ? undefined : decl.boost;
     return boost != null ? { ...field, boost } : field;
 }
-/** Text-bearing scalar leaves collected when walking into a container field. */
+/**
+ * Text-bearing scalar leaves collected when walking into a container field.
+ * `code` is deliberately excluded — source snippets are full-text noise
+ * (identifiers, punctuation) that would pollute the index.
+ */
 const TEXT_LEAF_TYPES = new Set(['text', 'textArea']);
 /**
  * Resolve a single `search.body` field to its searchable text. A scalar /

package/dist/services/document-to-markdown.js

@@ -154,6 +154,16 @@ function serializeField(field, value, ctx, level) {
             // toggles (constrainedWidth, featured) and json/object is
             // machine-shaped — the export renders content, not configuration.
             return null;
+        case 'code': {
+            // Fenced code block. The info string uses the schema's static
+            // `language` hint when present; a sibling `languageField` selection is
+            // not resolvable here (this serializer sees one field at a time), so
+            // those fences render bare — still valid markdown.
+            const text = stringValue(value);
+            if (text == null)
+                return null;
+            return `\`\`\`${field.language ?? ''}\n${text}\n\`\`\``;
+        }
         default: {
             const text = stringValue(value);
             return text ? labelled(field, text) : null;

package/dist/services/field-upload.d.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
+import { type FilenameSlugifierFn } from '../utils/slugify-filename.js';
 import type { CollectionDefinition, IDbAdapter, IStorageProvider, StoredFileLocation, StoredFileValue, UploadConfig } from '../@types/index.js';
 import type { BylineLogger } from '../lib/logger.js';
 import type { SlugifierFn } from '../utils/slugify.js';
@@ -67,6 +68,12 @@ export interface FieldUploadContext {
     defaultLocale: string;
     /** Optional installation slugifier, forwarded to the lifecycle context. */
     slugifier?: SlugifierFn;
+    /**
+     * Optional installation filename slugifier
+     * (`ServerConfig.uploads.filenameSlugifier`), applied to the uploaded base
+     * name before the `beforeStore` chain. Defaults to `slugifyFilename`.
+     */
+    filenameSlugifier?: FilenameSlugifierFn;
     /**
      * Request-scoped auth context. Forwarded to the internal
      * `DocumentLifecycleContext` when an upload creates a document, and