@byline/richtext-lexical 2.4.4 → 2.5.1

package/dist/field/config/default.js

@@ -15,8 +15,7 @@ const DEFAULT_EDITOR_SETTINGS = {
         debug: false
     },
     inlineImageUploadCollection: 'media',
-    placeholderText: 'Enter some rich text...',
-    embedRelationsOnSave: true
+    placeholderText: 'Enter some rich text...'
 };
 const defaultEditorConfig = {
     settings: DEFAULT_EDITOR_SETTINGS,

package/dist/field/config/types.d.ts

@@ -18,22 +18,11 @@ export interface EditorSettings {
      */
     inlineImageUploadCollection: string;
     placeholderText: string;
-    /**
-     * Whether relation-bearing nodes (link, inline-image) embed the picker's
-     * resolved target fields (`title`, `path`, `altText`, `image`, `sizes`)
-     * into the persisted Lexical JSON at modal-save time. Defaults to `true`.
-     *
-     * Mirrors `RichTextField.embedRelationsOnSave`. The lexical wrapper
-     * (`richtext-field.tsx`) merges the field-level value over the resolved
-     * editor settings so each field gets the policy it asked for.
-     */
-    embedRelationsOnSave: boolean;
 }
 export interface EditorSettingsOverride {
     options?: Partial<Record<OptionName, boolean>>;
     inlineImageUploadCollection?: string;
     placeholderText?: string;
-    embedRelationsOnSave?: boolean;
 }
 export interface EditorConfig {
     settings: EditorSettings;

package/dist/field/extensions/inline-image/inline-image-modal.js

@@ -3,7 +3,6 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
 import { getCollectionDefinition } from "@byline/core";
 import { Button, Checkbox, CloseIcon, ErrorText, IconButton, Input, Label, Modal, RadioGroup, RadioGroupItem, RelationPicker } from "@byline/ui/react";
-import { useEditorConfig } from "../../config/editor-config-context.js";
 import { useModalFormState } from "../../shared/useModalFormState.js";
 import { isAltTextValid, positionOptions } from "./fields.js";
 import { deriveImageSizes, getPreferredSize } from "./utils.js";
@@ -28,7 +27,6 @@ const InlineImageModal = ({ isOpen, collection, data: dataFromProps, onSubmit, o
     const [pickerOpen, setPickerOpen] = useState(false);
     const [altError, setAltError] = useState(null);
     const [imageError, setImageError] = useState(null);
-    const { config: editorSettings } = useEditorConfig();
     const [state, setState] = useModalFormState(isOpen, ()=>fromInlineImageData(dataFromProps), ()=>{
         setAltError(null);
         setImageError(null);
@@ -84,13 +82,8 @@ const InlineImageModal = ({ isOpen, collection, data: dataFromProps, onSubmit, o
         if (!state.documentRelation || !pickedImage) return void setImageError('Pick an image');
         if (!isAltTextValid(state.altText)) return void setAltError('Alt text is required');
         const preferred = getPreferredSize(state.position, pickedImage);
-        const persistedRelation = editorSettings.embedRelationsOnSave ? state.documentRelation : {
-            targetDocumentId: state.documentRelation.targetDocumentId,
-            targetCollectionId: state.documentRelation.targetCollectionId,
-            targetCollectionPath: state.documentRelation.targetCollectionPath
-        };
         const data = {
-            documentRelation: persistedRelation,
+            documentRelation: state.documentRelation,
             src: preferred?.url ?? pickedImage.storageUrl ?? '',
             altText: state.altText.trim(),
             position: state.position,

package/dist/field/extensions/link/link-modal.js

@@ -3,7 +3,6 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
 import { getClientConfig, getCollectionDefinition } from "@byline/core";
 import { Button, Checkbox, CloseIcon, IconButton, Input, Label, Modal, RadioGroup, RadioGroupItem, RelationPicker, Select } from "@byline/ui/react";
-import { useEditorConfig } from "../../config/editor-config-context.js";
 import { useModalFormState } from "../../shared/useModalFormState.js";
 import { validateUrl } from "../../utils/url.js";
 function emptyState(linkable) {
@@ -44,7 +43,6 @@ const LinkModal = ({ isOpen = false, onSubmit, onClose, data: dataFromProps })=>
     const linkable = useMemo(()=>getClientConfig().collections.filter((c)=>true === c.linksInEditor), []);
     const [pickerOpen, setPickerOpen] = useState(false);
     const [urlError, setUrlError] = useState(null);
-    const { config: editorSettings } = useEditorConfig();
     const [state, setState] = useModalFormState(isOpen, ()=>fromLinkData(dataFromProps, linkable), ()=>setUrlError(null));
     const targetDef = state.targetCollection ? getCollectionDefinition(state.targetCollection) : null;
     const collectionItems = useMemo(()=>linkable.map((c)=>({
@@ -104,7 +102,7 @@ const LinkModal = ({ isOpen = false, onSubmit, onClose, data: dataFromProps })=>
             targetDocumentId: picked.targetDocumentId,
             targetCollectionId: picked.targetCollectionId,
             targetCollectionPath: picked.targetCollectionPath,
-            document: editorSettings.embedRelationsOnSave ? picked.document : void 0
+            document: picked.document
         };
         onSubmit({
             text: state.text.length > 0 ? state.text : null,

package/dist/field/extensions/link/populate.d.ts

@@ -5,17 +5,5 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-/**
- * Server-side populate visitor for the link plugin. Pure / framework-
- * agnostic — imported only from the package's `server` entry.
- *
- * Refreshes `attributes.document` on `link` nodes whose
- * `attributes.linkType` is `'internal'`. Tight projection — `{ title,
- * path }` only, matching what the link modal embeds at picker time.
- *
- * `linkType: 'custom'` links carry a literal URL and have no relation
- * envelope; they're skipped. Auto-link nodes (`type: 'autolink'`) are
- * also skipped — they're derived from URL patterns and never internal.
- */
 import type { LexicalNodeVisitor } from '../../lexical-populate-shared';
 export declare const linkVisitor: LexicalNodeVisitor;

package/dist/field/extensions/link/populate.js

@@ -1,3 +1,4 @@
+import { getCollectionDefinition, getLogger } from "@byline/core";
 const linkVisitor = {
     match (node) {
         if ('link' !== node.type) return null;
@@ -12,14 +13,52 @@ const linkVisitor = {
             collectionPath,
             documentId,
             apply (target) {
+                const definition = getCollectionDefinition(collectionPath);
+                const useAsTitle = definition?.useAsTitle ?? 'title';
                 const targetFields = target.fields ?? {};
-                const path = target.path;
-                const title = targetFields.title;
                 const next = {
                     ...attributes.document ?? {}
                 };
+                const title = targetFields[useAsTitle];
                 if ('string' == typeof title && title.length > 0) next.title = title;
-                if ('string' == typeof path && path.length > 0) next.path = path;
+                let pathThrew = false;
+                let built;
+                if (definition?.buildDocumentPath != null) try {
+                    built = definition.buildDocumentPath({
+                        id: target.id,
+                        path: target.path,
+                        status: target.status,
+                        fields: targetFields
+                    }, {
+                        collectionPath
+                    });
+                } catch (err) {
+                    pathThrew = true;
+                    getLogger().info({
+                        collectionPath,
+                        documentId,
+                        err
+                    }, 'buildDocumentPath threw');
+                }
+                if (!pathThrew) if ('string' == typeof built) next.path = built;
+                else {
+                    const targetPath = target.path;
+                    if ('string' == typeof targetPath && targetPath.length > 0) next.path = `/${collectionPath}/${targetPath}`;
+                }
+                if ('_resolved' in next) delete next._resolved;
+                attributes.document = next;
+            },
+            applyMissing () {
+                getLogger().warn({
+                    collectionPath,
+                    documentId
+                }, 'internal link target not found');
+                const next = {
+                    ...attributes.document ?? {}
+                };
+                delete next.title;
+                delete next.path;
+                next._resolved = false;
                 attributes.document = next;
             }
         };

package/dist/field/extensions/link/types.d.ts

@@ -9,13 +9,40 @@ export interface CustomLinkAttributes extends BaseLinkAttributes {
     linkType?: 'custom';
     url?: string;
 }
+/**
+ * Denormalised document fields carried on an internal-link node.
+ *
+ *   - `title` — the target document's `useAsTitle` value. Refreshed by the
+ *     server-side link walker (both embed-on-save and populate-on-read
+ *     pipelines) whenever the target resolves.
+ *   - `path` — the canonical renderable path. Has dual meaning during
+ *     migration:
+ *       * with a leading `/` — composed by `CollectionDefinition.buildDocumentPath`
+ *         (or the generic `/${collectionPath}/${slug}` fallback) and
+ *         considered authoritative by the renderer.
+ *       * without a leading `/` — bare slug from `byline_document_paths`,
+ *         either legacy data or a picker-time write that has not yet been
+ *         through the walker. The renderer applies the generic compose
+ *         fallback in that case.
+ *   - `_resolved` — explicitly set to `false` by the walker when the most
+ *     recent pass could not find the target document. Absent (i.e. the
+ *     property is omitted) when the target resolved on the last pass.
+ *     Renderers strip the `<a>` wrapper and render children as plain text
+ *     when this is `false`, preserving editor intent without producing
+ *     a broken anchor on the public site.
+ */
+export interface InternalLinkDocument {
+    title?: string;
+    path?: string;
+    _resolved?: false;
+}
 /**
  * Internal link to a Byline document. The relation envelope (`targetDocumentId`,
  * `targetCollectionId`, `targetCollectionPath`, `document`) is flattened
  * directly onto the attributes alongside `linkType` — same shape pattern as
  * the `RelationField` value, no extra wrapper.
  */
-export interface InternalLinkAttributes extends BaseLinkAttributes, DocumentRelation {
+export interface InternalLinkAttributes extends BaseLinkAttributes, DocumentRelation<InternalLinkDocument> {
     linkType: 'internal';
 }
 export type LinkAttributes = CustomLinkAttributes | InternalLinkAttributes;

package/dist/field/lexical-populate-shared.d.ts

@@ -60,9 +60,18 @@ export interface PendingHydration {
      * Apply the freshly-fetched target document to the node. Mutates `node`
      * in place; `target.fields` is the shaped collection record. Receives
      * the full target so the visitor can pick whatever projection it cares
-     * about.
+     * about. Invoked by the driver only when the target was found.
      */
     apply: (target: Record<string, any>) => void;
+    /**
+     * Optional handler invoked by the driver when the target document could
+     * not be fetched — i.e. it was deleted between the picker's write and
+     * this walk. Lets the visitor mark the node with degraded state
+     * (e.g. `document._resolved = false` on internal-link nodes) so the
+     * renderer can react. Omit on visitors that prefer the older "silent
+     * skip" behaviour; the driver no-ops when absent.
+     */
+    applyMissing?: () => void;
 }
 /**
  * Visitor contract — one per node type that participates in populate.
@@ -88,9 +97,15 @@ interface RunPopulateOptions {
 /**
  * Walk every supplied rich-text value, collect the union of pending
  * hydrations across all visitors, batch-fetch by source collection, and
- * apply. Threading `readContext` keeps the visited-set / `afterReadFired`
- * / read-budget machinery in sync with relation populate and user-land
- * `afterRead` hooks.
+ * apply.
+ *
+ * `readContext` is accepted (factories thread it through from
+ * `RichTextPopulateContext` / `RichTextEmbedContext`) but currently unused —
+ * the batch fetch goes straight to `getDocumentsByDocumentIds` and doesn't
+ * recurse into populate or `afterRead`, so there's no visited-set or
+ * read-budget state to share. Retained on the options shape so a future
+ * visitor that performs nested populate can opt back in without another
+ * contract churn.
  */
 export declare function runLexicalPopulate(options: RunPopulateOptions): Promise<void>;
 export {};

package/dist/field/lexical-populate-shared.js

@@ -17,7 +17,7 @@ function* iterAllNodes(node) {
     if (Array.isArray(node.children)) for (const child of node.children)yield* iterAllNodes(child);
 }
 async function runLexicalPopulate(options) {
-    const { client, readContext, visitors, values } = options;
+    const { client, visitors, values } = options;
     const pending = [];
     for (const value of values){
         const root = getLexicalRoot(value);
@@ -39,22 +39,25 @@ async function runLexicalPopulate(options) {
     const fetched = new Map();
     await Promise.all(Array.from(idsByCollection.entries()).map(async ([collectionPath, idSet])=>{
         const ids = Array.from(idSet);
-        const result = await client.collection(collectionPath).find({
-            where: {
-                id: {
-                    $in: ids
-                }
-            },
-            pageSize: ids.length,
-            _readContext: readContext
+        const collectionId = await client.resolveCollectionId(collectionPath);
+        const rawDocs = await client.db.queries.documents.getDocumentsByDocumentIds({
+            collection_id: collectionId,
+            document_ids: ids,
+            readMode: 'published'
         });
         const byId = new Map();
-        for (const d of result.docs)if ('string' == typeof d.id) byId.set(d.id, d);
+        for (const raw of rawDocs)if ('string' == typeof raw.document_id) byId.set(raw.document_id, {
+            id: raw.document_id,
+            path: raw.path,
+            status: raw.status,
+            fields: raw.fields
+        });
         fetched.set(collectionPath, byId);
     }));
     for (const p of pending){
         const target = fetched.get(p.collectionPath)?.get(p.documentId);
         if (target) p.apply(target);
+        else p.applyMissing?.();
     }
 }
 export { getLexicalRoot, iterAllNodes, runLexicalPopulate };

package/dist/field/nodes/document-relation.d.ts

@@ -11,22 +11,29 @@
  * picks). Mirrors the relation-field envelope (`targetDocumentId` /
  * `targetCollectionId`) and adds the human-readable collection `path` plus
  * an optional `document` bag for denormalised fields populated by the picker
- * at write time or by an `afterRead` collection hook at read time.
+ * at write time or by the server-side richtext walker at read / save time.
  *
  * The two ID fields are the source of truth; `targetCollectionPath` is
  * carried alongside because the editor has no field-definition side-channel
  * (unlike a `relation` field) to look up the path from the id at render time.
  * `document` is best-effort — renderers must tolerate it being absent.
+ *
+ * The `document` slot is parameterised by `D` so each node type can pin its
+ * own shape: internal-link nodes pin `{ title?, path?, _resolved?: false }`
+ * (see `InternalLinkAttributes`); inline-image nodes carry image-specific
+ * fields (`title`, `altText`, `image`, `sizes`). Defaults to a loose
+ * `Record<string, any>` so existing call sites continue to compile.
  */
-export interface DocumentRelation {
+export interface DocumentRelation<D extends Record<string, any> = Record<string, any>> {
     targetDocumentId: string;
     targetCollectionId: string;
     targetCollectionPath: string;
     /**
      * Denormalised fields from the target document — typically `path`, `title`,
      * and any other fields a renderer needs without a round-trip. Populated by
-     * the picker at write time and (eventually) refreshed by an `afterRead`
-     * hook at read time. Treat as advisory; never the source of truth.
+     * the picker at write time and refreshed by the server-side richtext
+     * walker (write-time embed and / or read-time populate). Treat as
+     * advisory; the ID fields are the source of truth.
      */
-    document?: Record<string, any>;
+    document?: D;
 }

package/dist/richtext-field.js

@@ -17,13 +17,7 @@ const RichTextField = ({ field, value, defaultValue, editorConfig, readonly = fa
         ...resolved,
         extensions: defaultExtensionsList()
     };
-    const resolvedEditorConfig = void 0 === field.embedRelationsOnSave ? baseEditorConfig : {
-        ...baseEditorConfig,
-        settings: {
-            ...baseEditorConfig.settings,
-            embedRelationsOnSave: field.embedRelationsOnSave
-        }
-    };
+    const resolvedEditorConfig = baseEditorConfig;
     const labelNode = locale && field.label ? /*#__PURE__*/ jsxs("div", {
         className: classnames('byline-field-richtext-label', richtext_field_module["label-row"]),
         children: [

package/dist/server.d.ts

@@ -6,27 +6,37 @@
  * Copyright (c) Infonomic Company Limited
  */
 /**
- * Server-side entry point for the Lexical adapter — registered into
- * `ServerConfig.fields.richText.populate`. No React, no DOM, no Lexical
- * runtime — safe to import from server-only modules.
+ * Server-side entry points for the Lexical adapter — registered into
+ * `ServerConfig.fields.richText.{ populate, embed }`. No React, no DOM,
+ * no Lexical runtime — safe to import from server-only modules.
+ *
+ * Two factories, one shared visitor pipeline. The visitors themselves
+ * (link, inline-image) don't care whether they're firing on read or
+ * save; what differs is *when* the framework runs them.
  *
  * @example
  * ```ts
  * // apps/webapp/byline/server.config.ts
- * import { lexicalEditorServer } from '@byline/richtext-lexical/server'
+ * import {
+ *   lexicalEditorEmbedServer,
+ *   lexicalEditorPopulateServer,
+ * } from '@byline/richtext-lexical/server'
  * import { defineServerConfig } from '@byline/core'
  * import { getAdminBylineClient } from '@/lib/byline-client'
  *
  * defineServerConfig({
  *   // …
  *   fields: {
- *     richText: { populate: lexicalEditorServer({ getClient: getAdminBylineClient }) },
+ *     richText: {
+ *       embed: lexicalEditorEmbedServer({ getClient: getAdminBylineClient }),
+ *       populate: lexicalEditorPopulateServer({ getClient: getAdminBylineClient }),
+ *     },
  *   },
  * })
  * ```
  */
 import type { BylineClient } from '@byline/client';
-import type { RichTextPopulateFn } from '@byline/core';
+import type { RichTextEmbedFn, RichTextPopulateFn } from '@byline/core';
 import { type LexicalNodeVisitor } from './field/lexical-populate-shared';
 export { defaultEditorConfig } from './field/config/default';
 export { inlineImageVisitor } from './field/extensions/inline-image/populate';
@@ -38,7 +48,7 @@ export interface LexicalServerOptions {
      * Returns the server-side `BylineClient` used to batch-fetch target
      * documents. Typically the host application's cached singleton (e.g.
      * `getAdminBylineClient` in the webapp). Resolved lazily on every
-     * populate call so registration order doesn't matter.
+     * call so registration order doesn't matter.
      */
     getClient: () => BylineClient;
     /**
@@ -48,9 +58,9 @@ export interface LexicalServerOptions {
      * built-ins, or temporarily disable a built-in:
      *
      * ```ts
-     * lexicalEditorServer({
+     * lexicalEditorPopulateServer({
      *   getClient,
-     *   visitors: [inlineImageVisitor, linkVisitor, myCustomEmbedVisitor],
+     *   visitors: [inlineImageVisitor, linkVisitor, myCustomVisitor],
      * })
      * ```
      */
@@ -62,4 +72,18 @@ export interface LexicalServerOptions {
  * invokes this function once per rich-text leaf it discovers in a
  * document tree, gated by each leaf field's `populateRelationsOnRead`.
  */
-export declare function lexicalEditorServer(options: LexicalServerOptions): RichTextPopulateFn;
+export declare function lexicalEditorPopulateServer(options: LexicalServerOptions): RichTextPopulateFn;
+/**
+ * Build the registered `RichTextEmbedFn`. Mirror of
+ * `lexicalEditorPopulateServer` — same visitor pipeline, fires from the
+ * write path instead of the read path. The framework invokes this
+ * function once per rich-text leaf in the outgoing document data,
+ * gated by each leaf field's `embedRelationsOnSave` (default: `true`).
+ *
+ * The visitors mutate `ctx.value` in place (refreshing `document.path`,
+ * `document.title`, and `_resolved` on internal-link nodes; the inline-
+ * image bag on inline-image nodes). The lifecycle write path catches
+ * per-leaf errors and leaves the leaf untouched on hard failure (branch
+ * C of docs/RICHTEXT-LINK-REFACTOR-STRATEGY.md § 3.3).
+ */
+export declare function lexicalEditorEmbedServer(options: LexicalServerOptions): RichTextEmbedFn;

package/dist/server.js

@@ -1,7 +1,23 @@
 import { inlineImageVisitor } from "./field/extensions/inline-image/populate.js";
 import { linkVisitor } from "./field/extensions/link/populate.js";
 import { runLexicalPopulate } from "./field/lexical-populate-shared.js";
-function lexicalEditorServer(options) {
+function lexicalEditorPopulateServer(options) {
+    const visitors = options.visitors ?? [
+        inlineImageVisitor,
+        linkVisitor
+    ];
+    return async (ctx)=>{
+        await runLexicalPopulate({
+            client: options.getClient(),
+            readContext: ctx.readContext,
+            visitors,
+            values: [
+                ctx.value
+            ]
+        });
+    };
+}
+function lexicalEditorEmbedServer(options) {
     const visitors = options.visitors ?? [
         inlineImageVisitor,
         linkVisitor
@@ -18,4 +34,4 @@ function lexicalEditorServer(options) {
     };
 }
 export { defaultEditorConfig } from "./field/config/default.js";
-export { inlineImageVisitor, lexicalEditorServer, linkVisitor };
+export { inlineImageVisitor, lexicalEditorEmbedServer, lexicalEditorPopulateServer, linkVisitor };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "2.4.4",
+  "version": "2.5.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -72,9 +72,9 @@
     "npm-run-all": "^4.1.5",
     "prism-react-renderer": "^2.4.1",
     "react-error-boundary": "^6.1.1",
-    "@byline/core": "2.4.4",
-    "@byline/ui": "2.4.4",
-    "@byline/client": "2.4.4"
+    "@byline/client": "2.5.1",
+    "@byline/ui": "2.5.1",
+    "@byline/core": "2.5.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/field/config/default.ts

@@ -21,7 +21,6 @@ export const DEFAULT_EDITOR_SETTINGS: EditorSettings = {
   },
   inlineImageUploadCollection: 'media',
   placeholderText: 'Enter some rich text...',
-  embedRelationsOnSave: true,
 }
 
 /**

package/src/field/config/types.ts

@@ -29,23 +29,12 @@ export interface EditorSettings {
    */
   inlineImageUploadCollection: string
   placeholderText: string
-  /**
-   * Whether relation-bearing nodes (link, inline-image) embed the picker's
-   * resolved target fields (`title`, `path`, `altText`, `image`, `sizes`)
-   * into the persisted Lexical JSON at modal-save time. Defaults to `true`.
-   *
-   * Mirrors `RichTextField.embedRelationsOnSave`. The lexical wrapper
-   * (`richtext-field.tsx`) merges the field-level value over the resolved
-   * editor settings so each field gets the policy it asked for.
-   */
-  embedRelationsOnSave: boolean
 }
 
 export interface EditorSettingsOverride {
   options?: Partial<Record<OptionName, boolean>>
   inlineImageUploadCollection?: string
   placeholderText?: string
-  embedRelationsOnSave?: boolean
 }
 
 export interface EditorConfig {

package/src/field/extensions/inline-image/inline-image-modal.tsx

@@ -27,7 +27,6 @@ import {
   RelationPicker,
 } from '@byline/ui/react'
 
-import { useEditorConfig } from '../../config/editor-config-context'
 import { useModalFormState } from '../../shared/useModalFormState'
 import { isAltTextValid, positionOptions } from './fields'
 import { deriveImageSizes, getPreferredSize } from './utils'
@@ -71,7 +70,6 @@ export const InlineImageModal: React.FC<InlineImageModalProps> = ({
   const [pickerOpen, setPickerOpen] = useState(false)
   const [altError, setAltError] = useState<string | null>(null)
   const [imageError, setImageError] = useState<string | null>(null)
-  const { config: editorSettings } = useEditorConfig()
 
   const [state, setState] = useModalFormState<FormState>(
     isOpen,
@@ -150,21 +148,13 @@ export const InlineImageModal: React.FC<InlineImageModalProps> = ({
     }
 
     const preferred = getPreferredSize(state.position, pickedImage)
-    // The form-state `documentRelation` always carries `{ title, altText,
-    // image, sizes }` embedded at picker-select time so the modal preview
-    // can render. When `embedRelationsOnSave: false`, strip that envelope
-    // at save so the persisted node only carries the relation primary keys.
-    // Top-level `src` / `width` / `height` / `altText` are kept regardless —
-    // Lexical needs them to render the inline image in the admin editor.
-    const persistedRelation = editorSettings.embedRelationsOnSave
-      ? state.documentRelation
-      : {
-          targetDocumentId: state.documentRelation.targetDocumentId,
-          targetCollectionId: state.documentRelation.targetCollectionId,
-          targetCollectionPath: state.documentRelation.targetCollectionPath,
-        }
+    // Always persist the full `documentRelation` envelope (`{ title,
+    // altText, image, sizes }` embedded at picker-select time). The
+    // server-side write-time walker refreshes this on save; the
+    // editor reads it back to render the inline image without a
+    // round-trip.
     const data: InlineImageData = {
-      documentRelation: persistedRelation,
+      documentRelation: state.documentRelation,
       src: preferred?.url ?? pickedImage.storageUrl ?? '',
       altText: state.altText.trim(),
       position: state.position,

package/src/field/extensions/link/link-modal.tsx

@@ -28,7 +28,6 @@ import {
   type SelectValue,
 } from '@byline/ui/react'
 
-import { useEditorConfig } from '../../config/editor-config-context'
 import { useModalFormState } from '../../shared/useModalFormState'
 import { validateUrl } from '../../utils/url'
 import type { DocumentRelation } from '../../nodes/document-relation'
@@ -109,7 +108,6 @@ export const LinkModal: React.FC<LinkModalProps> = ({
 
   const [pickerOpen, setPickerOpen] = useState(false)
   const [urlError, setUrlError] = useState<string | null>(null)
-  const { config: editorSettings } = useEditorConfig()
 
   const [state, setState] = useModalFormState<FormState>(
     isOpen,
@@ -183,11 +181,11 @@ export const LinkModal: React.FC<LinkModalProps> = ({
     }
 
     const picked = state.picked as DocumentRelation
-    // Persist `picked.document` (the embedded `{ title, path }` envelope)
-    // only when picker-time embedding is enabled. Otherwise the link node
-    // carries the relation primary keys alone, and the registered server
-    // populate adapter is expected to refresh the renderer-facing fields
-    // on read.
+    // Always embed the picker's `{ title, path }` envelope on save —
+    // the in-editor display reads it back to render a label without a
+    // round-trip, and the server-side write-time walker
+    // (`embedRichTextFields` in `@byline/core` + `lexicalEditorEmbedServer`)
+    // refreshes / canonicalises it on persistence.
     const fields: LinkAttributes =
       state.linkType === 'custom'
         ? {
@@ -201,7 +199,7 @@ export const LinkModal: React.FC<LinkModalProps> = ({
             targetDocumentId: picked.targetDocumentId,
             targetCollectionId: picked.targetCollectionId,
             targetCollectionPath: picked.targetCollectionPath,
-            document: editorSettings.embedRelationsOnSave ? picked.document : undefined,
+            document: picked.document,
           }
 
     onSubmit({

package/src/field/extensions/link/populate.ts

@@ -7,18 +7,44 @@
  */
 
 /**
- * Server-side populate visitor for the link plugin. Pure / framework-
- * agnostic — imported only from the package's `server` entry.
+ * Server-side visitor for the link plugin. Pure / framework-agnostic —
+ * imported from the package's `server` entry by both the read-time
+ * populate adapter and the write-time embed adapter. The two modes share
+ * the same visitor; only the trigger point differs.
  *
  * Refreshes `attributes.document` on `link` nodes whose
- * `attributes.linkType` is `'internal'`. Tight projection — `{ title,
- * path }` only, matching what the link modal embeds at picker time.
+ * `attributes.linkType` is `'internal'`. Three branches:
+ *
+ *   - **Found** — sets `document.title` to the target's `useAsTitle`
+ *     field value (falling back to `title` when `useAsTitle` is not
+ *     defined), composes `document.path` via the collection's
+ *     `buildDocumentPath` hook (with `/${collectionPath}/${target.path}`
+ *     as the generic fallback when the hook is absent or returns
+ *     `null`), and clears any prior `document._resolved` flag.
+ *
+ *   - **Hook threw** (branch A) — logs at `info` level and leaves
+ *     `document.path` and `document._resolved` untouched. The picker-
+ *     time embedded value (if any) stays in place; the renderer's
+ *     fallback chain copes.
+ *
+ *   - **Target not found** (branch B) — logs at `warn` level, deletes
+ *     `document.title` and `document.path`, and sets
+ *     `document._resolved = false` so the renderer strips the `<a>`
+ *     wrapper and renders the link's children as plain text. Persisted
+ *     state remains a complete record — re-linking is possible whenever
+ *     the editor returns.
+ *
+ * Hard errors (DB unreachable, transport-level failures) propagate to
+ * the caller — `document-lifecycle` / the read pipeline — which catch
+ * per-field and leave the persisted state untouched (branch C).
  *
  * `linkType: 'custom'` links carry a literal URL and have no relation
  * envelope; they're skipped. Auto-link nodes (`type: 'autolink'`) are
  * also skipped — they're derived from URL patterns and never internal.
  */
 
+import { getCollectionDefinition, getLogger } from '@byline/core'
+
 import type { LexicalNodeLike, LexicalNodeVisitor } from '../../lexical-populate-shared'
 
 export const linkVisitor: LexicalNodeVisitor = {
@@ -30,17 +56,75 @@ export const linkVisitor: LexicalNodeVisitor = {
     const collectionPath = attributes.targetCollectionPath as string | undefined
     const documentId = attributes.targetDocumentId as string | undefined
     if (!collectionPath || !documentId) return null
+
     return {
       node,
       collectionPath,
       documentId,
       apply(target: Record<string, any>) {
+        const definition = getCollectionDefinition(collectionPath)
+        const useAsTitle = definition?.useAsTitle ?? 'title'
         const targetFields = (target.fields ?? {}) as Record<string, any>
-        const path = target.path as string | undefined
-        const title = targetFields.title as string | undefined
         const next: Record<string, any> = { ...(attributes.document ?? {}) }
-        if (typeof title === 'string' && title.length > 0) next.title = title
-        if (typeof path === 'string' && path.length > 0) next.path = path
+
+        // Title — `useAsTitle` lookup with `title` fallback.
+        const title = targetFields[useAsTitle]
+        if (typeof title === 'string' && title.length > 0) {
+          next.title = title
+        }
+
+        // Path — buildDocumentPath, then generic compose fallback.
+        // Branch A: hook threw — leave any existing `document.path`
+        // untouched and surface a log line so operators can find the
+        // bug without it taking the save / read down with it.
+        let pathThrew = false
+        let built: string | null | undefined
+        if (definition?.buildDocumentPath != null) {
+          try {
+            built = definition.buildDocumentPath(
+              {
+                id: target.id as string,
+                path: target.path as string,
+                status: target.status as string,
+                fields: targetFields,
+              },
+              { collectionPath }
+            )
+          } catch (err) {
+            pathThrew = true
+            getLogger().info({ collectionPath, documentId, err }, 'buildDocumentPath threw')
+          }
+        }
+
+        if (!pathThrew) {
+          if (typeof built === 'string') {
+            next.path = built
+          } else {
+            // Generic compose fallback. Only fires when the target has a
+            // non-empty `path` — otherwise we'd produce `/${collectionPath}/`
+            // or `/${collectionPath}/undefined`, both of which are worse
+            // than leaving the previous value alone.
+            const targetPath = target.path as string | undefined
+            if (typeof targetPath === 'string' && targetPath.length > 0) {
+              next.path = `/${collectionPath}/${targetPath}`
+            }
+          }
+        }
+
+        // Found-and-resolved: clear any stale miss flag from a prior pass.
+        if ('_resolved' in next) {
+          delete next._resolved
+        }
+
+        attributes.document = next
+      },
+      applyMissing() {
+        // Branch B — target deleted between picker and walker.
+        getLogger().warn({ collectionPath, documentId }, 'internal link target not found')
+        const next: Record<string, any> = { ...(attributes.document ?? {}) }
+        delete next.title
+        delete next.path
+        next._resolved = false
         attributes.document = next
       },
     }

package/src/field/extensions/link/types.ts

@@ -13,13 +13,43 @@ export interface CustomLinkAttributes extends BaseLinkAttributes {
   url?: string
 }
 
+/**
+ * Denormalised document fields carried on an internal-link node.
+ *
+ *   - `title` — the target document's `useAsTitle` value. Refreshed by the
+ *     server-side link walker (both embed-on-save and populate-on-read
+ *     pipelines) whenever the target resolves.
+ *   - `path` — the canonical renderable path. Has dual meaning during
+ *     migration:
+ *       * with a leading `/` — composed by `CollectionDefinition.buildDocumentPath`
+ *         (or the generic `/${collectionPath}/${slug}` fallback) and
+ *         considered authoritative by the renderer.
+ *       * without a leading `/` — bare slug from `byline_document_paths`,
+ *         either legacy data or a picker-time write that has not yet been
+ *         through the walker. The renderer applies the generic compose
+ *         fallback in that case.
+ *   - `_resolved` — explicitly set to `false` by the walker when the most
+ *     recent pass could not find the target document. Absent (i.e. the
+ *     property is omitted) when the target resolved on the last pass.
+ *     Renderers strip the `<a>` wrapper and render children as plain text
+ *     when this is `false`, preserving editor intent without producing
+ *     a broken anchor on the public site.
+ */
+export interface InternalLinkDocument {
+  title?: string
+  path?: string
+  _resolved?: false
+}
+
 /**
  * Internal link to a Byline document. The relation envelope (`targetDocumentId`,
  * `targetCollectionId`, `targetCollectionPath`, `document`) is flattened
  * directly onto the attributes alongside `linkType` — same shape pattern as
  * the `RelationField` value, no extra wrapper.
  */
-export interface InternalLinkAttributes extends BaseLinkAttributes, DocumentRelation {
+export interface InternalLinkAttributes
+  extends BaseLinkAttributes,
+    DocumentRelation<InternalLinkDocument> {
   linkType: 'internal'
 }
 

package/src/field/lexical-populate-shared.ts

@@ -100,9 +100,18 @@ export interface PendingHydration {
    * Apply the freshly-fetched target document to the node. Mutates `node`
    * in place; `target.fields` is the shaped collection record. Receives
    * the full target so the visitor can pick whatever projection it cares
-   * about.
+   * about. Invoked by the driver only when the target was found.
    */
   apply: (target: Record<string, any>) => void
+  /**
+   * Optional handler invoked by the driver when the target document could
+   * not be fetched — i.e. it was deleted between the picker's write and
+   * this walk. Lets the visitor mark the node with degraded state
+   * (e.g. `document._resolved = false` on internal-link nodes) so the
+   * renderer can react. Omit on visitors that prefer the older "silent
+   * skip" behaviour; the driver no-ops when absent.
+   */
+  applyMissing?: () => void
 }
 
 /**
@@ -131,12 +140,18 @@ interface RunPopulateOptions {
 /**
  * Walk every supplied rich-text value, collect the union of pending
  * hydrations across all visitors, batch-fetch by source collection, and
- * apply. Threading `readContext` keeps the visited-set / `afterReadFired`
- * / read-budget machinery in sync with relation populate and user-land
- * `afterRead` hooks.
+ * apply.
+ *
+ * `readContext` is accepted (factories thread it through from
+ * `RichTextPopulateContext` / `RichTextEmbedContext`) but currently unused —
+ * the batch fetch goes straight to `getDocumentsByDocumentIds` and doesn't
+ * recurse into populate or `afterRead`, so there's no visited-set or
+ * read-budget state to share. Retained on the options shape so a future
+ * visitor that performs nested populate can opt back in without another
+ * contract churn.
  */
 export async function runLexicalPopulate(options: RunPopulateOptions): Promise<void> {
-  const { client, readContext, visitors, values } = options
+  const { client, visitors, values } = options
 
   const pending: PendingHydration[] = []
   for (const value of values) {
@@ -163,18 +178,34 @@ export async function runLexicalPopulate(options: RunPopulateOptions): Promise<v
     bucket.add(p.documentId)
   }
 
+  // Fetch directly through the adapter rather than the client's `find()` —
+  // `parseWhere` has no handler for `id`, so `find({ where: { id: { $in } } })`
+  // silently dropped the filter and returned arbitrary docs ordered by
+  // `created_at desc`. This is the same primitive relation populate uses
+  // (`packages/core/src/services/populate.ts`) when it batches by document id.
   const fetched = new Map<string, Map<string, Record<string, any>>>()
   await Promise.all(
     Array.from(idsByCollection.entries()).map(async ([collectionPath, idSet]) => {
       const ids = Array.from(idSet)
-      const result = await client.collection(collectionPath).find({
-        where: { id: { $in: ids } },
-        pageSize: ids.length,
-        _readContext: readContext,
+      const collectionId = await client.resolveCollectionId(collectionPath)
+      const rawDocs = await client.db.queries.documents.getDocumentsByDocumentIds({
+        collection_id: collectionId,
+        document_ids: ids,
+        readMode: 'published',
       })
       const byId = new Map<string, Record<string, any>>()
-      for (const d of result.docs as Array<Record<string, any>>) {
-        if (typeof d.id === 'string') byId.set(d.id, d)
+      for (const raw of rawDocs as Array<Record<string, any>>) {
+        if (typeof raw.document_id !== 'string') continue
+        // Normalise the raw storage shape (`document_id` / `path` / `status` /
+        // `fields`) to the `{ id, path, status, fields }` shape the visitors
+        // expect — matches the shaped `ClientDocument` the previous `find()`
+        // path returned.
+        byId.set(raw.document_id, {
+          id: raw.document_id,
+          path: raw.path,
+          status: raw.status,
+          fields: raw.fields,
+        })
       }
       fetched.set(collectionPath, byId)
     })
@@ -182,7 +213,10 @@ export async function runLexicalPopulate(options: RunPopulateOptions): Promise<v
 
   for (const p of pending) {
     const target = fetched.get(p.collectionPath)?.get(p.documentId)
-    if (!target) continue
-    p.apply(target)
+    if (target) {
+      p.apply(target)
+    } else {
+      p.applyMissing?.()
+    }
   }
 }

package/src/field/nodes/document-relation.ts

@@ -12,22 +12,29 @@
  * picks). Mirrors the relation-field envelope (`targetDocumentId` /
  * `targetCollectionId`) and adds the human-readable collection `path` plus
  * an optional `document` bag for denormalised fields populated by the picker
- * at write time or by an `afterRead` collection hook at read time.
+ * at write time or by the server-side richtext walker at read / save time.
  *
  * The two ID fields are the source of truth; `targetCollectionPath` is
  * carried alongside because the editor has no field-definition side-channel
  * (unlike a `relation` field) to look up the path from the id at render time.
  * `document` is best-effort — renderers must tolerate it being absent.
+ *
+ * The `document` slot is parameterised by `D` so each node type can pin its
+ * own shape: internal-link nodes pin `{ title?, path?, _resolved?: false }`
+ * (see `InternalLinkAttributes`); inline-image nodes carry image-specific
+ * fields (`title`, `altText`, `image`, `sizes`). Defaults to a loose
+ * `Record<string, any>` so existing call sites continue to compile.
  */
-export interface DocumentRelation {
+export interface DocumentRelation<D extends Record<string, any> = Record<string, any>> {
   targetDocumentId: string
   targetCollectionId: string
   targetCollectionPath: string
   /**
    * Denormalised fields from the target document — typically `path`, `title`,
    * and any other fields a renderer needs without a round-trip. Populated by
-   * the picker at write time and (eventually) refreshed by an `afterRead`
-   * hook at read time. Treat as advisory; never the source of truth.
+   * the picker at write time and refreshed by the server-side richtext
+   * walker (write-time embed and / or read-time populate). Treat as
+   * advisory; the ID fields are the source of truth.
    */
-  document?: Record<string, any>
+  document?: D
 }

package/src/richtext-field.tsx

@@ -84,18 +84,12 @@ export const RichTextField = ({
   const baseEditorConfig: EditorConfig =
     resolved.extensions != null ? resolved : { ...resolved, extensions: defaultExtensionsList() }
 
-  // Adapter-agnostic field-level lever — when present, override the resolved
-  // editor settings so the inline-image / link modals see this field's policy.
-  const resolvedEditorConfig: EditorConfig =
-    field.embedRelationsOnSave === undefined
-      ? baseEditorConfig
-      : {
-          ...baseEditorConfig,
-          settings: {
-            ...baseEditorConfig.settings,
-            embedRelationsOnSave: field.embedRelationsOnSave,
-          },
-        }
+  // `field.embedRelationsOnSave` is a server-side flag — read by the
+  // document-lifecycle write path's richtext embed walker. The client
+  // editor no longer reads it (the modals always embed picker-time
+  // envelopes; the server walker refreshes them on save), so nothing
+  // here needs to propagate the field-level value into `EditorSettings`.
+  const resolvedEditorConfig: EditorConfig = baseEditorConfig
 
   // Assemble the label node here (a Byline-level concern) so that the editor
   // component itself stays free of any Byline-specific dependencies.

package/src/server.ts

@@ -7,28 +7,43 @@
  */
 
 /**
- * Server-side entry point for the Lexical adapter — registered into
- * `ServerConfig.fields.richText.populate`. No React, no DOM, no Lexical
- * runtime — safe to import from server-only modules.
+ * Server-side entry points for the Lexical adapter — registered into
+ * `ServerConfig.fields.richText.{ populate, embed }`. No React, no DOM,
+ * no Lexical runtime — safe to import from server-only modules.
+ *
+ * Two factories, one shared visitor pipeline. The visitors themselves
+ * (link, inline-image) don't care whether they're firing on read or
+ * save; what differs is *when* the framework runs them.
  *
  * @example
  * ```ts
  * // apps/webapp/byline/server.config.ts
- * import { lexicalEditorServer } from '@byline/richtext-lexical/server'
+ * import {
+ *   lexicalEditorEmbedServer,
+ *   lexicalEditorPopulateServer,
+ * } from '@byline/richtext-lexical/server'
  * import { defineServerConfig } from '@byline/core'
  * import { getAdminBylineClient } from '@/lib/byline-client'
  *
  * defineServerConfig({
  *   // …
  *   fields: {
- *     richText: { populate: lexicalEditorServer({ getClient: getAdminBylineClient }) },
+ *     richText: {
+ *       embed: lexicalEditorEmbedServer({ getClient: getAdminBylineClient }),
+ *       populate: lexicalEditorPopulateServer({ getClient: getAdminBylineClient }),
+ *     },
  *   },
  * })
  * ```
  */
 
 import type { BylineClient } from '@byline/client'
-import type { RichTextPopulateContext, RichTextPopulateFn } from '@byline/core'
+import type {
+  RichTextEmbedContext,
+  RichTextEmbedFn,
+  RichTextPopulateContext,
+  RichTextPopulateFn,
+} from '@byline/core'
 
 import { inlineImageVisitor } from './field/extensions/inline-image/populate'
 import { linkVisitor } from './field/extensions/link/populate'
@@ -55,7 +70,7 @@ export interface LexicalServerOptions {
    * Returns the server-side `BylineClient` used to batch-fetch target
    * documents. Typically the host application's cached singleton (e.g.
    * `getAdminBylineClient` in the webapp). Resolved lazily on every
-   * populate call so registration order doesn't matter.
+   * call so registration order doesn't matter.
    */
   getClient: () => BylineClient
   /**
@@ -65,9 +80,9 @@ export interface LexicalServerOptions {
    * built-ins, or temporarily disable a built-in:
    *
    * ```ts
-   * lexicalEditorServer({
+   * lexicalEditorPopulateServer({
    *   getClient,
-   *   visitors: [inlineImageVisitor, linkVisitor, myCustomEmbedVisitor],
+   *   visitors: [inlineImageVisitor, linkVisitor, myCustomVisitor],
    * })
    * ```
    */
@@ -80,7 +95,7 @@ export interface LexicalServerOptions {
  * invokes this function once per rich-text leaf it discovers in a
  * document tree, gated by each leaf field's `populateRelationsOnRead`.
  */
-export function lexicalEditorServer(options: LexicalServerOptions): RichTextPopulateFn {
+export function lexicalEditorPopulateServer(options: LexicalServerOptions): RichTextPopulateFn {
   const visitors = options.visitors ?? [inlineImageVisitor, linkVisitor]
   return async (ctx: RichTextPopulateContext): Promise<void> => {
     await runLexicalPopulate({
@@ -91,3 +106,28 @@ export function lexicalEditorServer(options: LexicalServerOptions): RichTextPopu
     })
   }
 }
+
+/**
+ * Build the registered `RichTextEmbedFn`. Mirror of
+ * `lexicalEditorPopulateServer` — same visitor pipeline, fires from the
+ * write path instead of the read path. The framework invokes this
+ * function once per rich-text leaf in the outgoing document data,
+ * gated by each leaf field's `embedRelationsOnSave` (default: `true`).
+ *
+ * The visitors mutate `ctx.value` in place (refreshing `document.path`,
+ * `document.title`, and `_resolved` on internal-link nodes; the inline-
+ * image bag on inline-image nodes). The lifecycle write path catches
+ * per-leaf errors and leaves the leaf untouched on hard failure (branch
+ * C of docs/RICHTEXT-LINK-REFACTOR-STRATEGY.md § 3.3).
+ */
+export function lexicalEditorEmbedServer(options: LexicalServerOptions): RichTextEmbedFn {
+  const visitors = options.visitors ?? [inlineImageVisitor, linkVisitor]
+  return async (ctx: RichTextEmbedContext): Promise<void> => {
+    await runLexicalPopulate({
+      client: options.getClient(),
+      readContext: ctx.readContext,
+      visitors,
+      values: [ctx.value],
+    })
+  }
+}