@byline/richtext-lexical 3.6.0 → 3.8.0

package/dist/field/markdown/lexical-to-markdown.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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
+ */
+export interface LexicalToMarkdownWarning {
+    kind: 'unknown-node' | 'unresolved-link' | 'empty-table';
+    detail: string;
+}
+export interface LexicalToMarkdownOptions {
+    /**
+     * Resolve an internal-link / inline-image relation to a public URL.
+     * Receives the node's flattened relation attributes (`targetCollectionPath`,
+     * `document.path`, …). Return `undefined` to fall back to the default
+     * `/${targetCollectionPath}/${document.path}` composition; the link is
+     * dropped (children kept) when no URL can be derived at all.
+     */
+    resolveInternalUrl?: (attrs: {
+        targetDocumentId?: string;
+        targetCollectionPath?: string;
+        documentPath?: string;
+    }) => string | undefined;
+}
+export interface LexicalToMarkdownResult {
+    markdown: string;
+    warnings: LexicalToMarkdownWarning[];
+}
+/**
+ * Serialize a stored Lexical `SerializedEditorState` (or its `root`) to a
+ * markdown string. Accepts the value as `unknown` because richtext leaves
+ * arrive untyped from storage; non-richtext shapes return an empty string.
+ */
+export declare function lexicalToMarkdown(state: unknown, options?: LexicalToMarkdownOptions): LexicalToMarkdownResult;

package/dist/field/markdown/lexical-to-markdown.js

@@ -0,0 +1,270 @@
+const IS_BOLD = 1;
+const IS_ITALIC = 2;
+const IS_STRIKETHROUGH = 4;
+const IS_CODE = 16;
+const ADMONITION_TO_GFM = {
+    note: 'NOTE',
+    tip: 'TIP',
+    warning: 'WARNING',
+    danger: 'CAUTION'
+};
+function lexicalToMarkdown(state, options = {}) {
+    const warnings = [];
+    const root = resolveRoot(state);
+    if (null == root) return {
+        markdown: '',
+        warnings
+    };
+    const blocks = serializeBlocks(root.children ?? [], {
+        options,
+        warnings
+    });
+    return {
+        markdown: joinBlocks(blocks),
+        warnings
+    };
+}
+function resolveRoot(state) {
+    if (null == state) return null;
+    let value = state;
+    if ('string' == typeof value) try {
+        value = JSON.parse(value);
+    } catch  {
+        return null;
+    }
+    if ('object' != typeof value || null === value) return null;
+    const obj = value;
+    const root = obj.root ?? obj;
+    return 'root' === root.type ? root : null;
+}
+function serializeBlocks(nodes, ctx) {
+    const out = [];
+    for (const node of nodes){
+        const block = serializeBlock(node, ctx);
+        if (null != block && block.length > 0) out.push(block);
+    }
+    return out;
+}
+function joinBlocks(blocks) {
+    return blocks.join('\n\n');
+}
+function serializeBlock(node, ctx) {
+    switch(node.type){
+        case 'paragraph':
+            {
+                const text = serializeInline(node.children ?? [], ctx);
+                return text.trim().length > 0 ? text : null;
+            }
+        case 'heading':
+            {
+                const tag = 'string' == typeof node.tag ? node.tag : 'h2';
+                const level = Math.min(Math.max(Number(tag.slice(1)) || 2, 1), 6);
+                return `${'#'.repeat(level)} ${serializeInline(node.children ?? [], ctx)}`;
+            }
+        case 'list':
+            return serializeList(node, ctx, 0);
+        case 'quote':
+            {
+                const inner = serializeInline(node.children ?? [], ctx);
+                return prefixLines(inner, '> ');
+            }
+        case 'code':
+            return serializeCode(node);
+        case 'table':
+            return serializeTable(node, ctx);
+        case 'horizontalrule':
+            return '---';
+        case 'admonition':
+            return serializeAdmonition(node, ctx);
+        case 'youtube':
+            return 'string' == typeof node.videoID && node.videoID.length > 0 ? `[YouTube video](https://www.youtube.com/watch?v=${node.videoID})` : null;
+        case 'vimeo':
+            return 'string' == typeof node.videoID && node.videoID.length > 0 ? `[Vimeo video](https://vimeo.com/${node.videoID})` : null;
+        case 'layout-container':
+            return joinBlocks(serializeBlocks(node.children ?? [], ctx));
+        case 'layout-item':
+            return joinBlocks(serializeBlocks(node.children ?? [], ctx));
+        case 'inline-image':
+            return serializeImage(node, ctx);
+        default:
+            if (node.children && node.children.length > 0) {
+                ctx.warnings.push({
+                    kind: 'unknown-node',
+                    detail: `unknown block node '${node.type ?? '?'}' — serialized children only`
+                });
+                return joinBlocks(serializeBlocks(node.children, ctx));
+            }
+            ctx.warnings.push({
+                kind: 'unknown-node',
+                detail: `unknown leaf node '${node.type ?? '?'}' — dropped`
+            });
+            return null;
+    }
+}
+function serializeList(node, ctx, depth) {
+    const listType = 'number' === node.listType ? 'number' : node.listType;
+    const lines = [];
+    let ordinal = 1;
+    for (const item of node.children ?? []){
+        if ('listitem' !== item.type) continue;
+        const inlineChildren = (item.children ?? []).filter((c)=>'list' !== c.type);
+        const nestedLists = (item.children ?? []).filter((c)=>'list' === c.type);
+        const marker = 'number' === listType ? `${ordinal}. ` : 'check' === listType ? `- [${true === item.checked ? 'x' : ' '}] ` : '- ';
+        ordinal += 1;
+        const text = serializeInline(inlineChildren, ctx);
+        const indent = '  '.repeat(depth);
+        if (text.trim().length > 0 || 0 === nestedLists.length) lines.push(`${indent}${marker}${text}`);
+        for (const nested of nestedLists)lines.push(serializeList(nested, ctx, depth + 1));
+    }
+    return lines.join('\n');
+}
+function serializeCode(node) {
+    const language = 'string' == typeof node.language ? node.language : '';
+    const parts = [];
+    for (const child of node.children ?? [])if ('linebreak' === child.type) parts.push('\n');
+    else if ('string' == typeof child.text) parts.push(child.text);
+    const body = parts.join('');
+    const longestRun = body.match(/`+/g)?.reduce((m, r)=>Math.max(m, r.length), 0) ?? 0;
+    const fence = '`'.repeat(Math.max(3, longestRun + 1));
+    return `${fence}${language}\n${body}\n${fence}`;
+}
+function serializeTable(node, ctx) {
+    const rows = (node.children ?? []).filter((c)=>'tablerow' === c.type);
+    if (0 === rows.length) {
+        ctx.warnings.push({
+            kind: 'empty-table',
+            detail: 'table with no rows dropped'
+        });
+        return null;
+    }
+    const toCells = (row)=>(row.children ?? []).filter((c)=>'tablecell' === c.type).map((cell)=>serializeInline(cell.children ?? [], ctx).replace(/\|/g, '\\|').trim());
+    const [first, ...rest] = rows;
+    const header = toCells(first);
+    const lines = [
+        `| ${header.join(' | ')} |`,
+        `| ${header.map(()=>'---').join(' | ')} |`,
+        ...rest.map((row)=>`| ${toCells(row).join(' | ')} |`)
+    ];
+    return lines.join('\n');
+}
+function serializeAdmonition(node, ctx) {
+    const gfmType = ADMONITION_TO_GFM[String(node.admonitionType ?? 'note')] ?? 'NOTE';
+    const title = 'string' == typeof node.title && node.title.length > 0 ? node.title : null;
+    const body = joinBlocks(serializeBlocks(node.children ?? [], ctx));
+    const parts = [
+        `[!${gfmType}]`
+    ];
+    if (title) parts.push(`**${title}**`);
+    if (body.length > 0) parts.push(body);
+    return prefixLines(parts.join('\n\n'), '> ');
+}
+function serializeInline(nodes, ctx) {
+    const parts = [];
+    let i = 0;
+    while(i < nodes.length){
+        const node = nodes[i];
+        switch(node.type){
+            case 'text':
+            case 'code-highlight':
+                {
+                    const format = Number(node.format ?? 0);
+                    let text = String(node.text ?? '');
+                    while(i + 1 < nodes.length && nodes[i + 1].type === node.type && Number(nodes[i + 1].format ?? 0) === format){
+                        i += 1;
+                        text += String(nodes[i].text ?? '');
+                    }
+                    parts.push(wrapFormats(text, format));
+                    break;
+                }
+            case 'linebreak':
+                parts.push('\\\n');
+                break;
+            case 'link':
+            case 'autolink':
+                parts.push(serializeLink(node, ctx));
+                break;
+            case 'inline-image':
+                parts.push(serializeImage(node, ctx));
+                break;
+            default:
+                if (node.children && node.children.length > 0) parts.push(serializeInline(node.children, ctx));
+                else if ('string' == typeof node.text) parts.push(escapeText(node.text));
+                else ctx.warnings.push({
+                    kind: 'unknown-node',
+                    detail: `unknown inline node '${node.type ?? '?'}' — dropped`
+                });
+        }
+        i += 1;
+    }
+    return parts.join('');
+}
+function wrapFormats(rawText, format) {
+    if (0 === rawText.length) return '';
+    if (format & IS_CODE) {
+        const longestRun = rawText.match(/`+/g)?.reduce((m, r)=>Math.max(m, r.length), 0) ?? 0;
+        const fence = '`'.repeat(longestRun + 1);
+        return `${fence}${rawText}${fence}`;
+    }
+    const leading = rawText.match(/^\s*/)?.[0] ?? '';
+    const trailing = rawText.match(/\s*$/)?.[0] ?? '';
+    const core = rawText.slice(leading.length, rawText.length - trailing.length);
+    if (0 === core.length) return rawText;
+    let text = escapeText(core);
+    if (format & IS_BOLD) text = `**${text}**`;
+    if (format & IS_ITALIC) text = `*${text}*`;
+    if (format & IS_STRIKETHROUGH) text = `~~${text}~~`;
+    return `${leading}${text}${trailing}`;
+}
+function escapeText(text) {
+    return text.replace(/([\\`*_[\]])/g, '\\$1');
+}
+function serializeLink(node, ctx) {
+    const attrs = node.attributes ?? {};
+    const text = serializeInline(node.children ?? [], ctx);
+    const url = resolveLinkUrl(attrs, ctx);
+    if (null == url) return text;
+    return `[${text}](${url})`;
+}
+function resolveLinkUrl(attrs, ctx) {
+    if ('internal' === attrs.linkType) {
+        const document = attrs.document ?? {};
+        if (false === document._resolved) {
+            ctx.warnings.push({
+                kind: 'unresolved-link',
+                detail: `internal link to ${String(attrs.targetDocumentId ?? '?')} unresolved`
+            });
+            return null;
+        }
+        const documentPath = 'string' == typeof document.path ? document.path : void 0;
+        const custom = ctx.options.resolveInternalUrl?.({
+            targetDocumentId: 'string' == typeof attrs.targetDocumentId ? attrs.targetDocumentId : void 0,
+            targetCollectionPath: 'string' == typeof attrs.targetCollectionPath ? attrs.targetCollectionPath : void 0,
+            documentPath
+        });
+        if (null != custom) return custom;
+        if (null == documentPath) return null;
+        if (documentPath.startsWith('/')) return documentPath;
+        if ('string' == typeof attrs.targetCollectionPath && attrs.targetCollectionPath.length > 0) return `/${attrs.targetCollectionPath}/${documentPath}`;
+        return null;
+    }
+    return 'string' == typeof attrs.url && attrs.url.length > 0 ? attrs.url : null;
+}
+function serializeImage(node, ctx) {
+    const src = 'string' == typeof node.src ? node.src : '';
+    if (0 === src.length) return '';
+    const alt = 'string' == typeof node.altText ? node.altText : '';
+    const image = `![${alt.replace(/[[\]]/g, '')}](${src})`;
+    const caption = node.caption;
+    if (true === node.showCaption && caption?.editorState != null) {
+        const captionRoot = resolveRoot(caption.editorState);
+        if (null != captionRoot) {
+            const captionText = serializeBlocks(captionRoot.children ?? [], ctx).join(' ').trim();
+            if (captionText.length > 0) return `${image}\n*${captionText}*`;
+        }
+    }
+    return image;
+}
+function prefixLines(text, prefix) {
+    return text.split('\n').map((line)=>line.length > 0 ? `${prefix}${line}` : prefix.trimEnd()).join('\n');
+}
+export { lexicalToMarkdown };

package/dist/server.d.ts

@@ -36,9 +36,11 @@
  * ```
  */
 import type { BylineClient } from '@byline/client';
-import type { RichTextEmbedFn, RichTextPopulateFn } from '@byline/core';
+import type { RichTextEmbedFn, RichTextPopulateFn, RichTextToMarkdownFn } from '@byline/core';
 import { type LexicalNodeVisitor } from './field/lexical-populate-shared';
 export { defaultEditorConfig } from './field/config/default';
+export { type LexicalToMarkdownOptions, type LexicalToMarkdownResult, type LexicalToMarkdownWarning, lexicalToMarkdown, } from './field/markdown/lexical-to-markdown';
+import { type LexicalToMarkdownOptions } from './field/markdown/lexical-to-markdown';
 export { inlineImageVisitor } from './field/extensions/inline-image/populate';
 export { linkVisitor } from './field/extensions/link/populate';
 export type { EditorConfig, EditorSettings, EditorSettingsOverride } from './field/config/types';
@@ -86,4 +88,13 @@ export declare function lexicalEditorPopulateServer(options: LexicalServerOption
  * per-leaf errors and leaves the leaf untouched on hard failure (branch
  * C of docs/RICHTEXT-LINK-REFACTOR-STRATEGY.md § 3.3).
  */
+/**
+ * One-way markdown serializer for the agent-readable export surface,
+ * shaped for `ServerConfig.fields.richText.toMarkdown`. The sibling of
+ * `lexicalEditorPopulateServer` / `lexicalEditorEmbedServer` — but pure
+ * and synchronous: it walks the stored editor JSON with
+ * `lexicalToMarkdown` and performs no reads. See that function's header
+ * for the dialect contract (GFM alerts, lossy-OK).
+ */
+export declare function lexicalEditorToMarkdownServer(options?: LexicalToMarkdownOptions): RichTextToMarkdownFn;
 export declare function lexicalEditorEmbedServer(options: LexicalServerOptions): RichTextEmbedFn;

package/dist/server.js

@@ -1,6 +1,7 @@
 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";
+import { lexicalToMarkdown } from "./field/markdown/lexical-to-markdown.js";
 function lexicalEditorPopulateServer(options) {
     const visitors = options.visitors ?? [
         inlineImageVisitor,
@@ -17,6 +18,9 @@ function lexicalEditorPopulateServer(options) {
         });
     };
 }
+function lexicalEditorToMarkdownServer(options = {}) {
+    return (ctx)=>lexicalToMarkdown(ctx.value, options).markdown;
+}
 function lexicalEditorEmbedServer(options) {
     const visitors = options.visitors ?? [
         inlineImageVisitor,
@@ -34,4 +38,4 @@ function lexicalEditorEmbedServer(options) {
     };
 }
 export { defaultEditorConfig } from "./field/config/default.js";
-export { inlineImageVisitor, lexicalEditorEmbedServer, lexicalEditorPopulateServer, linkVisitor };
+export { inlineImageVisitor, lexicalEditorEmbedServer, lexicalEditorPopulateServer, lexicalEditorToMarkdownServer, lexicalToMarkdown, linkVisitor };

package/package.json

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

package/src/field/markdown/lexical-to-markdown.test.node.ts

@@ -0,0 +1,333 @@
+/**
+ * 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
+ */
+
+/**
+ * Contract tests for the one-way Lexical → markdown export serializer.
+ * The expected strings below ARE the format contract — agents build on
+ * this shape, so a change here is a consumer-visible format change and
+ * should be deliberate (see docs/TODO.md → "The output is a contract
+ * surface").
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { lexicalToMarkdown } from './lexical-to-markdown'
+
+// ---------------------------------------------------------------------------
+// Fixture helpers — minimal stored-JSON shapes
+// ---------------------------------------------------------------------------
+
+const text = (t: string, format = 0) => ({
+  type: 'text',
+  text: t,
+  format,
+  detail: 0,
+  mode: 'normal',
+  style: '',
+  version: 1,
+})
+
+const paragraph = (...children: unknown[]) => ({
+  type: 'paragraph',
+  children,
+  direction: 'ltr',
+  format: '',
+  indent: 0,
+  version: 1,
+})
+
+const root = (...children: unknown[]) => ({
+  root: { type: 'root', children, direction: 'ltr', format: '', indent: 0, version: 1 },
+})
+
+const md = (state: unknown) => lexicalToMarkdown(state).markdown
+
+// ---------------------------------------------------------------------------
+
+describe('lexicalToMarkdown — blocks', () => {
+  it('serializes paragraphs separated by blank lines', () => {
+    expect(md(root(paragraph(text('First.')), paragraph(text('Second.'))))).toBe(
+      'First.\n\nSecond.'
+    )
+  })
+
+  it('serializes headings h1–h6 from the tag property', () => {
+    const state = root(
+      { type: 'heading', tag: 'h2', children: [text('Title')], version: 1 },
+      { type: 'heading', tag: 'h4', children: [text('Sub')], version: 1 }
+    )
+    expect(md(state)).toBe('## Title\n\n#### Sub')
+  })
+
+  it('serializes bullet, numbered, and check lists', () => {
+    const item = (t: string, extra: Record<string, unknown> = {}) => ({
+      type: 'listitem',
+      children: [text(t)],
+      version: 1,
+      ...extra,
+    })
+    expect(
+      md(root({ type: 'list', listType: 'bullet', children: [item('a'), item('b')], version: 1 }))
+    ).toBe('- a\n- b')
+    expect(
+      md(root({ type: 'list', listType: 'number', children: [item('a'), item('b')], version: 1 }))
+    ).toBe('1. a\n2. b')
+    expect(
+      md(
+        root({
+          type: 'list',
+          listType: 'check',
+          children: [item('done', { checked: true }), item('todo')],
+          version: 1,
+        })
+      )
+    ).toBe('- [x] done\n- [ ] todo')
+  })
+
+  it('serializes nested lists with indentation', () => {
+    const state = root({
+      type: 'list',
+      listType: 'bullet',
+      version: 1,
+      children: [
+        {
+          type: 'listitem',
+          version: 1,
+          children: [
+            text('outer'),
+            {
+              type: 'list',
+              listType: 'bullet',
+              version: 1,
+              children: [{ type: 'listitem', children: [text('inner')], version: 1 }],
+            },
+          ],
+        },
+      ],
+    })
+    expect(md(state)).toBe('- outer\n  - inner')
+  })
+
+  it('serializes blockquotes', () => {
+    expect(md(root({ type: 'quote', children: [text('wise words')], version: 1 }))).toBe(
+      '> wise words'
+    )
+  })
+
+  it('serializes code blocks with language and code-highlight children', () => {
+    const state = root({
+      type: 'code',
+      language: 'ts',
+      version: 1,
+      children: [
+        { type: 'code-highlight', text: 'const a = 1', version: 1 },
+        { type: 'linebreak', version: 1 },
+        { type: 'code-highlight', text: 'const b = 2', version: 1 },
+      ],
+    })
+    expect(md(state)).toBe('```ts\nconst a = 1\nconst b = 2\n```')
+  })
+
+  it('serializes tables as GFM pipes with the first row as header', () => {
+    const cell = (t: string, headerState = 0) => ({
+      type: 'tablecell',
+      headerState,
+      children: [paragraph(text(t))],
+      version: 1,
+    })
+    const row = (...cells: unknown[]) => ({ type: 'tablerow', children: cells, version: 1 })
+    const state = root({
+      type: 'table',
+      version: 1,
+      children: [row(cell('Name', 1), cell('Age', 1)), row(cell('Ada'), cell('36'))],
+    })
+    expect(md(state)).toBe('| Name | Age |\n| --- | --- |\n| Ada | 36 |')
+  })
+
+  it('serializes horizontal rules', () => {
+    expect(md(root(paragraph(text('a')), { type: 'horizontalrule', version: 1 }))).toBe('a\n\n---')
+  })
+
+  it('serializes admonitions as GFM alerts with bold title', () => {
+    const state = root({
+      type: 'admonition',
+      admonitionType: 'warning',
+      title: 'Careful',
+      version: 1,
+      children: [paragraph(text('Hot surface.'))],
+    })
+    expect(md(state)).toBe('> [!WARNING]\n>\n> **Careful**\n>\n> Hot surface.')
+  })
+
+  it('maps danger to CAUTION and omits an absent title', () => {
+    const state = root({
+      type: 'admonition',
+      admonitionType: 'danger',
+      title: '',
+      version: 1,
+      children: [paragraph(text('Boom.'))],
+    })
+    expect(md(state)).toBe('> [!CAUTION]\n>\n> Boom.')
+  })
+
+  it('serializes video embeds as links', () => {
+    expect(md(root({ type: 'youtube', videoID: 'abc123', version: 1 }))).toBe(
+      '[YouTube video](https://www.youtube.com/watch?v=abc123)'
+    )
+    expect(md(root({ type: 'vimeo', videoID: '987', version: 1 }))).toBe(
+      '[Vimeo video](https://vimeo.com/987)'
+    )
+  })
+
+  it('flattens layout columns to stacked sections', () => {
+    const state = root({
+      type: 'layout-container',
+      templateColumns: '1fr 1fr',
+      version: 1,
+      children: [
+        { type: 'layout-item', children: [paragraph(text('left'))], version: 1 },
+        { type: 'layout-item', children: [paragraph(text('right'))], version: 1 },
+      ],
+    })
+    expect(md(state)).toBe('left\n\nright')
+  })
+
+  it('serializes unknown block nodes via their children with a warning', () => {
+    const result = lexicalToMarkdown(
+      root({ type: 'future-node', children: [paragraph(text('still here'))], version: 1 })
+    )
+    expect(result.markdown).toBe('still here')
+    expect(result.warnings).toContainEqual(expect.objectContaining({ kind: 'unknown-node' }))
+  })
+})
+
+describe('lexicalToMarkdown — inline', () => {
+  it('decodes the format bitmask', () => {
+    expect(md(root(paragraph(text('bold', 1))))).toBe('**bold**')
+    expect(md(root(paragraph(text('italic', 2))))).toBe('*italic*')
+    expect(md(root(paragraph(text('both', 3))))).toBe('***both***')
+    expect(md(root(paragraph(text('struck', 4))))).toBe('~~struck~~')
+    expect(md(root(paragraph(text('code()', 16))))).toBe('`code()`')
+  })
+
+  it('drops underline/highlight wrappers but keeps the text (lossy-OK)', () => {
+    expect(md(root(paragraph(text('plain', 8))))).toBe('plain')
+    expect(md(root(paragraph(text('plain', 128))))).toBe('plain')
+  })
+
+  it('merges consecutive text nodes sharing a format', () => {
+    expect(md(root(paragraph(text('bo', 1), text('ld', 1), text(' plain'))))).toBe('**bold** plain')
+  })
+
+  it('hoists whitespace outside emphasis markers', () => {
+    expect(md(root(paragraph(text('a'), text(' spaced ', 1), text('b'))))).toBe('a **spaced** b')
+  })
+
+  it('escapes markdown-significant characters in plain text', () => {
+    expect(md(root(paragraph(text('2 * 3 [not a link]'))))).toBe('2 \\* 3 \\[not a link\\]')
+  })
+
+  it('does not escape inside inline code', () => {
+    expect(md(root(paragraph(text('a * b', 16))))).toBe('`a * b`')
+  })
+
+  it('serializes custom links', () => {
+    const link = {
+      type: 'link',
+      attributes: { linkType: 'custom', url: 'https://example.com' },
+      children: [text('Example')],
+      version: 1,
+    }
+    expect(md(root(paragraph(link)))).toBe('[Example](https://example.com)')
+  })
+
+  it('composes internal link URLs from the embedded document envelope', () => {
+    const link = {
+      type: 'link',
+      attributes: {
+        linkType: 'internal',
+        targetDocumentId: 'doc-1',
+        targetCollectionPath: 'news',
+        document: { title: 'A Post', path: 'a-post', _resolved: true },
+      },
+      children: [text('A Post')],
+      version: 1,
+    }
+    expect(md(root(paragraph(link)))).toBe('[A Post](/news/a-post)')
+  })
+
+  it('prefers the resolveInternalUrl callback for internal links', () => {
+    const link = {
+      type: 'link',
+      attributes: {
+        linkType: 'internal',
+        targetCollectionPath: 'news',
+        document: { path: 'a-post', _resolved: true },
+      },
+      children: [text('A Post')],
+      version: 1,
+    }
+    const result = lexicalToMarkdown(root(paragraph(link)), {
+      resolveInternalUrl: ({ targetCollectionPath, documentPath }) =>
+        `https://example.org/${targetCollectionPath}/${documentPath}.md`,
+    })
+    expect(result.markdown).toBe('[A Post](https://example.org/news/a-post.md)')
+  })
+
+  it('keeps the text and drops the link when an internal target is unresolved', () => {
+    const link = {
+      type: 'link',
+      attributes: {
+        linkType: 'internal',
+        targetDocumentId: 'gone',
+        document: { _resolved: false },
+      },
+      children: [text('Missing')],
+      version: 1,
+    }
+    const result = lexicalToMarkdown(root(paragraph(link)))
+    expect(result.markdown).toBe('Missing')
+    expect(result.warnings).toContainEqual(expect.objectContaining({ kind: 'unresolved-link' }))
+  })
+
+  it('serializes inline images with alt text and flattened caption', () => {
+    const image = {
+      type: 'inline-image',
+      src: '/uploads/media/photo.avif',
+      altText: 'A photo',
+      showCaption: true,
+      caption: { editorState: root(paragraph(text('Taken in 2026.'))) },
+      version: 1,
+    }
+    expect(md(root(paragraph(image)))).toBe(
+      '![A photo](/uploads/media/photo.avif)\n*Taken in 2026.*'
+    )
+  })
+
+  it('serializes hard line breaks', () => {
+    expect(
+      md(root(paragraph(text('line one'), { type: 'linebreak', version: 1 }, text('line two'))))
+    ).toBe('line one\\\nline two')
+  })
+})
+
+describe('lexicalToMarkdown — robustness', () => {
+  it('returns empty for null, non-richtext shapes, and bad JSON strings', () => {
+    expect(md(null)).toBe('')
+    expect(md({ not: 'lexical' })).toBe('')
+    expect(md('not json')).toBe('')
+  })
+
+  it('accepts a stringified editor state', () => {
+    expect(md(JSON.stringify(root(paragraph(text('parsed')))))).toBe('parsed')
+  })
+
+  it('skips empty paragraphs', () => {
+    expect(md(root(paragraph(), paragraph(text('only')), paragraph()))).toBe('only')
+  })
+})

package/src/field/markdown/lexical-to-markdown.ts

@@ -0,0 +1,446 @@
+/**
+ * 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
+ */
+
+/**
+ * One-way Lexical → markdown serializer for the agent-readable export
+ * surface (`.md` routes, `llms.txt` — see docs/TODO.md → markdown export).
+ *
+ * Walks the **stored** `SerializedEditorState` JSON directly — no
+ * `@lexical/headless`, no DOM, no node registration. Output is read-only
+ * and never re-imported, so *lossy is acceptable* by design: layout
+ * columns flatten to stacked sections, video embeds become links,
+ * underline/highlight/sub/superscript inline formats are dropped.
+ *
+ * This is deliberately NOT the editor's markdown source toggle
+ * (`./transformers.ts` / `BYLINE_TRANSFORMERS`), which needs bidirectional,
+ * lossless `:::`-dialect transformers running inside a Lexical editor.
+ * One asymmetry to know about: admonitions export as GFM alerts
+ * (`> [!NOTE]`), while the editor toggle and the docs importer
+ * (`apps/webapp/byline/scripts/lib/parse-markdown.ts`) speak the
+ * Docusaurus `:::type[Title]` dialect. GFM alerts are what GitHub,
+ * agents, and most renderers understand — the export optimises for them.
+ *
+ * Node coverage mirrors the render serializer
+ * (`apps/webapp/src/ui/byline/components/richtext-lexical/serialize/`):
+ * paragraph, heading, list (bullet/number/check, nested), quote, code
+ * (+ code-highlight/linebreak children), table (GFM pipes), link/autolink
+ * (custom + internal), horizontalrule, linebreak, text (format bitmask),
+ * admonition, inline-image (+ nested caption editor), youtube, vimeo,
+ * layout-container/layout-item (flattened). Unknown node types emit a
+ * warning and serialize their children, so new nodes degrade gracefully
+ * instead of disappearing.
+ */
+
+// Text format bitmask — Lexical convention, kept in sync with the render
+// serializer's richtext-node-formats.ts and the importer's mdast mapper.
+const IS_BOLD = 1
+const IS_ITALIC = 1 << 1
+const IS_STRIKETHROUGH = 1 << 2
+// IS_UNDERLINE (1 << 3), IS_SUBSCRIPT (1 << 5), IS_SUPERSCRIPT (1 << 6),
+// IS_HIGHLIGHT (1 << 7) have no portable markdown form — dropped (lossy-OK).
+const IS_CODE = 1 << 4
+
+type AnyNode = {
+  type?: string
+  children?: AnyNode[]
+  [k: string]: unknown
+}
+
+export interface LexicalToMarkdownWarning {
+  kind: 'unknown-node' | 'unresolved-link' | 'empty-table'
+  detail: string
+}
+
+export interface LexicalToMarkdownOptions {
+  /**
+   * Resolve an internal-link / inline-image relation to a public URL.
+   * Receives the node's flattened relation attributes (`targetCollectionPath`,
+   * `document.path`, …). Return `undefined` to fall back to the default
+   * `/${targetCollectionPath}/${document.path}` composition; the link is
+   * dropped (children kept) when no URL can be derived at all.
+   */
+  resolveInternalUrl?: (attrs: {
+    targetDocumentId?: string
+    targetCollectionPath?: string
+    documentPath?: string
+  }) => string | undefined
+}
+
+export interface LexicalToMarkdownResult {
+  markdown: string
+  warnings: LexicalToMarkdownWarning[]
+}
+
+/** GFM alert labels per Byline admonition type. */
+const ADMONITION_TO_GFM: Record<string, string> = {
+  note: 'NOTE',
+  tip: 'TIP',
+  warning: 'WARNING',
+  danger: 'CAUTION',
+}
+
+/**
+ * Serialize a stored Lexical `SerializedEditorState` (or its `root`) to a
+ * markdown string. Accepts the value as `unknown` because richtext leaves
+ * arrive untyped from storage; non-richtext shapes return an empty string.
+ */
+export function lexicalToMarkdown(
+  state: unknown,
+  options: LexicalToMarkdownOptions = {}
+): LexicalToMarkdownResult {
+  const warnings: LexicalToMarkdownWarning[] = []
+  const root = resolveRoot(state)
+  if (root == null) return { markdown: '', warnings }
+  const blocks = serializeBlocks(root.children ?? [], { options, warnings })
+  return { markdown: joinBlocks(blocks), warnings }
+}
+
+interface Ctx {
+  options: LexicalToMarkdownOptions
+  warnings: LexicalToMarkdownWarning[]
+}
+
+function resolveRoot(state: unknown): AnyNode | null {
+  if (state == null) return null
+  let value: unknown = state
+  // Tolerate stringified editor state (older rows / defensive).
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value)
+    } catch {
+      return null
+    }
+  }
+  if (typeof value !== 'object' || value === null) return null
+  const obj = value as Record<string, unknown>
+  const root = (obj.root ?? obj) as AnyNode
+  return root.type === 'root' ? root : null
+}
+
+/** Serialize a list of block-level nodes; empty results are dropped. */
+function serializeBlocks(nodes: AnyNode[], ctx: Ctx): string[] {
+  const out: string[] = []
+  for (const node of nodes) {
+    const block = serializeBlock(node, ctx)
+    if (block != null && block.length > 0) out.push(block)
+  }
+  return out
+}
+
+function joinBlocks(blocks: string[]): string {
+  return blocks.join('\n\n')
+}
+
+function serializeBlock(node: AnyNode, ctx: Ctx): string | null {
+  switch (node.type) {
+    case 'paragraph': {
+      const text = serializeInline(node.children ?? [], ctx)
+      return text.trim().length > 0 ? text : null
+    }
+    case 'heading': {
+      const tag = typeof node.tag === 'string' ? node.tag : 'h2'
+      const level = Math.min(Math.max(Number(tag.slice(1)) || 2, 1), 6)
+      return `${'#'.repeat(level)} ${serializeInline(node.children ?? [], ctx)}`
+    }
+    case 'list':
+      return serializeList(node, ctx, 0)
+    case 'quote': {
+      const inner = serializeInline(node.children ?? [], ctx)
+      return prefixLines(inner, '> ')
+    }
+    case 'code':
+      return serializeCode(node)
+    case 'table':
+      return serializeTable(node, ctx)
+    case 'horizontalrule':
+      return '---'
+    case 'admonition':
+      return serializeAdmonition(node, ctx)
+    case 'youtube':
+      return typeof node.videoID === 'string' && node.videoID.length > 0
+        ? `[YouTube video](https://www.youtube.com/watch?v=${node.videoID})`
+        : null
+    case 'vimeo':
+      return typeof node.videoID === 'string' && node.videoID.length > 0
+        ? `[Vimeo video](https://vimeo.com/${node.videoID})`
+        : null
+    case 'layout-container':
+      // Columns flatten to stacked sections (lossy-OK by design).
+      return joinBlocks(serializeBlocks(node.children ?? [], ctx))
+    case 'layout-item':
+      return joinBlocks(serializeBlocks(node.children ?? [], ctx))
+    case 'inline-image':
+      // An image can appear at block position (sole child of the root).
+      return serializeImage(node, ctx)
+    default: {
+      if (node.children && node.children.length > 0) {
+        ctx.warnings.push({
+          kind: 'unknown-node',
+          detail: `unknown block node '${node.type ?? '?'}' — serialized children only`,
+        })
+        return joinBlocks(serializeBlocks(node.children, ctx))
+      }
+      ctx.warnings.push({
+        kind: 'unknown-node',
+        detail: `unknown leaf node '${node.type ?? '?'}' — dropped`,
+      })
+      return null
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lists
+// ---------------------------------------------------------------------------
+
+function serializeList(node: AnyNode, ctx: Ctx, depth: number): string {
+  const listType = node.listType === 'number' ? 'number' : node.listType
+  const lines: string[] = []
+  let ordinal = 1
+  for (const item of node.children ?? []) {
+    if (item.type !== 'listitem') continue
+    // A list item whose children include a nested list renders the nested
+    // list on subsequent indented lines.
+    const inlineChildren = (item.children ?? []).filter((c) => c.type !== 'list')
+    const nestedLists = (item.children ?? []).filter((c) => c.type === 'list')
+
+    const marker =
+      listType === 'number'
+        ? `${ordinal}. `
+        : listType === 'check'
+          ? `- [${item.checked === true ? 'x' : ' '}] `
+          : '- '
+    ordinal += 1
+
+    const text = serializeInline(inlineChildren, ctx)
+    const indent = '  '.repeat(depth)
+    if (text.trim().length > 0 || nestedLists.length === 0) {
+      lines.push(`${indent}${marker}${text}`)
+    }
+    for (const nested of nestedLists) {
+      lines.push(serializeList(nested, ctx, depth + 1))
+    }
+  }
+  return lines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Code blocks
+// ---------------------------------------------------------------------------
+
+function serializeCode(node: AnyNode): string {
+  const language = typeof node.language === 'string' ? node.language : ''
+  const parts: string[] = []
+  for (const child of node.children ?? []) {
+    if (child.type === 'linebreak') {
+      parts.push('\n')
+    } else if (typeof child.text === 'string') {
+      // code-highlight and plain text children both carry `.text`.
+      parts.push(child.text)
+    }
+  }
+  const body = parts.join('')
+  // Grow the fence beyond any backtick run inside the code itself.
+  const longestRun = body.match(/`+/g)?.reduce((m, r) => Math.max(m, r.length), 0) ?? 0
+  const fence = '`'.repeat(Math.max(3, longestRun + 1))
+  return `${fence}${language}\n${body}\n${fence}`
+}
+
+// ---------------------------------------------------------------------------
+// Tables (GFM pipes)
+// ---------------------------------------------------------------------------
+
+function serializeTable(node: AnyNode, ctx: Ctx): string | null {
+  const rows = (node.children ?? []).filter((c) => c.type === 'tablerow')
+  if (rows.length === 0) {
+    ctx.warnings.push({ kind: 'empty-table', detail: 'table with no rows dropped' })
+    return null
+  }
+  const toCells = (row: AnyNode): string[] =>
+    (row.children ?? [])
+      .filter((c) => c.type === 'tablecell')
+      .map((cell) =>
+        serializeInline(cell.children ?? [], ctx)
+          .replace(/\|/g, '\\|')
+          .trim()
+      )
+
+  const [first, ...rest] = rows
+  const header = toCells(first as AnyNode)
+  const lines = [
+    `| ${header.join(' | ')} |`,
+    `| ${header.map(() => '---').join(' | ')} |`,
+    ...rest.map((row) => `| ${toCells(row).join(' | ')} |`),
+  ]
+  return lines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Admonitions → GFM alerts
+// ---------------------------------------------------------------------------
+
+function serializeAdmonition(node: AnyNode, ctx: Ctx): string {
+  const gfmType = ADMONITION_TO_GFM[String(node.admonitionType ?? 'note')] ?? 'NOTE'
+  const title = typeof node.title === 'string' && node.title.length > 0 ? node.title : null
+  const body = joinBlocks(serializeBlocks(node.children ?? [], ctx))
+  const parts = [`[!${gfmType}]`]
+  if (title) parts.push(`**${title}**`)
+  if (body.length > 0) parts.push(body)
+  return prefixLines(parts.join('\n\n'), '> ')
+}
+
+// ---------------------------------------------------------------------------
+// Inline serialization
+// ---------------------------------------------------------------------------
+
+function serializeInline(nodes: AnyNode[], ctx: Ctx): string {
+  const parts: string[] = []
+  let i = 0
+  while (i < nodes.length) {
+    const node = nodes[i] as AnyNode
+    switch (node.type) {
+      case 'text':
+      case 'code-highlight': {
+        // Group consecutive text nodes sharing one format so `**bold**`
+        // doesn't fragment into `**bo****ld**`.
+        const format = Number(node.format ?? 0)
+        let text = String(node.text ?? '')
+        while (
+          i + 1 < nodes.length &&
+          (nodes[i + 1] as AnyNode).type === node.type &&
+          Number((nodes[i + 1] as AnyNode).format ?? 0) === format
+        ) {
+          i += 1
+          text += String((nodes[i] as AnyNode).text ?? '')
+        }
+        parts.push(wrapFormats(text, format))
+        break
+      }
+      case 'linebreak':
+        parts.push('\\\n')
+        break
+      case 'link':
+      case 'autolink':
+        parts.push(serializeLink(node, ctx))
+        break
+      case 'inline-image':
+        parts.push(serializeImage(node, ctx))
+        break
+      default: {
+        if (node.children && node.children.length > 0) {
+          parts.push(serializeInline(node.children, ctx))
+        } else if (typeof node.text === 'string') {
+          parts.push(escapeText(node.text))
+        } else {
+          ctx.warnings.push({
+            kind: 'unknown-node',
+            detail: `unknown inline node '${node.type ?? '?'}' — dropped`,
+          })
+        }
+      }
+    }
+    i += 1
+  }
+  return parts.join('')
+}
+
+function wrapFormats(rawText: string, format: number): string {
+  if (rawText.length === 0) return ''
+  // Inline code suppresses every other wrapper and is not escaped.
+  if (format & IS_CODE) {
+    const longestRun = rawText.match(/`+/g)?.reduce((m, r) => Math.max(m, r.length), 0) ?? 0
+    const fence = '`'.repeat(longestRun + 1)
+    return `${fence}${rawText}${fence}`
+  }
+  // Markdown emphasis does not survive leading/trailing whitespace inside
+  // the markers — hoist it outside.
+  const leading = rawText.match(/^\s*/)?.[0] ?? ''
+  const trailing = rawText.match(/\s*$/)?.[0] ?? ''
+  const core = rawText.slice(leading.length, rawText.length - trailing.length)
+  if (core.length === 0) return rawText
+  let text = escapeText(core)
+  if (format & IS_BOLD) text = `**${text}**`
+  if (format & IS_ITALIC) text = `*${text}*`
+  if (format & IS_STRIKETHROUGH) text = `~~${text}~~`
+  return `${leading}${text}${trailing}`
+}
+
+/**
+ * Conservative escaping of characters that would otherwise activate
+ * markdown syntax mid-sentence. Deliberately light — over-escaping makes
+ * the output unreadable, and the export is lossy-by-contract.
+ */
+function escapeText(text: string): string {
+  return text.replace(/([\\`*_[\]])/g, '\\$1')
+}
+
+function serializeLink(node: AnyNode, ctx: Ctx): string {
+  const attrs = (node.attributes ?? {}) as Record<string, unknown>
+  const text = serializeInline(node.children ?? [], ctx)
+  const url = resolveLinkUrl(attrs, ctx)
+  if (url == null) {
+    // Unresolved / unresolvable internal link: keep the text, drop the link.
+    return text
+  }
+  return `[${text}](${url})`
+}
+
+function resolveLinkUrl(attrs: Record<string, unknown>, ctx: Ctx): string | null {
+  if (attrs.linkType === 'internal') {
+    const document = (attrs.document ?? {}) as Record<string, unknown>
+    if (document._resolved === false) {
+      ctx.warnings.push({
+        kind: 'unresolved-link',
+        detail: `internal link to ${String(attrs.targetDocumentId ?? '?')} unresolved`,
+      })
+      return null
+    }
+    const documentPath = typeof document.path === 'string' ? document.path : undefined
+    const custom = ctx.options.resolveInternalUrl?.({
+      targetDocumentId:
+        typeof attrs.targetDocumentId === 'string' ? attrs.targetDocumentId : undefined,
+      targetCollectionPath:
+        typeof attrs.targetCollectionPath === 'string' ? attrs.targetCollectionPath : undefined,
+      documentPath,
+    })
+    if (custom != null) return custom
+    if (documentPath == null) return null
+    if (documentPath.startsWith('/')) return documentPath
+    if (typeof attrs.targetCollectionPath === 'string' && attrs.targetCollectionPath.length > 0) {
+      return `/${attrs.targetCollectionPath}/${documentPath}`
+    }
+    return null
+  }
+  return typeof attrs.url === 'string' && attrs.url.length > 0 ? attrs.url : null
+}
+
+function serializeImage(node: AnyNode, ctx: Ctx): string {
+  const src = typeof node.src === 'string' ? node.src : ''
+  if (src.length === 0) return ''
+  const alt = typeof node.altText === 'string' ? node.altText : ''
+  const image = `![${alt.replace(/[[\]]/g, '')}](${src})`
+  // The caption is a nested SerializedEditor — flatten to emphasized text.
+  const caption = node.caption as { editorState?: unknown } | undefined
+  if (node.showCaption === true && caption?.editorState != null) {
+    const captionRoot = resolveRoot(caption.editorState)
+    if (captionRoot != null) {
+      const captionText = serializeBlocks(captionRoot.children ?? [], ctx)
+        .join(' ')
+        .trim()
+      if (captionText.length > 0) return `${image}\n*${captionText}*`
+    }
+  }
+  return image
+}
+
+function prefixLines(text: string, prefix: string): string {
+  return text
+    .split('\n')
+    .map((line) => (line.length > 0 ? `${prefix}${line}` : prefix.trimEnd()))
+    .join('\n')
+}

package/src/server.ts

@@ -43,6 +43,7 @@ import type {
   RichTextEmbedFn,
   RichTextPopulateContext,
   RichTextPopulateFn,
+  RichTextToMarkdownFn,
 } from '@byline/core'
 
 import { inlineImageVisitor } from './field/extensions/inline-image/populate'
@@ -56,6 +57,18 @@ import { type LexicalNodeVisitor, runLexicalPopulate } from './field/lexical-pop
 // their CSS imports; the `/server` subpath stays React-free.
 // ---------------------------------------------------------------------------
 export { defaultEditorConfig } from './field/config/default'
+export {
+  type LexicalToMarkdownOptions,
+  type LexicalToMarkdownResult,
+  type LexicalToMarkdownWarning,
+  lexicalToMarkdown,
+} from './field/markdown/lexical-to-markdown'
+
+import {
+  type LexicalToMarkdownOptions,
+  lexicalToMarkdown,
+} from './field/markdown/lexical-to-markdown'
+
 export { inlineImageVisitor } from './field/extensions/inline-image/populate'
 export { linkVisitor } from './field/extensions/link/populate'
 export type { EditorConfig, EditorSettings, EditorSettingsOverride } from './field/config/types'
@@ -120,6 +133,20 @@ export function lexicalEditorPopulateServer(options: LexicalServerOptions): Rich
  * per-leaf errors and leaves the leaf untouched on hard failure (branch
  * C of docs/RICHTEXT-LINK-REFACTOR-STRATEGY.md § 3.3).
  */
+/**
+ * One-way markdown serializer for the agent-readable export surface,
+ * shaped for `ServerConfig.fields.richText.toMarkdown`. The sibling of
+ * `lexicalEditorPopulateServer` / `lexicalEditorEmbedServer` — but pure
+ * and synchronous: it walks the stored editor JSON with
+ * `lexicalToMarkdown` and performs no reads. See that function's header
+ * for the dialect contract (GFM alerts, lossy-OK).
+ */
+export function lexicalEditorToMarkdownServer(
+  options: LexicalToMarkdownOptions = {}
+): RichTextToMarkdownFn {
+  return (ctx) => lexicalToMarkdown(ctx.value, options).markdown
+}
+
 export function lexicalEditorEmbedServer(options: LexicalServerOptions): RichTextEmbedFn {
   const visitors = options.visitors ?? [inlineImageVisitor, linkVisitor]
   return async (ctx: RichTextEmbedContext): Promise<void> => {