perf(core): add document-level and block-level caching to pm→markdown serialization (#1047)

Two-level caching in `MarkdownSerializer`:

- **Document-level:** when `serialize()` is called with the same `doc` node and equivalent `options`, returns the cached result without re-serialization
- **Top-level block cache:** when the document changes, only modified top-level blocks are re-serialized; unchanged blocks are served from a `WeakMap` cache

Author: d3m1d0v

packages/editor/src/core/markdown/Markdown.test.ts

@@ -420,4 +420,226 @@ describe('markdown (fork-specific)', () => {
             );
         });
     });
+
+    describe('document-level cache', () => {
+        let renderTopLevelContentCallCount: number;
+        const origRenderTopLevelContent = MarkdownSerializerState.prototype.renderTopLevelContent;
+
+        beforeEach(() => {
+            serializer.clearCache();
+            renderTopLevelContentCallCount = 0;
+            MarkdownSerializerState.prototype.renderTopLevelContent = function (parent) {
+                renderTopLevelContentCallCount++;
+                return origRenderTopLevelContent.call(this, parent);
+            };
+        });
+
+        afterEach(() => {
+            MarkdownSerializerState.prototype.renderTopLevelContent = origRenderTopLevelContent;
+            serializer.clearCache();
+        });
+
+        it('returns cached result for the same doc node', () => {
+            const document = doc(p('hello'));
+            const result1 = serializer.serialize(document);
+            renderTopLevelContentCallCount = 0;
+            const result2 = serializer.serialize(document);
+            expect(result2).toBe('hello');
+            expect(result2).toBe(result1);
+            expect(renderTopLevelContentCallCount).toBe(0);
+        });
+
+        it('re-serializes when doc node changes', () => {
+            const doc1 = doc(p('hello'));
+            const doc2 = doc(p('world'));
+            const result1 = serializer.serialize(doc1);
+            const result2 = serializer.serialize(doc2);
+            expect(result1).toBe('hello');
+            expect(result2).toBe('world');
+        });
+
+        it('cache hit when options objects differ by reference but equal by content', () => {
+            const document = doc(p('hello'));
+            serializer.serialize(document, {tightLists: true});
+            renderTopLevelContentCallCount = 0;
+            const result = serializer.serialize(document, {tightLists: true});
+            expect(result).toBe('hello');
+            expect(renderTopLevelContentCallCount).toBe(0);
+        });
+
+        it('cache miss when options actually differ', () => {
+            const document = doc(p('hello'));
+            serializer.serialize(document, {strict: true});
+            renderTopLevelContentCallCount = 0;
+            serializer.serialize(document, {strict: false});
+            expect(renderTopLevelContentCallCount).toBeGreaterThan(0);
+        });
+
+        it('cache hit when RegExp options are equal but different objects', () => {
+            const document = doc(p('hello'));
+            serializer.serialize(document, {commonEscape: /[abc]/g});
+            renderTopLevelContentCallCount = 0;
+            serializer.serialize(document, {commonEscape: /[abc]/g});
+            expect(renderTopLevelContentCallCount).toBe(0);
+        });
+
+        it('cache miss when RegExp options differ', () => {
+            const document = doc(p('hello'));
+            serializer.serialize(document, {commonEscape: /[abc]/g});
+            renderTopLevelContentCallCount = 0;
+            serializer.serialize(document, {commonEscape: /[xyz]/g});
+            expect(renderTopLevelContentCallCount).toBeGreaterThan(0);
+        });
+
+        it('clearCache forces re-serialization', () => {
+            const document = doc(p('hello'));
+            serializer.serialize(document);
+            serializer.clearCache();
+            renderTopLevelContentCallCount = 0;
+            serializer.serialize(document);
+            expect(renderTopLevelContentCallCount).toBeGreaterThan(0);
+        });
+
+        it('cache hit with same options reference (fast path)', () => {
+            const document = doc(p('hello'));
+            const opts = {tightLists: true, commonEscape: /test/g};
+            serializer.serialize(document, opts);
+            renderTopLevelContentCallCount = 0;
+            serializer.serialize(document, opts);
+            expect(renderTopLevelContentCallCount).toBe(0);
+        });
+    });
+
+    describe('top-level node cache', () => {
+        let renderCallCount: number;
+        let renderedNodeTypes: string[];
+        const origRender = MarkdownSerializerState.prototype.render;
+
+        beforeEach(() => {
+            serializer.clearCache();
+            renderCallCount = 0;
+            renderedNodeTypes = [];
+            MarkdownSerializerState.prototype.render = function (node, parent, index) {
+                renderCallCount++;
+                renderedNodeTypes.push(node.type.name);
+                return origRender.call(this, node, parent, index);
+            };
+        });
+
+        afterEach(() => {
+            MarkdownSerializerState.prototype.render = origRender;
+            serializer.clearCache();
+        });
+
+        it('uses cache for unchanged blocks when one block changes', () => {
+            const block1 = p('hello');
+            const block2 = p('world');
+            serializer.serialize(doc(block1, block2));
+
+            // Change only block2 — block1 should come from cache
+            const block2new = p('changed');
+            renderCallCount = 0;
+            renderedNodeTypes = [];
+            const result = serializer.serialize(doc(block1, block2new));
+
+            expect(result).toBe('hello\n\nchanged');
+            // Only block2new is re-rendered (paragraph + its inline text child)
+            expect(renderedNodeTypes).toStrictEqual(['paragraph', 'text']);
+        });
+
+        it('produces correct separators between blocks on cache hit', () => {
+            const block1 = p('one');
+            const block2 = p('two');
+            const block3 = p('three');
+            serializer.serialize(doc(block1, block2, block3));
+
+            // New doc with same blocks — document-level miss, top-level cache hit
+            renderCallCount = 0;
+            const result = serializer.serialize(doc(block1, block2, block3));
+            expect(result).toBe('one\n\ntwo\n\nthree');
+            // All blocks from top-level cache, none re-rendered
+            expect(renderCallCount).toBe(0);
+        });
+
+        it('correct separator for two consecutive lists of the same type', () => {
+            const list1 = ul(li(p('a')));
+            const list2 = ul(li(p('b')));
+            const result = serializer.serialize(doc(list1, list2));
+            expect(result).toBe('* a\n\n\n* b');
+
+            // New doc, same blocks — top-level cache hit
+            const result2 = serializer.serialize(doc(list1, list2));
+            expect(result2).toBe('* a\n\n\n* b');
+        });
+
+        it('handles mixed block types correctly', () => {
+            const heading = h1('Title');
+            const paragraph = p('text');
+            const list = ul(li(p('item')));
+            const codeBlock = pre('code\n');
+            serializer.serialize(doc(heading, paragraph, list, codeBlock));
+
+            // Change only the paragraph, others from cache
+            const newParagraph = p('new text');
+            renderCallCount = 0;
+            renderedNodeTypes = [];
+            const result = serializer.serialize(doc(heading, newParagraph, list, codeBlock));
+
+            expect(result).toBe('# Title\n\nnew text\n\n* item\n\n```\ncode\n```');
+            // Only newParagraph is re-rendered (paragraph + its inline text child)
+            expect(renderedNodeTypes).toStrictEqual(['paragraph', 'text']);
+        });
+
+        it('invalidates cache when block order changes (prevClosedTypeName differs)', () => {
+            const heading = h1('Title');
+            const paragraph = p('text');
+            serializer.serialize(doc(heading, paragraph));
+
+            // Swap order — prevClosedTypeName changes for both blocks
+            renderCallCount = 0;
+            const result = serializer.serialize(doc(paragraph, heading));
+
+            expect(result).toBe('text\n\n# Title');
+            expect(renderCallCount).toBeGreaterThanOrEqual(2);
+        });
+
+        it('clearCache resets top-level node cache', () => {
+            const block = p('hello');
+            serializer.serialize(doc(block));
+
+            serializer.clearCache();
+            renderCallCount = 0;
+            serializer.serialize(doc(block));
+            expect(renderCallCount).toBeGreaterThan(0);
+        });
+
+        it('invalidates top-level node cache when options change', () => {
+            const block = p('hello');
+            serializer.serialize(doc(block), {strict: true});
+
+            renderCallCount = 0;
+            serializer.serialize(doc(block), {strict: false});
+            expect(renderCallCount).toBeGreaterThan(0);
+        });
+
+        it('does not cache nested nodes (non top-level)', () => {
+            // paragraph is nested inside list_item — it should not be cached
+            const paragraph = p('nested');
+            const list1 = ul(li(paragraph));
+            serializer.serialize(doc(list1));
+
+            // New list with the same paragraph node inside — list is new,
+            // so top-level cache misses. The nested paragraph must be
+            // re-rendered, not taken from cache.
+            const list2 = ul(li(paragraph));
+            renderCallCount = 0;
+            renderedNodeTypes = [];
+            const result = serializer.serialize(doc(list2));
+
+            expect(result).toBe('* nested');
+            // paragraph and text must be re-rendered (not cached)
+            expect(renderedNodeTypes).toContain('paragraph');
+            expect(renderedNodeTypes).toContain('text');
+        });
+    });
 });