@byline/richtext-lexical 6.6.0 → 6.7.1

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

@@ -1,5 +1,16 @@
 import { createInternalLinkHydration } from "../link/populate.js";
 import { deriveImageSizes, getPreferredSize } from "./utils.js";
+const DERIVED_KEYS = [
+    'title',
+    'altText',
+    'image',
+    'sizes'
+];
+function clearPreview(node) {
+    node.src = '';
+    delete node.width;
+    delete node.height;
+}
 const inlineImageVisitor = {
     match (node) {
         if ('inline-image' !== node.type) return null;
@@ -14,22 +25,38 @@ const inlineImageVisitor = {
             apply (target) {
                 const targetFields = target.fields ?? {};
                 const image = targetFields.image;
-                const sizes = image ? deriveImageSizes(image) : [];
                 const next = {
                     ...node.document ?? {}
                 };
+                for (const key of DERIVED_KEYS)delete next[key];
                 if ('string' == typeof targetFields.title) next.title = targetFields.title;
                 if ('string' == typeof targetFields.altText) next.altText = targetFields.altText;
-                if (null != image) next.image = image;
-                if (sizes.length > 0) next.sizes = sizes;
-                node.document = next;
                 const preferred = getPreferredSize(imageNode.position, image);
                 const url = preferred?.url?.trim();
-                if (url) {
+                if (null != image && url) {
+                    const sizes = deriveImageSizes(image);
+                    next.image = image;
+                    if (sizes.length > 0) next.sizes = sizes;
+                    delete next._resolved;
                     imageNode.src = url;
                     if (preferred?.width != null) imageNode.width = preferred.width;
+                    else delete imageNode.width;
                     if (preferred?.height != null) imageNode.height = preferred.height;
+                    else delete imageNode.height;
+                } else {
+                    next._resolved = false;
+                    clearPreview(imageNode);
                 }
+                node.document = next;
+            },
+            applyMissing () {
+                const next = {
+                    ...node.document ?? {}
+                };
+                for (const key of DERIVED_KEYS)delete next[key];
+                next._resolved = false;
+                node.document = next;
+                clearPreview(imageNode);
             }
         };
     }

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

@@ -10,6 +10,7 @@ function createInternalLinkHydration(envelope, collectionPath, documentId) {
             };
             const title = targetFields[useAsTitle];
             if ('string' == typeof title && title.length > 0) next.title = title;
+            else delete next.title;
             let pathThrew = false;
             let built;
             if (definition?.buildDocumentPath != null) try {
@@ -29,12 +30,19 @@ function createInternalLinkHydration(envelope, collectionPath, documentId) {
                     err
                 }, 'buildDocumentPath threw');
             }
-            if (!pathThrew) if ('string' == typeof built) next.path = built;
+            let path;
+            if (!pathThrew) if ('string' == typeof built) path = built;
             else {
                 const targetPath = target.path;
-                if ('string' == typeof targetPath && targetPath.length > 0) next.path = `/${collectionPath}/${targetPath}`;
+                if ('string' == typeof targetPath && targetPath.length > 0) path = `/${collectionPath}/${targetPath}`;
+            }
+            if (null != path) {
+                next.path = path;
+                delete next._resolved;
+            } else {
+                delete next.path;
+                next._resolved = false;
             }
-            if ('_resolved' in next) delete next._resolved;
             envelope.document = next;
         },
         applyMissing () {

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "6.6.0",
+  "version": "6.7.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,11 +79,11 @@
     "clsx": "^2.1.1",
     "lexical": "0.51.0",
     "react-error-boundary": "^6.1.5",
-    "@byline/admin": "6.6.0",
-    "@byline/core": "6.6.0",
-    "@byline/i18n": "6.6.0",
-    "@byline/client": "6.6.0",
-    "@byline/ui": "6.6.0"
+    "@byline/admin": "6.7.1",
+    "@byline/i18n": "6.7.1",
+    "@byline/core": "6.7.1",
+    "@byline/client": "6.7.1",
+    "@byline/ui": "6.7.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/field/extensions/inline-image/populate-link.test.node.ts

@@ -318,3 +318,73 @@ describe('inlineImageLinkVisitor', () => {
     })
   })
 })
+
+describe('inlineImageLinkVisitor never reuses a stale click-through path', () => {
+  beforeEach(() => {
+    installLogger(makeLogger())
+    clearConfig()
+  })
+
+  afterEach(() => {
+    clearConfig()
+  })
+
+  it('marks the click-through unresolved when the path hook throws, without reactivating it', () => {
+    registerCollection({
+      path: 'pages',
+      buildDocumentPath: () => {
+        throw new Error('boom')
+      },
+    })
+    const node = makeLinkedImageNode({
+      ...internalLink,
+      document: { title: 'Stale', path: '/pages/stale', _resolved: false },
+    })
+
+    inlineImageLinkVisitor.match(node)?.apply(linkTarget)
+
+    expect(node.link?.document?.path).toBeUndefined()
+    expect(node.link?.document?._resolved).toBe(false)
+    expect(node.link?.targetDocumentId, 'identity kept').toBe('doc-1')
+  })
+
+  it('marks the click-through unresolved when the target has no usable path', () => {
+    registerCollection({ path: 'pages' })
+    const node = makeLinkedImageNode({ ...internalLink })
+
+    inlineImageLinkVisitor.match(node)?.apply({ ...linkTarget, path: '' })
+
+    expect(node.link?.document?.path).toBeUndefined()
+    expect(node.link?.document?._resolved).toBe(false)
+  })
+
+  it('a missing click-through target does not suppress an independently readable image', async () => {
+    registerCollection({ path: 'pages' })
+    const node = makeLinkedImageNode({ ...internalLink })
+    const readDocuments = vi.fn(async ({ collectionPath }: { collectionPath: string }) =>
+      collectionPath === 'media'
+        ? [
+            {
+              document_id: 'media-1',
+              path: 'm',
+              status: 'published',
+              fields: { image: mediaImage },
+            },
+          ]
+        : []
+    )
+
+    await runLexicalPopulate({
+      readContext: createReadContext(),
+      readDocuments,
+      visitors: [inlineImageVisitor, inlineImageLinkVisitor],
+      values: [{ root: { type: 'root', children: [node] } }],
+    })
+
+    expect(node.link?.document?._resolved).toBe(false)
+    expect(node.link?.document?.path).toBeUndefined()
+    expect(node.document?._resolved).toBeUndefined()
+    expect(node.document?.image).toEqual(mediaImage)
+    expect(node.src).toBe('https://cdn.example.com/media/current-card.avif')
+  })
+})

package/src/field/extensions/inline-image/populate.test.node.ts

@@ -10,6 +10,7 @@ import { createReadContext, type StoredFileValue } from '@byline/core'
 import { describe, expect, it, vi } from 'vitest'
 
 import { type LexicalNodeLike, runLexicalPopulate } from '../../lexical-populate-shared'
+import { lexicalToMarkdown } from '../../markdown/lexical-to-markdown'
 import { inlineImageVisitor } from './populate'
 import type { Position } from './node-types'
 
@@ -172,9 +173,10 @@ describe('inlineImageVisitor', () => {
     })
   })
 
-  describe('never leaves the node emptier than it found it', () => {
-    it('preserves src, width and height when the target cannot be resolved', async () => {
+  describe('never serves a stale image when no current image is available', () => {
+    it('clears the copied image and preview when the target cannot be read', async () => {
       const node = makeNode('left')
+      node.document = { title: 'Stale title', altText: 'Stale alt', image: currentImage }
       const readDocuments = vi.fn().mockResolvedValue([])
 
       await runLexicalPopulate({
@@ -188,36 +190,69 @@ describe('inlineImageVisitor', () => {
         collectionPath: 'media',
         documentIds: ['media-1'],
       })
-      expect(node.src).toBe(STALE_SRC)
-      expect(node.width).toBe(STALE_WIDTH)
-      expect(node.height).toBe(STALE_HEIGHT)
+      expect(node.document).toEqual({ _resolved: false })
+      expect(node.src).toBe('')
+      expect(node.width).toBeUndefined()
+      expect(node.height).toBeUndefined()
+      // Identity and authored state survive.
+      expect(node.targetDocumentId).toBe('media-1')
+      expect(node.position).toBe('left')
+      expect(node.children).toEqual([{ type: 'caption', children: [{ type: 'text' }] }])
     })
 
-    it('preserves the preview when the target resolves without an image', () => {
+    it('clears the copied image and preview when the target resolves without an image', () => {
       const node = makeNode('left')
+      node.document = { title: 'Old', image: currentImage, sizes: [{ name: 'card' }] }
 
       applyTo(node, undefined, 'Current title')
 
-      expect(node.src).toBe(STALE_SRC)
-      expect(node.width).toBe(STALE_WIDTH)
-      expect(node.height).toBe(STALE_HEIGHT)
-      expect(node.document).toEqual(expect.objectContaining({ title: 'Current title' }))
+      expect(node.document).toEqual({ title: 'Current title', _resolved: false })
+      expect(node.src).toBe('')
+      expect(node.width).toBeUndefined()
+      expect(node.height).toBeUndefined()
     })
 
     // Variant-less, so there is no usable variant URL to fall back to and
-    // the original is the only candidate — exactly the case the guard is for.
+    // the original is the only candidate.
     it.each([undefined, '', '   '])(
-      'preserves the preview when the resolved storageUrl is %j',
+      'clears the copied image and preview when the resolved storageUrl is %j',
       (storageUrl) => {
         const node = makeNode('left')
+        node.document = { image: currentImage }
 
         applyTo(node, { ...variantlessImage, storageUrl })
 
-        expect(node.src).toBe(STALE_SRC)
-        expect(node.width).toBe(STALE_WIDTH)
-        expect(node.height).toBe(STALE_HEIGHT)
+        expect(node.document).toEqual({ _resolved: false })
+        expect(node.src).toBe('')
+        expect(node.width).toBeUndefined()
+        expect(node.height).toBeUndefined()
       }
     )
+
+    it('marks a node resolved again once a current image is available', () => {
+      const node = makeNode('left')
+      node.document = { _resolved: false }
+
+      applyTo(node, currentImage)
+
+      expect(node.document?._resolved).toBeUndefined()
+      expect(node.document?.image).toEqual(currentImage)
+      expect(node.src).toBe('https://cdn.example.com/media/current-card.avif')
+    })
+
+    it('exports no stale image to Markdown once the target is unavailable', async () => {
+      const node = { ...makeNode('left'), altText: 'authored alt' }
+      await runLexicalPopulate({
+        readContext: createReadContext(),
+        readDocuments: vi.fn().mockResolvedValue([]),
+        visitors: [inlineImageVisitor],
+        values: [{ root: { type: 'root', children: [node] } }],
+      })
+      const markdown = lexicalToMarkdown({ root: { type: 'root', children: [node] } }).markdown
+
+      expect(markdown).not.toContain(STALE_SRC)
+      expect(node.altText, 'authored alt text is not target data').toBe('authored alt')
+    })
   })
 
   it('is idempotent and leaves unrelated node state untouched', () => {
@@ -235,3 +270,19 @@ describe('inlineImageVisitor', () => {
     expect(node.children).toEqual([{ type: 'caption', children: [{ type: 'text' }] }])
   })
 })
+
+describe('inlineImageVisitor replaces derived values instead of merging them', () => {
+  it('removes a stale title and alt text while a valid current image still renders', () => {
+    const node = makeNode('left')
+    node.document = { title: 'Withheld ES', altText: 'Texto alternativo', caption: 'kept' }
+
+    inlineImageVisitor.match(node)?.apply({ fields: { image: currentImage } })
+
+    expect(node.document).not.toHaveProperty('title')
+    expect(node.document).not.toHaveProperty('altText')
+    expect(node.document?.caption, 'unrelated envelope keys are kept').toBe('kept')
+    expect(node.document?.image).toEqual(currentImage)
+    expect(node.document?._resolved).toBeUndefined()
+    expect(node.src).toBe('https://cdn.example.com/media/current-card.avif')
+  })
+})

package/src/field/extensions/inline-image/populate.ts

@@ -22,9 +22,17 @@
  * fallback), so the refresh must go through it rather than assigning
  * `image.storageUrl` directly — otherwise every save would swap the
  * variant for the full-size original and leave the variant's dimensions
- * describing different bytes. Missing targets, missing images, and
- * blank URLs leave all three fields untouched: the visitor never leaves
- * a node emptier than it found it.
+ * describing different bytes.
+ *
+ * Every copied media value — the envelope's `title`, `altText`, `image` and
+ * `sizes`, and the node's `src` / `width` / `height` — is **replaced, never
+ * merged**. When the media target is missing or denied to this reader, or it
+ * resolves without an image or without a usable URL, the copied image data
+ * and preview are removed and `document._resolved = false` marks the node
+ * unresolved, so no stale image is rendered, serialized or exported to
+ * Markdown. A valid current image still renders when only its title or alt
+ * text is absent. The node's identity, position, authored `altText`, caption
+ * and click-through link are never touched here.
  */
 
 import type { StoredFileValue } from '@byline/core'
@@ -50,6 +58,20 @@ interface InlineImageNodeLike extends LexicalNodeLike {
   link?: LinkAttributes
 }
 
+/** Envelope values copied from the media document on every refresh. */
+const DERIVED_KEYS = ['title', 'altText', 'image', 'sizes'] as const
+
+/**
+ * Remove the copied preview. `src` is a required string on the serialized
+ * node, so it becomes empty (the Markdown serializer and editor already treat
+ * an empty `src` as "no image") rather than being deleted.
+ */
+function clearPreview(node: InlineImageNodeLike): void {
+  node.src = ''
+  delete node.width
+  delete node.height
+}
+
 export const inlineImageVisitor: LexicalNodeVisitor = {
   match(node: LexicalNodeLike) {
     if (node.type !== 'inline-image') return null
@@ -64,20 +86,39 @@ export const inlineImageVisitor: LexicalNodeVisitor = {
       apply(target: Record<string, any>) {
         const targetFields = (target.fields ?? {}) as Record<string, any>
         const image = targetFields.image as StoredFileValue | undefined
-        const sizes = image ? deriveImageSizes(image) : []
         const next: Record<string, any> = { ...(node.document ?? {}) }
+        for (const key of DERIVED_KEYS) delete next[key]
         if (typeof targetFields.title === 'string') next.title = targetFields.title
         if (typeof targetFields.altText === 'string') next.altText = targetFields.altText
-        if (image != null) next.image = image
-        if (sizes.length > 0) next.sizes = sizes
-        node.document = next
+
         const preferred = getPreferredSize(imageNode.position, image)
         const url = preferred?.url?.trim()
-        if (url) {
+        if (image != null && url) {
+          const sizes = deriveImageSizes(image)
+          next.image = image
+          if (sizes.length > 0) next.sizes = sizes
+          delete next._resolved
           imageNode.src = url
           if (preferred?.width != null) imageNode.width = preferred.width
+          else delete imageNode.width
           if (preferred?.height != null) imageNode.height = preferred.height
+          else delete imageNode.height
+        } else {
+          // Resolved without an image, or without a usable URL.
+          next._resolved = false
+          clearPreview(imageNode)
         }
+        node.document = next
+      },
+      applyMissing() {
+        // The media target could not be read (deleted, unpublished, or
+        // denied to this reader). Remove every copied value rather than
+        // serve it as though it were a live resolution.
+        const next: Record<string, any> = { ...(node.document ?? {}) }
+        for (const key of DERIVED_KEYS) delete next[key]
+        next._resolved = false
+        node.document = next
+        clearPreview(imageNode)
       },
     }
   },

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

@@ -26,8 +26,11 @@
 import { type BylineLogger, type CollectionDefinition, defineServerConfig } from '@byline/core'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
+import { lexicalToMarkdown } from '../../markdown/lexical-to-markdown'
+import { resolveLinkHref } from './link-href'
 import { linkVisitor } from './populate'
 import type { LexicalNodeLike } from '../../lexical-populate-shared'
+import type { LinkAttributes } from './types'
 
 // ---------------------------------------------------------------------------
 // Test harness — logger + config registration
@@ -246,9 +249,9 @@ describe('linkVisitor', () => {
       expect(node.attributes?.document?.path).toBe('/pages/about')
     })
 
-    it('leaves path untouched when target.path is empty and no hook is defined', () => {
+    it('marks the link unresolved when target.path is empty and no hook is defined', () => {
       // Generic fallback bails when target.path is empty rather than
-      // emitting `/pages/undefined`.
+      // emitting `/pages/undefined`; the old copied path is not reused.
       registerCollection({ path: 'pages' })
       const node = makeInternalLinkNode({
         document: { title: 'Old', path: '/previous' },
@@ -256,7 +259,9 @@ describe('linkVisitor', () => {
       const pending = linkVisitor.match(node)
       pending?.apply({ ...targetFixture, path: '' })
 
-      expect(node.attributes?.document?.path).toBe('/previous')
+      expect(node.attributes?.document?.path).toBeUndefined()
+      expect(node.attributes?.document?._resolved).toBe(false)
+      expect(resolveLinkHref(node.attributes as LinkAttributes)).toBeNull()
     })
   })
 
@@ -265,7 +270,7 @@ describe('linkVisitor', () => {
   // -------------------------------------------------------------------------
 
   describe('apply (branch A — hook threw)', () => {
-    it('logs at info and leaves document.path untouched', () => {
+    it('logs at info, removes the old path and marks the link unresolved', () => {
       registerCollection({
         path: 'pages',
         useAsTitle: 'title',
@@ -279,8 +284,10 @@ describe('linkVisitor', () => {
       const pending = linkVisitor.match(node)
       pending?.apply(targetFixture)
 
-      // Path preserved (branch A's whole point).
-      expect(node.attributes?.document?.path).toBe('/previous')
+      // The old copied path is never reused: no current path was produced.
+      expect(node.attributes?.document?.path).toBeUndefined()
+      expect(node.attributes?.document?._resolved).toBe(false)
+      expect(resolveLinkHref(node.attributes as LinkAttributes)).toBeNull()
       // Title still refreshes — only the path resolution failed.
       expect(node.attributes?.document?.title).toBe('About Us')
       expect(logger.info).toHaveBeenCalledWith(
@@ -306,6 +313,37 @@ describe('linkVisitor', () => {
 
       // No path written — neither hook output nor generic fallback fired.
       expect(node.attributes?.document?.path).toBeUndefined()
+      expect(node.attributes?.document?._resolved).toBe(false)
+    })
+
+    it('does not reactivate a previously unresolved link with its old path', () => {
+      registerCollection({
+        path: 'pages',
+        buildDocumentPath: () => {
+          throw new Error('boom')
+        },
+      })
+      const node = makeInternalLinkNode({
+        document: { title: 'Old', path: '/stale-path', _resolved: false },
+      })
+      linkVisitor.match(node)?.apply(targetFixture)
+
+      expect(node.attributes?.document?._resolved).toBe(false)
+      expect(node.attributes?.document?.path).toBeUndefined()
+      expect(resolveLinkHref(node.attributes as LinkAttributes)).toBeNull()
+      const markdown = lexicalToMarkdown({
+        root: {
+          type: 'root',
+          children: [
+            {
+              type: 'paragraph',
+              children: [{ ...node, children: [{ type: 'text', text: 'authored text' }] }],
+            },
+          ],
+        },
+      }).markdown
+      expect(markdown).not.toContain('/stale-path')
+      expect(markdown).toContain('authored text')
     })
   })
 
@@ -349,3 +387,50 @@ describe('linkVisitor', () => {
     })
   })
 })
+
+// ---------------------------------------------------------------------------
+// apply() — derived values are replaced, never merged
+// ---------------------------------------------------------------------------
+
+describe('linkVisitor replaces derived values instead of merging them', () => {
+  beforeEach(() => {
+    installLogger(makeLogger())
+    clearConfig()
+    registerCollection({ path: 'pages' })
+  })
+
+  afterEach(() => {
+    clearConfig()
+  })
+
+  it('removes a stale title when the current target result supplies none', () => {
+    // A withheld or redacted title arrives as an absent field; the copy
+    // saved by an earlier refresh must not survive.
+    const node = makeInternalLinkNode({ document: { title: 'Withheld ES', path: '/pages/about' } })
+    linkVisitor.match(node)?.apply({ ...targetFixture, fields: { area: 'root' } })
+
+    expect(node.attributes?.document).not.toHaveProperty('title')
+    expect(node.attributes?.document?.path).toBe('/pages/about')
+  })
+
+  it('replaces a stale title with the current one', () => {
+    const node = makeInternalLinkNode({ document: { title: 'Withheld ES' } })
+    linkVisitor.match(node)?.apply({ ...targetFixture, fields: { title: 'About EN' } })
+
+    expect(node.attributes?.document?.title).toBe('About EN')
+  })
+
+  it('keeps reference identity, authored children and unrelated envelope keys', () => {
+    const node: LexicalNodeLike = {
+      ...makeInternalLinkNode({ document: { title: 'Old', note: 'kept' } }),
+      children: [{ type: 'text', text: 'authored link text' } as LexicalNodeLike],
+    }
+    linkVisitor.match(node)?.apply({ ...targetFixture, fields: {} })
+
+    expect(node.attributes?.targetDocumentId).toBe('doc-1')
+    expect(node.attributes?.targetCollectionPath).toBe('pages')
+    expect(node.attributes?.linkType).toBe('internal')
+    expect(node.attributes?.document?.note).toBe('kept')
+    expect(node.children).toEqual([{ type: 'text', text: 'authored link text' }])
+  })
+})

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

@@ -13,30 +13,34 @@
  * the same visitor; only the trigger point differs.
  *
  * Refreshes `attributes.document` on `link` nodes whose
- * `attributes.linkType` is `'internal'`. Three branches:
+ * `attributes.linkType` is `'internal'`. The copied target values (`title`,
+ * `path`) are **replaced, never merged**: a value the current, permitted
+ * target result does not supply is removed rather than kept from an earlier
+ * copy. The link's identity (`targetDocumentId` / `targetCollectionPath`)
+ * and its authored children are never touched. 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.
+ *   - **Found, path produced** — sets `document.title` from the target's
+ *     `useAsTitle` field (falling back to `title`), or removes it when the
+ *     result has none; sets `document.path` from the collection's
+ *     `buildDocumentPath` hook, or from `/${collectionPath}/${target.path}`
+ *     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.
+ *   - **Found, no path** (branch A) — the hook threw (logged at `info`) or
+ *     no usable path could be composed. The old copied path is removed and
+ *     `document._resolved = false`, so the renderer strips the `<a>` and
+ *     renders the children as plain text. A stale path is never reused, and
+ *     an unresolved link is only reactivated by a path actually produced.
  *
  *   - **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.
+ *     `document._resolved = false`. 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).
+ * Hard reader errors (DB unreachable, transport failures) propagate (branch
+ * C). On a read, the whole read fails, so no stale snapshot is served. On a
+ * save, `document-lifecycle` catches per leaf and leaves the persisted leaf
+ * untouched.
  *
  * `linkType: 'custom'` links carry a literal URL and have no relation
  * envelope; they're skipped. Auto-link nodes (`type: 'autolink'`) are
@@ -76,16 +80,20 @@ export function createInternalLinkHydration(
       const targetFields = (target.fields ?? {}) as Record<string, any>
       const next: Record<string, any> = { ...(envelope.document ?? {}) }
 
-      // Title — `useAsTitle` lookup with `title` fallback.
+      // Title — `useAsTitle` lookup with `title` fallback. Replaced, never
+      // merged: when the current (permitted) target result supplies no title,
+      // a previously copied title is removed rather than kept. A withheld or
+      // redacted translation must not survive as a stale copy.
       const title = targetFields[useAsTitle]
       if (typeof title === 'string' && title.length > 0) {
         next.title = title
+      } else {
+        delete next.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.
+      // Path — buildDocumentPath, then generic compose fallback. A hook that
+      // throws is logged (so operators can find the bug without it taking the
+      // save / read down) and treated as "no path produced" (branch A).
       let pathThrew = false
       let built: string | null | undefined
       if (definition?.buildDocumentPath != null) {
@@ -105,24 +113,29 @@ export function createInternalLinkHydration(
         }
       }
 
+      let path: string | undefined
       if (!pathThrew) {
         if (typeof built === 'string') {
-          next.path = built
+          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.
+          // non-empty `path` — `/${collectionPath}/` or
+          // `/${collectionPath}/undefined` are not usable paths.
           const targetPath = target.path as string | undefined
           if (typeof targetPath === 'string' && targetPath.length > 0) {
-            next.path = `/${collectionPath}/${targetPath}`
+            path = `/${collectionPath}/${targetPath}`
           }
         }
       }
 
-      // Found-and-resolved: clear any stale miss flag from a prior pass.
-      if ('_resolved' in next) {
+      if (path != null) {
+        next.path = path
+        // Found-and-resolved: clear any stale miss flag from a prior pass.
         delete next._resolved
+      } else {
+        // Branch A — no usable current path. Never reuse the old copy.
+        delete next.path
+        next._resolved = false
       }
 
       envelope.document = next

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

@@ -32,3 +32,28 @@ describe('runLexicalPopulate secure reader', () => {
     )
   })
 })
+
+describe('runLexicalPopulate failed refresh', () => {
+  it('rejects without applying, so a stale snapshot is never returned as a live resolution', async () => {
+    const node = { type: 'x', document: { title: 'Stale' } }
+    const apply = vi.fn()
+    const applyMissing = vi.fn()
+    const visitor: LexicalNodeVisitor = {
+      match: (candidate) =>
+        candidate.type === 'x'
+          ? { node: candidate, collectionPath: 'pages', documentId: 'doc-1', apply, applyMissing }
+          : null,
+    }
+
+    await expect(
+      runLexicalPopulate({
+        readContext: createReadContext(),
+        readDocuments: vi.fn().mockRejectedValue(new Error('database unavailable')),
+        visitors: [visitor],
+        values: [{ root: { type: 'root', children: [node] } }],
+      })
+    ).rejects.toThrow('database unavailable')
+    expect(apply).not.toHaveBeenCalled()
+    expect(applyMissing).not.toHaveBeenCalled()
+  })
+})