@byline/richtext-lexical 2.5.2 → 2.6.1

package/dist/field/editor-field.js

@@ -8,7 +8,9 @@ const EditorComponent = /*#__PURE__*/ lazy(()=>import("./editor-component.js").t
 function EditorField(props) {
     return /*#__PURE__*/ jsx(Suspense, {
         fallback: /*#__PURE__*/ jsx(Shimmer, {
-            height: "35vh"
+            variant: "text",
+            lines: 20,
+            lineHeight: "1.15rem"
         }),
         children: /*#__PURE__*/ jsx(EditorComponent, {
             ...props

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

@@ -1,25 +1,51 @@
-.inline-image-plugin--modal-image {
-  margin-bottom: 2rem;
+.inline-image-modal-picker {
+  align-items: center;
+  gap: .75rem;
+  display: flex;
+}
+
+.inline-image-modal-thumb, .inline-image-modal-thumb-placeholder {
+  border: 1px solid var(--border-color);
+  border-radius: .25rem;
+  flex-shrink: 0;
+  width: 8rem;
+  height: 8rem;
 }
 
-.inline-image-plugin--modal-media-display {
-  margin-bottom: 2em;
+.inline-image-modal-thumb {
+  object-fit: cover;
 }
 
-.inline-image-plugin--modal-alt-text {
-  margin-bottom: 1em;
+.inline-image-modal-thumb-placeholder {
+  background-color: var(--surface-subtle);
+  color: var(--text-subtle);
+  justify-content: center;
+  align-items: center;
+  font-size: .75rem;
+  display: flex;
 }
 
-.inline-image-plugin--modal-position {
-  margin-bottom: 2em;
+.inline-image-modal-picker-details {
+  flex-direction: column;
+  flex: 1;
+  align-items: flex-start;
+  gap: .5rem;
+  min-width: 0;
+  display: flex;
 }
 
-.inline-image-plugin--modal-show-caption {
-  margin-bottom: 1em;
+.inline-image-modal-change-btn {
+  flex-shrink: 0;
+  min-width: 70px;
 }
 
-.inline-image-plugin--modal-actions {
-  gap: 12px;
-  display: flex;
+.inline-image-modal-title {
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  min-width: 0;
+  color: var(--text-subtle);
+  align-self: stretch;
+  font-size: .875rem;
+  overflow: hidden;
 }
 

package/dist/field/extensions/inline-image/inline-image-modal.d.ts

@@ -7,4 +7,5 @@
  */
 import type * as React from 'react';
 import type { InlineImageModalProps } from './types';
+import './inline-image-modal.css';
 export declare const InlineImageModal: React.FC<InlineImageModalProps>;

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

@@ -1,11 +1,13 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
+import { RelationPicker } from "@byline/admin/react";
 import { getCollectionDefinition } from "@byline/core";
-import { Button, Checkbox, CloseIcon, ErrorText, IconButton, Input, Label, Modal, RadioGroup, RadioGroupItem, RelationPicker } from "@byline/ui/react";
+import { Button, Checkbox, CloseIcon, ErrorText, IconButton, Input, Label, Modal, RadioGroup, RadioGroupItem } from "@byline/ui/react";
 import { useModalFormState } from "../../shared/useModalFormState.js";
 import { isAltTextValid, positionOptions } from "./fields.js";
 import { deriveImageSizes, getPreferredSize } from "./utils.js";
+import "./inline-image-modal.css";
 function emptyState() {
     return {
         documentRelation: null,
@@ -23,6 +25,22 @@ function fromInlineImageData(data) {
         showCaption: data.showCaption ?? false
     };
 }
+const LABEL_FIELD_KEYS = [
+    'title',
+    'name',
+    'subject',
+    'label'
+];
+function deriveLabel(fields) {
+    for (const key of LABEL_FIELD_KEYS){
+        const value = fields[key];
+        if ('string' == typeof value && value.trim().length > 0) return value;
+    }
+}
+const PICKER_EXTRA_FIELDS = [
+    'altText',
+    ...LABEL_FIELD_KEYS
+];
 const InlineImageModal = ({ isOpen, collection, data: dataFromProps, onSubmit, onClose })=>{
     const [pickerOpen, setPickerOpen] = useState(false);
     const [altError, setAltError] = useState(null);
@@ -57,7 +75,8 @@ const InlineImageModal = ({ isOpen, collection, data: dataFromProps, onSubmit, o
         const fields = selection.record?.fields ?? {};
         const image = fields.image;
         const title = 'string' == typeof fields.title ? fields.title : void 0;
-        const altTextFromMedia = 'string' == typeof fields.altText ? fields.altText : void 0;
+        const altTextFromMedia = 'string' == typeof fields.altText && fields.altText.trim().length > 0 ? fields.altText : void 0;
+        const derivedLabel = deriveLabel(fields);
         const sizes = image ? deriveImageSizes(image) : [];
         setState((s)=>{
             const document = {};
@@ -73,7 +92,7 @@ const InlineImageModal = ({ isOpen, collection, data: dataFromProps, onSubmit, o
                     targetCollectionPath: collection,
                     document: Object.keys(document).length > 0 ? document : void 0
                 },
-                altText: s.altText.length > 0 ? s.altText : altTextFromMedia ?? ''
+                altText: s.altText.length > 0 ? s.altText : altTextFromMedia ?? derivedLabel ?? ''
             };
         });
         setImageError(null);
@@ -138,28 +157,33 @@ const InlineImageModal = ({ isOpen, collection, data: dataFromProps, onSubmit, o
                                                 children: "Image"
                                             }),
                                             /*#__PURE__*/ jsxs("div", {
-                                                className: "flex items-center gap-3",
+                                                className: "inline-image-modal-picker",
                                                 children: [
                                                     pickedThumbUrl ? /*#__PURE__*/ jsx("img", {
                                                         src: pickedThumbUrl,
                                                         alt: pickedTitle ?? '',
-                                                        className: "w-18 h-18 object-cover rounded border border-gray-700"
+                                                        className: "inline-image-modal-thumb"
                                                     }) : /*#__PURE__*/ jsx("div", {
-                                                        className: "w-18 h-18 flex items-center justify-center bg-gray-800 rounded border border-gray-700 text-xs text-gray-500",
+                                                        className: "inline-image-modal-thumb-placeholder",
                                                         children: "—"
                                                     }),
-                                                    /*#__PURE__*/ jsx(Button, {
-                                                        size: "sm",
-                                                        className: "min-w-[70px]",
-                                                        variant: "outlined",
-                                                        intent: "noeffect",
-                                                        type: "button",
-                                                        onClick: ()=>setPickerOpen(true),
-                                                        children: state.documentRelation ? 'Change image…' : `Pick ${targetDef?.labels.singular ?? 'image'}…`
-                                                    }),
-                                                    pickedTitle && /*#__PURE__*/ jsx("span", {
-                                                        className: "text-sm text-gray-200 truncate",
-                                                        children: pickedTitle
+                                                    /*#__PURE__*/ jsxs("div", {
+                                                        className: "inline-image-modal-picker-details",
+                                                        children: [
+                                                            pickedTitle && /*#__PURE__*/ jsx("span", {
+                                                                className: "inline-image-modal-title",
+                                                                children: pickedTitle
+                                                            }),
+                                                            /*#__PURE__*/ jsx(Button, {
+                                                                size: "sm",
+                                                                className: "inline-image-modal-change-btn",
+                                                                variant: "outlined",
+                                                                intent: "noeffect",
+                                                                type: "button",
+                                                                onClick: ()=>setPickerOpen(true),
+                                                                children: state.documentRelation ? 'Change image…' : `Pick ${targetDef?.labels.singular ?? 'image'}…`
+                                                            })
+                                                        ]
                                                     })
                                                 ]
                                             }),
@@ -253,6 +277,7 @@ const InlineImageModal = ({ isOpen, collection, data: dataFromProps, onSubmit, o
             /*#__PURE__*/ jsx(RelationPicker, {
                 targetCollectionPath: collection,
                 targetDefinition: targetDef,
+                extraSelectFields: PICKER_EXTRA_FIELDS,
                 isOpen: pickerOpen,
                 onSelect: handlePickerSelect,
                 onDismiss: ()=>setPickerOpen(false)

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

@@ -1,8 +1,9 @@
 "use client";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useMemo, useState } from "react";
+import { RelationPicker } from "@byline/admin/react";
 import { getClientConfig, getCollectionDefinition } from "@byline/core";
-import { Button, Checkbox, CloseIcon, IconButton, Input, Label, Modal, RadioGroup, RadioGroupItem, RelationPicker, Select } from "@byline/ui/react";
+import { Button, Checkbox, CloseIcon, IconButton, Input, Label, Modal, RadioGroup, RadioGroupItem, Select } from "@byline/ui/react";
 import { useModalFormState } from "../../shared/useModalFormState.js";
 import { validateUrl } from "../../utils/url.js";
 function emptyState(linkable) {

package/dist/lexical-editor.js

@@ -52,7 +52,9 @@ function EditorPlaceholder() {
         children: /*#__PURE__*/ jsx("div", {
             className: "byline-field-richtext-body",
             children: /*#__PURE__*/ jsx(Shimmer, {
-                height: "35vh"
+                variant: "text",
+                lines: 20,
+                lineHeight: "1.15rem"
             })
         })
     });

package/dist/richtext-field.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import { ErrorText, Label, LocaleBadge, useFieldError, useFieldValue } from "@byline/ui/react";
+import { LocaleBadge, useFieldError, useFieldValue } from "@byline/admin/react";
+import { ErrorText, Label } from "@byline/ui/react";
 import classnames from "classnames";
 import { defaultEditorConfig } from "./field/config/default.js";
 import { defaultExtensionsList } from "./field/config/default-extensions.js";

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "2.5.2",
+  "version": "2.6.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -72,9 +72,10 @@
     "npm-run-all": "^4.1.5",
     "prism-react-renderer": "^2.4.1",
     "react-error-boundary": "^6.1.1",
-    "@byline/client": "2.5.2",
-    "@byline/core": "2.5.2",
-    "@byline/ui": "2.5.2"
+    "@byline/admin": "2.6.1",
+    "@byline/core": "2.6.1",
+    "@byline/client": "2.6.1",
+    "@byline/ui": "2.6.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",
@@ -115,6 +116,7 @@
     "typecheck": "tsc --noEmit",
     "clean": "node scripts/clean.js node_modules dist build types .turbo",
     "lint": "biome check --write --unsafe --diagnostic-level=error",
-    "skip:test": "vitest"
+    "test": "vitest run --mode=node",
+    "test:watch": "vitest --mode=node"
   }
 }

package/src/field/editor-field.tsx

@@ -44,7 +44,7 @@ const EditorComponent = lazy(() =>
 
 export function EditorField(props: EditorFieldProps): React.JSX.Element {
   return (
-    <Suspense fallback={<Shimmer height="35vh" />}>
+    <Suspense fallback={<Shimmer variant="text" lines={20} lineHeight="1.15rem" />}>
       <EditorComponent {...props} />
     </Suspense>
   )

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

@@ -1,29 +1,59 @@
-.inline-image-plugin--modal-image {
-  margin-bottom: 2rem;
-}
+/**
+ * Inline image modal — image picker row.
+ *
+ * Only the picker row (thumbnail + change button + title) needs bespoke
+ * layout; the rest of the modal is composed from shared @byline/ui
+ * components. Colours use the design tokens so the row is theme-aware.
+ */
 
-.inline-image-plugin--modal-actions {
+.inline-image-modal-picker {
   display: flex;
-  gap: 12px;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.inline-image-modal-thumb,
+.inline-image-modal-thumb-placeholder {
+  flex-shrink: 0;
+  width: 8rem;
+  height: 8rem;
+  border-radius: 0.25rem;
+  border: 1px solid var(--border-color);
 }
 
-.inline-image-plugin--modal-media-display {
-  margin-bottom: 2em;
+.inline-image-modal-thumb {
+  object-fit: cover;
 }
 
-.inline-image-plugin--modal-alt-text {
-  margin-bottom: 1em;
+.inline-image-modal-thumb-placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--surface-subtle);
+  color: var(--text-subtle);
+  font-size: 0.75rem;
 }
 
-.inline-image-plugin--modal-position {
-  margin-bottom: 2em;
+.inline-image-modal-picker-details {
+  display: flex;
+  flex: 1;
+  min-width: 0;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.5rem;
 }
 
-.inline-image-plugin--modal-show-caption {
-  margin-bottom: 1em;
+.inline-image-modal-change-btn {
+  flex-shrink: 0;
+  min-width: 70px;
 }
 
-.inline-image-plugin--modal-actions {
-  display: flex;
-  gap: 12px;
+.inline-image-modal-title {
+  align-self: stretch;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-size: 0.875rem;
+  color: var(--text-subtle);
 }

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

@@ -11,6 +11,7 @@
 import type * as React from 'react'
 import { useMemo, useState } from 'react'
 
+import { RelationPicker } from '@byline/admin/react'
 import type { CollectionDefinition, StoredFileValue } from '@byline/core'
 import { getCollectionDefinition } from '@byline/core'
 import {
@@ -24,7 +25,6 @@ import {
   Modal,
   RadioGroup,
   RadioGroupItem,
-  RelationPicker,
 } from '@byline/ui/react'
 
 import { useModalFormState } from '../../shared/useModalFormState'
@@ -34,6 +34,8 @@ import type { DocumentRelation } from '../../nodes/document-relation'
 import type { Position } from './node-types'
 import type { InlineImageData, InlineImageModalProps } from './types'
 
+import './inline-image-modal.css'
+
 interface FormState {
   documentRelation: DocumentRelation | null
   altText: string
@@ -60,6 +62,30 @@ function fromInlineImageData(data: InlineImageData | undefined): FormState {
   }
 }
 
+/**
+ * Human-readable label fields a media/document collection might use, in
+ * priority order. Used only to *seed* the alt-text field when the picked
+ * record has no explicit `altText`. Intentionally excludes filenames — a
+ * label like `IMG_2024.jpg` makes poor alt text. The user can always edit.
+ */
+const LABEL_FIELD_KEYS = ['title', 'name', 'subject', 'label'] as const
+
+function deriveLabel(fields: Record<string, any>): string | undefined {
+  for (const key of LABEL_FIELD_KEYS) {
+    const value = fields[key]
+    if (typeof value === 'string' && value.trim().length > 0) return value
+  }
+  return undefined
+}
+
+/**
+ * Extra fields the relation picker must load (beyond its display columns)
+ * so `handlePickerSelect` can seed the alt-text field: the media's own
+ * `altText`, then the human-readable label fallbacks. Module-level so the
+ * reference is stable across renders (it feeds the picker's fetch effect).
+ */
+const PICKER_EXTRA_FIELDS: string[] = ['altText', ...LABEL_FIELD_KEYS]
+
 export const InlineImageModal: React.FC<InlineImageModalProps> = ({
   isOpen,
   collection,
@@ -110,7 +136,13 @@ export const InlineImageModal: React.FC<InlineImageModalProps> = ({
     const fields = selection.record?.fields ?? {}
     const image = fields.image as StoredFileValue | undefined
     const title = typeof fields.title === 'string' ? fields.title : undefined
-    const altTextFromMedia = typeof fields.altText === 'string' ? fields.altText : undefined
+    // Treat a present-but-blank `altText` as absent so the title fallback
+    // below still applies.
+    const altTextFromMedia =
+      typeof fields.altText === 'string' && fields.altText.trim().length > 0
+        ? fields.altText
+        : undefined
+    const derivedLabel = deriveLabel(fields)
     const sizes = image ? deriveImageSizes(image) : []
 
     setState((s) => {
@@ -128,10 +160,11 @@ export const InlineImageModal: React.FC<InlineImageModalProps> = ({
           targetCollectionPath: collection,
           document: Object.keys(document).length > 0 ? document : undefined,
         },
-        // Pre-fill alt-text from the media's `altText` field on first pick if
-        // the form's alt-text is still empty. Editorial wins over the source
-        // record once the user starts typing.
-        altText: s.altText.length > 0 ? s.altText : (altTextFromMedia ?? ''),
+        // Pre-fill alt-text on first pick when the form's alt-text is still
+        // empty: prefer the media's own `altText`, then fall back to a
+        // human-readable label (title / name / subject / label). Editorial
+        // wins over the source record once the user starts typing.
+        altText: s.altText.length > 0 ? s.altText : (altTextFromMedia ?? derivedLabel ?? ''),
       }
     })
     setImageError(null)
@@ -182,33 +215,31 @@ export const InlineImageModal: React.FC<InlineImageModalProps> = ({
             <div className="flex flex-col gap-4">
               <div className="flex flex-col gap-2">
                 <span className="text-sm font-medium">Image</span>
-                <div className="flex items-center gap-3">
+                <div className="inline-image-modal-picker">
                   {pickedThumbUrl ? (
                     <img
                       src={pickedThumbUrl}
                       alt={pickedTitle ?? ''}
-                      className="w-18 h-18 object-cover rounded border border-gray-700"
+                      className="inline-image-modal-thumb"
                     />
                   ) : (
-                    <div className="w-18 h-18 flex items-center justify-center bg-gray-800 rounded border border-gray-700 text-xs text-gray-500">
-                      —
-                    </div>
-                  )}
-                  <Button
-                    size="sm"
-                    className="min-w-[70px]"
-                    variant="outlined"
-                    intent="noeffect"
-                    type="button"
-                    onClick={() => setPickerOpen(true)}
-                  >
-                    {state.documentRelation
-                      ? 'Change image…'
-                      : `Pick ${targetDef?.labels.singular ?? 'image'}…`}
-                  </Button>
-                  {pickedTitle && (
-                    <span className="text-sm text-gray-200 truncate">{pickedTitle}</span>
+                    <div className="inline-image-modal-thumb-placeholder">—</div>
                   )}
+                  <div className="inline-image-modal-picker-details">
+                    {pickedTitle && <span className="inline-image-modal-title">{pickedTitle}</span>}
+                    <Button
+                      size="sm"
+                      className="inline-image-modal-change-btn"
+                      variant="outlined"
+                      intent="noeffect"
+                      type="button"
+                      onClick={() => setPickerOpen(true)}
+                    >
+                      {state.documentRelation
+                        ? 'Change image…'
+                        : `Pick ${targetDef?.labels.singular ?? 'image'}…`}
+                    </Button>
+                  </div>
                 </div>
                 {imageError && <ErrorText id="image-error" text={imageError} />}
               </div>
@@ -293,6 +324,7 @@ export const InlineImageModal: React.FC<InlineImageModalProps> = ({
       <RelationPicker
         targetCollectionPath={collection}
         targetDefinition={targetDef}
+        extraSelectFields={PICKER_EXTRA_FIELDS}
         isOpen={pickerOpen}
         onSelect={handlePickerSelect}
         onDismiss={() => setPickerOpen(false)}

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

@@ -11,6 +11,7 @@
 import type * as React from 'react'
 import { useMemo, useState } from 'react'
 
+import { RelationPicker } from '@byline/admin/react'
 import type { CollectionDefinition } from '@byline/core'
 import { getClientConfig, getCollectionDefinition } from '@byline/core'
 import {
@@ -23,7 +24,6 @@ import {
   Modal,
   RadioGroup,
   RadioGroupItem,
-  RelationPicker,
   Select,
   type SelectValue,
 } from '@byline/ui/react'

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

@@ -0,0 +1,351 @@
+/**
+ * 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
+ */
+
+/**
+ * Fixture-driven tests for the link visitor's three resolution branches:
+ *
+ *   - Found              — target resolved, `buildDocumentPath` returned a string
+ *   - Found (fallback)   — target resolved, generic `/${collectionPath}/${path}` compose
+ *   - Branch A (threw)   — `buildDocumentPath` raised
+ *   - Branch B (missing) — target deleted between picker and walker
+ *
+ * The visitor itself is framework-agnostic and exercised directly: build
+ * a `LexicalNodeLike`, call `linkVisitor.match(node)`, then invoke the
+ * returned `apply` / `applyMissing` and assert on the mutated `node`.
+ *
+ * Branch C (hard transport failures) is owned by the framework caller
+ * (`embedRichTextFields`) and tested in `packages/core` against that
+ * service — see `richtext-embed.test.node.ts`.
+ */
+
+import { type BylineLogger, type CollectionDefinition, defineServerConfig } from '@byline/core'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { linkVisitor } from './populate'
+import type { LexicalNodeLike } from '../../lexical-populate-shared'
+
+// ---------------------------------------------------------------------------
+// Test harness — logger + config registration
+// ---------------------------------------------------------------------------
+
+function makeLogger(): BylineLogger {
+  return {
+    log: vi.fn(),
+    fatal: vi.fn(),
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    silent: vi.fn(),
+  }
+}
+
+function registerCollection(definition: Partial<CollectionDefinition> & { path: string }): void {
+  defineServerConfig({
+    collections: [
+      {
+        labels: { singular: 'Page', plural: 'Pages' },
+        fields: [{ name: 'title', type: 'text', label: 'Title' }],
+        useAsTitle: 'title',
+        ...definition,
+      } as CollectionDefinition,
+    ],
+  } as Parameters<typeof defineServerConfig>[0])
+}
+
+function clearConfig(): void {
+  // Mirror the config module's globalThis-symbol storage so tests can
+  // register a fresh collection set per case without bleed-over.
+  ;(globalThis as any)[Symbol.for('__byline_server_config__')] = null
+  ;(globalThis as any)[Symbol.for('__byline_client_config__')] = null
+}
+
+function installLogger(logger: BylineLogger): void {
+  // `defineLogger` is not re-exported from `@byline/core`'s root barrel —
+  // setting the symbol directly mirrors what `initBylineCore()` does at
+  // boot and avoids growing the public surface for test wiring.
+  ;(globalThis as any)[Symbol.for('__byline_logger__')] = logger
+}
+
+// ---------------------------------------------------------------------------
+// Node fixtures
+// ---------------------------------------------------------------------------
+
+function makeInternalLinkNode(opts: {
+  documentId?: string
+  collectionPath?: string
+  document?: Record<string, any>
+}): LexicalNodeLike {
+  return {
+    type: 'link',
+    attributes: {
+      linkType: 'internal',
+      targetDocumentId: opts.documentId ?? 'doc-1',
+      targetCollectionPath: opts.collectionPath ?? 'pages',
+      document: opts.document,
+    },
+  }
+}
+
+const targetFixture = {
+  id: 'doc-1',
+  path: 'about',
+  status: 'published',
+  fields: { title: 'About Us', area: 'root' },
+}
+
+// ---------------------------------------------------------------------------
+// Suite
+// ---------------------------------------------------------------------------
+
+describe('linkVisitor', () => {
+  let logger: BylineLogger
+
+  beforeEach(() => {
+    logger = makeLogger()
+    installLogger(logger)
+    clearConfig()
+  })
+
+  afterEach(() => {
+    clearConfig()
+  })
+
+  // -------------------------------------------------------------------------
+  // match() — skip-conditions
+  // -------------------------------------------------------------------------
+
+  describe('match', () => {
+    it('returns null for non-link nodes', () => {
+      const node: LexicalNodeLike = { type: 'paragraph' }
+      expect(linkVisitor.match(node)).toBeNull()
+    })
+
+    it('returns null for custom-URL links', () => {
+      const node: LexicalNodeLike = {
+        type: 'link',
+        attributes: { linkType: 'custom', url: 'https://example.com' },
+      }
+      expect(linkVisitor.match(node)).toBeNull()
+    })
+
+    it('returns null when targetDocumentId is missing', () => {
+      const node: LexicalNodeLike = {
+        type: 'link',
+        attributes: { linkType: 'internal', targetCollectionPath: 'pages' },
+      }
+      expect(linkVisitor.match(node)).toBeNull()
+    })
+
+    it('returns null when targetCollectionPath is missing', () => {
+      const node: LexicalNodeLike = {
+        type: 'link',
+        attributes: { linkType: 'internal', targetDocumentId: 'doc-1' },
+      }
+      expect(linkVisitor.match(node)).toBeNull()
+    })
+
+    it('returns a PendingHydration for a well-formed internal link', () => {
+      registerCollection({ path: 'pages' })
+      const node = makeInternalLinkNode({})
+      const pending = linkVisitor.match(node)
+      expect(pending).not.toBeNull()
+      expect(pending?.collectionPath).toBe('pages')
+      expect(pending?.documentId).toBe('doc-1')
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // apply() — Found branches
+  // -------------------------------------------------------------------------
+
+  describe('apply (found)', () => {
+    it('uses buildDocumentPath when defined and returning a string', () => {
+      registerCollection({
+        path: 'pages',
+        useAsTitle: 'title',
+        buildDocumentPath: (doc) => `/custom/${doc.path}`,
+      })
+      const node = makeInternalLinkNode({})
+      const pending = linkVisitor.match(node)
+      pending?.apply(targetFixture)
+
+      expect(node.attributes?.document).toEqual({
+        title: 'About Us',
+        path: '/custom/about',
+      })
+    })
+
+    it('falls back to generic compose when buildDocumentPath returns null', () => {
+      registerCollection({
+        path: 'pages',
+        useAsTitle: 'title',
+        buildDocumentPath: () => null,
+      })
+      const node = makeInternalLinkNode({})
+      const pending = linkVisitor.match(node)
+      pending?.apply(targetFixture)
+
+      expect(node.attributes?.document?.path).toBe('/pages/about')
+    })
+
+    it('falls back to generic compose when buildDocumentPath is not defined', () => {
+      registerCollection({ path: 'pages', useAsTitle: 'title' })
+      const node = makeInternalLinkNode({})
+      const pending = linkVisitor.match(node)
+      pending?.apply(targetFixture)
+
+      expect(node.attributes?.document?.path).toBe('/pages/about')
+    })
+
+    it('refreshes title from useAsTitle (defaults to "title" when not set)', () => {
+      registerCollection({ path: 'pages' })
+      const node = makeInternalLinkNode({
+        document: { title: 'Stale Title', path: '/stale' },
+      })
+      const pending = linkVisitor.match(node)
+      pending?.apply(targetFixture)
+
+      expect(node.attributes?.document?.title).toBe('About Us')
+    })
+
+    it('honours a custom useAsTitle field', () => {
+      registerCollection({
+        path: 'pages',
+        useAsTitle: 'headline',
+        fields: [
+          { name: 'title', type: 'text', label: 'Title' },
+          { name: 'headline', type: 'text', label: 'Headline' },
+        ],
+      })
+      const node = makeInternalLinkNode({})
+      const pending = linkVisitor.match(node)
+      pending?.apply({
+        ...targetFixture,
+        fields: { title: 'fallback', headline: 'Real Headline' },
+      })
+
+      expect(node.attributes?.document?.title).toBe('Real Headline')
+    })
+
+    it('clears a stale _resolved: false flag when the target is now found', () => {
+      registerCollection({ path: 'pages' })
+      const node = makeInternalLinkNode({
+        document: { _resolved: false },
+      })
+      const pending = linkVisitor.match(node)
+      pending?.apply(targetFixture)
+
+      expect(node.attributes?.document?._resolved).toBeUndefined()
+      expect(node.attributes?.document?.path).toBe('/pages/about')
+    })
+
+    it('leaves path untouched when target.path is empty and no hook is defined', () => {
+      // Generic fallback bails when target.path is empty rather than
+      // emitting `/pages/undefined`.
+      registerCollection({ path: 'pages' })
+      const node = makeInternalLinkNode({
+        document: { title: 'Old', path: '/previous' },
+      })
+      const pending = linkVisitor.match(node)
+      pending?.apply({ ...targetFixture, path: '' })
+
+      expect(node.attributes?.document?.path).toBe('/previous')
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // apply() — Branch A: buildDocumentPath threw
+  // -------------------------------------------------------------------------
+
+  describe('apply (branch A — hook threw)', () => {
+    it('logs at info and leaves document.path untouched', () => {
+      registerCollection({
+        path: 'pages',
+        useAsTitle: 'title',
+        buildDocumentPath: () => {
+          throw new Error('boom')
+        },
+      })
+      const node = makeInternalLinkNode({
+        document: { title: 'Previous', path: '/previous' },
+      })
+      const pending = linkVisitor.match(node)
+      pending?.apply(targetFixture)
+
+      // Path preserved (branch A's whole point).
+      expect(node.attributes?.document?.path).toBe('/previous')
+      // Title still refreshes — only the path resolution failed.
+      expect(node.attributes?.document?.title).toBe('About Us')
+      expect(logger.info).toHaveBeenCalledWith(
+        expect.objectContaining({
+          collectionPath: 'pages',
+          documentId: 'doc-1',
+          err: expect.any(Error),
+        }),
+        'buildDocumentPath threw'
+      )
+    })
+
+    it('does not fall back to generic compose when the hook threw', () => {
+      registerCollection({
+        path: 'pages',
+        buildDocumentPath: () => {
+          throw new Error('boom')
+        },
+      })
+      const node = makeInternalLinkNode({ document: {} })
+      const pending = linkVisitor.match(node)
+      pending?.apply(targetFixture)
+
+      // No path written — neither hook output nor generic fallback fired.
+      expect(node.attributes?.document?.path).toBeUndefined()
+    })
+  })
+
+  // -------------------------------------------------------------------------
+  // applyMissing() — Branch B: target deleted
+  // -------------------------------------------------------------------------
+
+  describe('applyMissing (branch B — target deleted)', () => {
+    it('deletes title and path and sets _resolved: false', () => {
+      registerCollection({ path: 'pages' })
+      const node = makeInternalLinkNode({
+        document: { title: 'Stale', path: '/stale-path' },
+      })
+      const pending = linkVisitor.match(node)
+      pending?.applyMissing?.()
+
+      expect(node.attributes?.document?.title).toBeUndefined()
+      expect(node.attributes?.document?.path).toBeUndefined()
+      expect(node.attributes?.document?._resolved).toBe(false)
+    })
+
+    it('logs at warn level', () => {
+      registerCollection({ path: 'pages' })
+      const node = makeInternalLinkNode({ document: { title: 'Stale' } })
+      const pending = linkVisitor.match(node)
+      pending?.applyMissing?.()
+
+      expect(logger.warn).toHaveBeenCalledWith(
+        { collectionPath: 'pages', documentId: 'doc-1' },
+        'internal link target not found'
+      )
+    })
+
+    it('still produces a usable envelope when no prior document was present', () => {
+      registerCollection({ path: 'pages' })
+      const node = makeInternalLinkNode({})
+      const pending = linkVisitor.match(node)
+      pending?.applyMissing?.()
+
+      expect(node.attributes?.document).toEqual({ _resolved: false })
+    })
+  })
+})

package/src/lexical-editor.tsx

@@ -142,7 +142,7 @@ function EditorPlaceholder() {
   return (
     <div className="byline-field-richtext">
       <div className="byline-field-richtext-body">
-        <Shimmer height="35vh" />
+        <Shimmer variant="text" lines={20} lineHeight="1.15rem" />
       </div>
     </div>
   )

package/src/richtext-field.tsx

@@ -8,8 +8,9 @@
 
 import type React from 'react'
 
+import { LocaleBadge, useFieldError, useFieldValue } from '@byline/admin/react'
 import type { RichTextField as FieldType } from '@byline/core'
-import { ErrorText, Label, LocaleBadge, useFieldError, useFieldValue } from '@byline/ui/react'
+import { ErrorText, Label } from '@byline/ui/react'
 import cx from 'classnames'
 
 import { defaultEditorConfig } from './field/config/default'