@byline/core 2.4.3 → 2.5.0

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

@@ -713,6 +713,36 @@ export interface CollectionDefinition {
      * without `useAsPath` receive a UUID `path` instead.
      */
     useAsPath?: string;
+    /**
+     * Optional host-defined function that composes a renderable root-relative
+     * path for a document in this collection. Called server-side by the
+     * richtext write-time walker (when `embedRelationsOnSave` is true on a
+     * `richText` field) and the read-time populate visitor (when
+     * `populateRelationsOnRead` is true). Sits next to `useAsPath` — that
+     * names the field that becomes the slug; this says how the slug
+     * composes into a renderable path.
+     *
+     * Returns a path with a leading slash, or `null` when no path can be
+     * built for this document (e.g. the doc is in a state that should not
+     * be linked to). Origin / host / protocol AND locale prefix are runtime
+     * concerns of the renderer (`LangLink` etc.) and MUST NOT be included —
+     * paths returned here are locale-agnostic; the renderer composes the
+     * final URL by prepending the request-time locale.
+     *
+     * Receives the same minimal document shape as
+     * `CollectionAdminConfig.preview.url` (`PreviewDocument`-style envelope:
+     * top-level columns plus `fields`) so the two hooks can share an
+     * implementation today and `preview.url` can default to
+     * `buildDocumentPath` in a later pass.
+     */
+    buildDocumentPath?: (doc: {
+        id: string;
+        path: string;
+        status: string;
+        fields: Record<string, any>;
+    }, ctx: {
+        collectionPath: string;
+    }) => string | null;
     /***
      * When `true`, the rich text editor's link plugin surfaces relation targets
      * from this collection as linkable options. Requires the collection to have

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

@@ -629,4 +629,40 @@ export interface RichTextPopulateContext {
  * `populateRelationsOnRead` flag.
  */
 export type RichTextPopulateFn = (ctx: RichTextPopulateContext) => Promise<void>;
+/**
+ * Context passed to the richtext embed function for one rich-text field
+ * value at write time. Mirrors `RichTextPopulateContext` — same shape,
+ * same `readContext` threading rules — but fires from the document
+ * write path (`document-lifecycle.*`) instead of the read pipeline.
+ *
+ * The adapter mutates `value` in place — typically by walking the editor's
+ * node tree and refreshing embedded relation envelopes (e.g. calling
+ * `CollectionDefinition.buildDocumentPath` and overwriting
+ * `document.path` on internal-link nodes). The framework holds the parent
+ * reference and persists the mutated value.
+ */
+export interface RichTextEmbedContext {
+    /** The richText field's value (raw editor JSON, possibly stringified). */
+    value: unknown;
+    /** Field path within the document — e.g. `'body'` or `'content.0.caption'`. */
+    fieldPath: string;
+    /** Collection path the document belongs to. */
+    collectionPath: string;
+    /**
+     * Shared request-scoped `ReadContext`. Threading is mandatory — adapter
+     * implementations must pass this back into any `client.collection(...)`
+     * read they perform via `_readContext`. The lifecycle write path spins
+     * one up per save so the embed walker's reads share visited-set / read
+     * budget machinery with the rest of the framework.
+     */
+    readContext: import('./db-types.js').ReadContext;
+}
+/**
+ * Server-side embed function contract. Editor adapters export an
+ * implementation; installations register one via
+ * `ServerConfig.fields.richText.embed`. Called once per rich-text
+ * leaf the framework discovers in a document during save, gated by
+ * each field's `embedRelationsOnSave` flag.
+ */
+export type RichTextEmbedFn = (ctx: RichTextEmbedContext) => Promise<void>;
 export {};

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

@@ -10,7 +10,7 @@ import type { SlugifierFn } from '../utils/slugify.js';
 import type { CollectionAdminConfig } from './admin-types.js';
 import type { CollectionDefinition } from './collection-types.js';
 import type { IDbAdapter } from './db-types.js';
-import type { RichTextEditorComponent, RichTextPopulateFn } from './field-types.js';
+import type { RichTextEditorComponent, RichTextEmbedFn, RichTextPopulateFn } from './field-types.js';
 import type { IStorageProvider } from './storage-types.js';
 export type DbAdapterFn = (args: {
     connectionString: string;
@@ -189,24 +189,41 @@ export interface ServerConfig<TAdminStore = unknown> extends BaseConfig {
      *
      * @example
      * ```ts
-     * import { lexicalEditorServer } from '@byline/richtext-lexical/server'
+     * import {
+     *   lexicalEditorEmbedServer,
+     *   lexicalEditorPopulateServer,
+     * } from '@byline/richtext-lexical/server'
      *
      * defineServerConfig({
      *   fields: {
-     *     richText: { populate: lexicalEditorServer({ getClient: getAdminBylineClient }) },
+     *     richText: {
+     *       embed: lexicalEditorEmbedServer({ getClient: getAdminBylineClient }),
+     *       populate: lexicalEditorPopulateServer({ getClient: getAdminBylineClient }),
+     *     },
      *   },
      * })
      * ```
      */
     fields?: {
         /**
-         * Richtext server-side populate function. Invoked by the read pipeline
-         * for every rich-text field whose effective `populateRelationsOnRead`
-         * is `true`. Required when any collection has a `richText` field
-         * configured to populate on read; `initBylineCore()` enforces this.
+         * Richtext server-side adapter slots.
+         *
+         * `populate` — invoked by the read pipeline for every rich-text field
+         * whose effective `populateRelationsOnRead` is `true`. Required when
+         * any collection has a `richText` field configured to populate on
+         * read; `initBylineCore()` enforces this.
+         *
+         * `embed` — invoked by the document-lifecycle write path for every
+         * rich-text field whose effective `embedRelationsOnSave` is `true`
+         * (the default). Walks the editor tree at save time and refreshes
+         * embedded relation envelopes (e.g. composing `document.path` via
+         * `CollectionDefinition.buildDocumentPath` on internal-link nodes).
+         * Required when any collection has a `richText` field with
+         * `embedRelationsOnSave: true`; `initBylineCore()` enforces this.
          */
         richText?: {
-            populate: RichTextPopulateFn;
+            populate?: RichTextPopulateFn;
+            embed?: RichTextEmbedFn;
         };
     };
 }

package/dist/core.js

@@ -41,7 +41,10 @@ export const initBylineCore = async (config, pinoLogger) => {
     // before any DB work. Fail-fast surfaces unrenderable configurations
     // (both flags off) and missing-adapter cases at boot rather than at
     // request time.
-    validateRichTextFieldFlags(composed.collections, config.fields?.richText?.populate != null);
+    validateRichTextFieldFlags(composed.collections, {
+        populate: config.fields?.richText?.populate != null,
+        embed: config.fields?.richText?.embed != null,
+    });
     // Backward compat: populate globalThis singletons
     defineServerConfig(config);
     defineLogger(composed.logger);

package/dist/services/document-lifecycle.js

@@ -7,7 +7,7 @@
  */
 import { isArrayField, isBlocksField, isGroupField, normalizeCollectionHook, } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
-import { getCollectionDefinition } from '../config/config.js';
+import { getCollectionDefinition, getServerConfig } from '../config/config.js';
 import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_PATH_CONFLICT, ERR_VALIDATION, ErrorCodes, } from '../lib/errors.js';
 import { generateKeyBetween } from '../lib/fractional-index.js';
 import { withLogContext } from '../lib/logger.js';
@@ -17,6 +17,8 @@ import { slugify } from '../utils/slugify.js';
 import { getUploadFields } from '../utils/storage-utils.js';
 import { getDefaultStatus, getWorkflow, validateStatusTransition } from '../workflow/workflow.js';
 import { assignCounterValues } from './assign-counter-values.js';
+import { createReadContext } from './populate.js';
+import { embedRichTextFields } from './richtext-embed.js';
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -31,6 +33,41 @@ async function invokeHook(hook, ctx) {
         await fn(ctx);
     }
 }
+/**
+ * Run the registered richtext embed adapter across every rich-text leaf
+ * in the outgoing document data. Mirror of the read-side
+ * `populateRichTextFields` — fires once per write, mutates `data` in
+ * place. Per-leaf errors are logged and swallowed by `embedRichTextFields`
+ * itself (branch C); document-level errors propagate.
+ *
+ * No-op when no embed adapter is registered. The bootstrap validator
+ * (step 7 of the link-refactor strategy) will eventually fail-fast for
+ * collections that declare `embedRelationsOnSave: true` without a
+ * registered adapter; until then a missing adapter is silent and writes
+ * proceed unmodified.
+ */
+async function applyRichTextEmbed(ctx, data) {
+    // Tolerate environments that drive the lifecycle without
+    // `initBylineCore()` (unit tests, isolated tooling) — they have no
+    // adapter to invoke, so this is a soft no-op.
+    let embed;
+    try {
+        embed = getServerConfig().fields?.richText?.embed;
+    }
+    catch {
+        return;
+    }
+    if (embed == null)
+        return;
+    await embedRichTextFields({
+        fields: ctx.definition.fields,
+        collectionPath: ctx.collectionPath,
+        data,
+        embed,
+        readContext: createReadContext(),
+        logger: ctx.logger,
+    });
+}
 /**
  * For collections with `orderable: true` on their schema definition, compute
  * an append-at-end fractional-index key for a newly-inserted document.
@@ -191,6 +228,9 @@ export async function createDocument(ctx, params) {
         // carries the key into the byline_documents row. No effect when the
         // admin config opts out or isn't registered.
         const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
+        // Refresh embedded relation envelopes inside rich-text fields
+        // (internal-link / inline-image nodes) before flatten-and-persist.
+        await applyRichTextEmbed(ctx, data);
         const result = await db.commands.documents
             .createDocumentVersion({
             collectionId,
@@ -268,6 +308,7 @@ export async function updateDocument(ctx, params) {
             documentId: params.documentId,
             logger: ctx.logger,
         });
+        await applyRichTextEmbed(ctx, data);
         const result = await db.commands.documents
             .createDocumentVersion({
             documentId: params.documentId,
@@ -374,6 +415,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             documentId: params.documentId,
             logger: ctx.logger,
         });
+        await applyRichTextEmbed(ctx, nextData);
         const result = await db.commands.documents
             .createDocumentVersion({
             documentId: params.documentId,
@@ -628,6 +670,11 @@ export async function restoreDocumentVersion(ctx, params) {
             collectionPath,
             restore: restoreContext,
         });
+        // Embed walker is a no-op here for localized richtext leaves
+        // (multi-locale `{ locale: lexJson }` shape — see
+        // richtext-embed.ts header). Non-localized richtext leaves still
+        // get refreshed, so leave the call in for that branch.
+        await applyRichTextEmbed(ctx, sourceFields);
         // 6. Persist new version. locale: 'all' carries every locale row in
         //    the source tree forward in a single flatten pass — the
         //    cross-locale carry-forward branch in createDocumentVersion does
@@ -930,6 +977,9 @@ export async function duplicateDocument(ctx, params) {
         // before the insert; the source row's order is intentionally not
         // copied — duplicates land at the end of the list.
         const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
+        // Embed walker (no-op for multi-locale richtext leaves — see
+        // restoreDocumentVersion for the same caveat).
+        await applyRichTextEmbed(ctx, clonedFields);
         try {
             result = await db.commands.documents
                 .createDocumentVersion({
@@ -1247,6 +1297,7 @@ export async function copyToLocale(ctx, params) {
         //    *other* locale (not source, not target — those rows are
         //    rewritten by this call).
         const previousVersionId = targetRecord.document_version_id ?? undefined;
+        await applyRichTextEmbed(ctx, merged.data);
         const writeResult = await db.commands.documents.createDocumentVersion({
             documentId: params.documentId,
             collectionId,

package/dist/services/index.d.ts

@@ -8,5 +8,6 @@ export * from './document-read.js';
 export * from './field-upload.js';
 export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, type UnresolvedRelationValue, } from './populate.js';
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
-export { collectRichTextLeaves, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export { type EmbedRichTextFieldsOptions, embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
+export { collectRichTextLeaves, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextAdapterPresence, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
 export { type FieldLeaf, walkFieldTree } from './walk-field-tree.js';

package/dist/services/index.js

@@ -9,5 +9,6 @@ export * from './document-read.js';
 export * from './field-upload.js';
 export { createReadContext, populateDocuments, } from './populate.js';
 export { buildRelationSummaryPopulateMap, resolveRelationProjection, } from './relation-projection.js';
+export { embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
 export { collectRichTextLeaves, populateRichTextFields, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
 export { walkFieldTree } from './walk-field-tree.js';

package/dist/services/richtext-embed.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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
+ */
+import type { FieldSet, RichTextEmbedFn, RichTextField } from '../@types/field-types.js';
+import type { ReadContext } from '../@types/index.js';
+import type { BylineLogger } from '../lib/logger.js';
+/**
+ * Resolve the effective `embedRelationsOnSave` for a richText field.
+ * Defaults to `true` — embed-on-save is the headline behaviour the new
+ * walker turns on, and CMS authors expect picker-time choices to land
+ * with refreshed envelopes by default.
+ */
+export declare function resolveEmbedOnSave(field: RichTextField): boolean;
+export interface EmbedRichTextFieldsOptions {
+    /** Source collection's schema fields (used to drive the leaf walk). */
+    fields: FieldSet;
+    collectionPath: string;
+    /**
+     * The outgoing document data. Mutated in place by the adapter as each
+     * rich-text leaf is walked.
+     */
+    data: Record<string, any>;
+    /** Registered server-side embed function from `ServerConfig`. */
+    embed: RichTextEmbedFn;
+    /**
+     * Request-scoped read context. Threading is mandatory — the embed
+     * adapter performs reads while walking and must share the same
+     * visited-set / read-budget machinery as the rest of the framework.
+     */
+    readContext: ReadContext;
+    /** Structured logger — used for branch-C per-leaf error reporting. */
+    logger: BylineLogger;
+}
+/**
+ * For one document being saved, walk its rich-text leaves and call the
+ * registered embed function for each leaf whose effective
+ * `embedRelationsOnSave` is `true`.
+ *
+ * Per-leaf errors are caught and logged at `error` level. The leaf's
+ * value is left as whatever the caller submitted — the persistence step
+ * downstream proceeds. Document-level errors propagate.
+ */
+export declare function embedRichTextFields(options: EmbedRichTextFieldsOptions): Promise<void>;

package/dist/services/richtext-embed.js

@@ -0,0 +1,77 @@
+/**
+ * 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
+ */
+/**
+ * Richtext embed service — walks an outgoing document, finds every
+ * rich-text leaf (including those nested inside `group` / `array` /
+ * `blocks` structures), gates each leaf by its `embedRelationsOnSave`
+ * flag, and dispatches to the registered richtext embed adapter so
+ * link envelopes (and any future write-time embeds) can be refreshed
+ * before the value is flattened and persisted.
+ *
+ * Mirror of `richtext-populate.ts`. Slots into the document-lifecycle
+ * write path:
+ *
+ *   beforeCreate / beforeUpdate
+ *     → assignCounterValues
+ *     → embedRichTextFields       (this module)
+ *     → createDocumentVersion
+ *     → afterCreate / afterUpdate
+ *
+ * Per-leaf errors are logged and swallowed — leaving the persisted state
+ * for that leaf as the editor submitted it. Aligns with the strategy's
+ * "branch C — hard error" non-destructive fail mode (see
+ * docs/RICHTEXT-LINK-REFACTOR-STRATEGY.md § 3.3).
+ *
+ * Multi-locale (`locale: 'all'`) writes: when a richText leaf's value is
+ * a `{ <locale>: lexicalJson }` map (the shape used by
+ * `restoreDocumentVersion` and `duplicateDocument`), the adapter's
+ * `getLexicalRoot` parses the object as a single tree, finds no `root`
+ * key and no `children` array, and yields nothing. So embed is a no-op
+ * on multi-locale writes — the persisted state carries forward exactly
+ * what the source had. Per-locale walking is a deliberate future
+ * refinement; today's behaviour matches the populate side (which only
+ * fires on locale-scoped reads) and the renderer's fallback chain
+ * handles stale embedded paths.
+ */
+import { collectRichTextLeaves } from './richtext-populate.js';
+/**
+ * Resolve the effective `embedRelationsOnSave` for a richText field.
+ * Defaults to `true` — embed-on-save is the headline behaviour the new
+ * walker turns on, and CMS authors expect picker-time choices to land
+ * with refreshed envelopes by default.
+ */
+export function resolveEmbedOnSave(field) {
+    return field.embedRelationsOnSave ?? true;
+}
+/**
+ * For one document being saved, walk its rich-text leaves and call the
+ * registered embed function for each leaf whose effective
+ * `embedRelationsOnSave` is `true`.
+ *
+ * Per-leaf errors are caught and logged at `error` level. The leaf's
+ * value is left as whatever the caller submitted — the persistence step
+ * downstream proceeds. Document-level errors propagate.
+ */
+export async function embedRichTextFields(options) {
+    const { fields, collectionPath, data, embed, readContext, logger } = options;
+    for (const leaf of collectRichTextLeaves(fields, data)) {
+        if (!resolveEmbedOnSave(leaf.field))
+            continue;
+        try {
+            await embed({
+                value: leaf.value,
+                fieldPath: leaf.fieldPath,
+                collectionPath,
+                readContext,
+            });
+        }
+        catch (err) {
+            logger.error({ err, collectionPath, fieldPath: leaf.fieldPath }, 'richtext embed adapter threw — leaf left untouched (branch C)');
+        }
+    }
+}

package/dist/services/richtext-populate.d.ts

@@ -76,6 +76,17 @@ export declare function resolvePopulateOnRead(field: RichTextField): boolean;
  * is `true`. Mutates document `fields` in place.
  */
 export declare function populateRichTextFields(options: PopulateRichTextFieldsOptions): Promise<void>;
+/**
+ * Which richtext server adapters the host has registered. Pass both
+ * flags so the validator can fail-fast on each missing-adapter case
+ * with a specific message.
+ */
+export interface RichTextAdapterPresence {
+    /** `ServerConfig.fields.richText.populate != null` */
+    populate: boolean;
+    /** `ServerConfig.fields.richText.embed != null` */
+    embed: boolean;
+}
 /**
  * Validate every richText field across every collection. Throws on:
  *   1. `embedRelationsOnSave === false && populateRelationsOnRead === false`
@@ -83,8 +94,12 @@ export declare function populateRichTextFields(options: PopulateRichTextFieldsOp
  *   2. Effective `populateRelationsOnRead === true` and no server-side
  *      `RichTextPopulateFn` registered — populate would be a no-op and
  *      the field would render with stale (or empty) embedded data.
+ *   3. Effective `embedRelationsOnSave === true` and no server-side
+ *      `RichTextEmbedFn` registered — saves would silently skip the
+ *      walker so internal-link `document.path` envelopes would never
+ *      be canonicalised, breaking the renderer's fallback chain.
  *
  * Called once at `initBylineCore()` time. Fail-fast at boot is the right
  * posture; the alternative is a silent broken renderer at request time.
  */
-export declare function validateRichTextFieldFlags(collections: CollectionDefinition[], hasServerAdapter: boolean): void;
+export declare function validateRichTextFieldFlags(collections: CollectionDefinition[], adapters: RichTextAdapterPresence): void;

package/dist/services/richtext-populate.js

@@ -118,11 +118,15 @@ function* walkDeclaration(field, declaredPath) {
  *   2. Effective `populateRelationsOnRead === true` and no server-side
  *      `RichTextPopulateFn` registered — populate would be a no-op and
  *      the field would render with stale (or empty) embedded data.
+ *   3. Effective `embedRelationsOnSave === true` and no server-side
+ *      `RichTextEmbedFn` registered — saves would silently skip the
+ *      walker so internal-link `document.path` envelopes would never
+ *      be canonicalised, breaking the renderer's fallback chain.
  *
  * Called once at `initBylineCore()` time. Fail-fast at boot is the right
  * posture; the alternative is a silent broken renderer at request time.
  */
-export function validateRichTextFieldFlags(collections, hasServerAdapter) {
+export function validateRichTextFieldFlags(collections, adapters) {
     const errors = [];
     for (const def of collections) {
         for (const { field, declaredPath } of iterRichTextFieldDeclarations(def.fields)) {
@@ -134,12 +138,18 @@ export function validateRichTextFieldFlags(collections, hasServerAdapter) {
                     `Set at least one to true — otherwise nothing renders.`);
                 continue;
             }
-            if (populate && !hasServerAdapter) {
+            if (populate && !adapters.populate) {
                 errors.push(`[${def.path}] richText field '${declaredPath}' requires read-time populate ` +
                     `(embedRelationsOnSave=${embed}, populateRelationsOnRead=${populate}) but no ` +
-                    `richtext server adapter is registered. Wire one via ` +
+                    `richtext populate adapter is registered. Wire one via ` +
                     `ServerConfig.fields.richText.populate — see ` +
-                    `\`@byline/richtext-lexical/server\` → \`lexicalEditorServer()\`.`);
+                    `\`@byline/richtext-lexical/server\` → \`lexicalEditorPopulateServer()\`.`);
+            }
+            if (embed && !adapters.embed) {
+                errors.push(`[${def.path}] richText field '${declaredPath}' requires write-time embed ` +
+                    `(embedRelationsOnSave=${embed}) but no richtext embed adapter is registered. ` +
+                    `Wire one via ServerConfig.fields.richText.embed — see ` +
+                    `\`@byline/richtext-lexical/server\` → \`lexicalEditorEmbedServer()\`.`);
             }
         }
     }

package/dist/services/richtext-populate.test.node.js

@@ -149,21 +149,35 @@ function makeCollection(richTextField) {
         ],
     };
 }
+const BOTH = { populate: true, embed: true };
+const POPULATE_ONLY = { populate: true, embed: false };
+const NEITHER = { populate: false, embed: false };
 describe('validateRichTextFieldFlags', () => {
-    it('passes when default flags are used and adapter is registered', () => {
-        expect(() => validateRichTextFieldFlags([makeCollection({})], true)).not.toThrow();
+    it('passes when default flags are used and both adapters are registered', () => {
+        expect(() => validateRichTextFieldFlags([makeCollection({})], BOTH)).not.toThrow();
     });
-    it('passes when default flags are used and no adapter is registered (snapshot mode)', () => {
-        expect(() => validateRichTextFieldFlags([makeCollection({})], false)).not.toThrow();
+    it('throws when default flags are used and the embed adapter is missing', () => {
+        // Default `embedRelationsOnSave: true` requires the embed adapter.
+        expect(() => validateRichTextFieldFlags([makeCollection({})], POPULATE_ONLY)).toThrow(/no richtext embed adapter is registered/i);
+    });
+    it('passes when default flags are used and no adapters are registered (snapshot mode, fields opted out)', () => {
+        // Both flags explicitly off: field is non-renderable, so the
+        // first-line "both off" check trips before the missing-adapter
+        // checks. Wrap with a single field that opts out of both.
+        expect(() => validateRichTextFieldFlags([], NEITHER)).not.toThrow();
     });
     it('throws when both flags are explicitly false', () => {
-        expect(() => validateRichTextFieldFlags([makeCollection({ embedRelationsOnSave: false, populateRelationsOnRead: false })], true)).toThrow(/both .* set to false/i);
+        expect(() => validateRichTextFieldFlags([makeCollection({ embedRelationsOnSave: false, populateRelationsOnRead: false })], BOTH)).toThrow(/both .* set to false/i);
     });
-    it('throws when embedRelationsOnSave: false but no adapter is registered', () => {
-        expect(() => validateRichTextFieldFlags([makeCollection({ embedRelationsOnSave: false })], false)).toThrow(/no.*server adapter/i);
+    it('throws when populate is required but the populate adapter is missing', () => {
+        // embedRelationsOnSave: false flips the default for populate to true.
+        expect(() => validateRichTextFieldFlags([makeCollection({ embedRelationsOnSave: false })], {
+            populate: false,
+            embed: true,
+        })).toThrow(/no richtext populate adapter is registered/i);
     });
-    it('throws when belt-and-braces is asked for but no adapter is registered', () => {
-        expect(() => validateRichTextFieldFlags([makeCollection({ embedRelationsOnSave: true, populateRelationsOnRead: true })], false)).toThrow(/no.*server adapter/i);
+    it('throws when belt-and-braces is asked for but no adapters are registered', () => {
+        expect(() => validateRichTextFieldFlags([makeCollection({ embedRelationsOnSave: true, populateRelationsOnRead: true })], NEITHER)).toThrow(/no richtext (populate|embed) adapter is registered/i);
     });
     it('reports nested richText paths inside blocks with the block type tag', () => {
         const collection = {
@@ -191,6 +205,6 @@ describe('validateRichTextFieldFlags', () => {
                 },
             ],
         };
-        expect(() => validateRichTextFieldFlags([collection], true)).toThrow(/content\.<photoBlock>\.caption/);
+        expect(() => validateRichTextFieldFlags([collection], BOTH)).toThrow(/content\.<photoBlock>\.caption/);
     });
 });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.4.3",
+  "version": "2.5.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "2.4.3"
+    "@byline/auth": "2.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",