fix(html): keep table caption CommonMark valid

Address Copilot review feedback on PR #640:

- Flatten <caption> content to inline-only nodes before wrapping in
  Strong, so flow content (e.g. nested <p>, lists) can no longer become
  invalid block children of a Strong node.
- Handle <caption> inside the table branch instead of a standalone rule,
  so a caption appearing outside a table no longer leaks a node without
  a $class into the output.
- Emit the bolded caption as its own Paragraph block and drop the inline
  '\n\n' Text hack, leaving block-level spacing to the Markdown serializer.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Signed-off-by: Matt Roberts <code@rbrts.uk>

Author: mttrbrts

packages/markdown-html/src/HtmlTransformer.test.js

@@ -107,16 +107,50 @@ describe('html table deserialization', () => {
                             text: 'Employee Details'
                         }
                     ]
-                },
-                {
-                    $class: `${commonmarkNamespace}.Text`,
-                    text: '\n\n'
                 }
             ]
         });
         expect(ciceroMarkDom.nodes[1].$class).toBe(`${commonmarkNamespace}.Table`);
     });
 
+    it('flattens block content in a caption to inline-only Strong children', () => {
+        const ciceroMarkDom = htmlTransformer.toCiceroMark(`
+            <table>
+                <caption><p>See <em>also</em></p></caption>
+                <thead>
+                    <tr><th>Name</th></tr>
+                </thead>
+                <tbody>
+                    <tr><td>Ada</td></tr>
+                </tbody>
+            </table>
+        `);
+
+        expect(ciceroMarkDom.nodes).toHaveLength(2);
+        const strong = ciceroMarkDom.nodes[0].nodes[0];
+        expect(strong.$class).toBe(`${commonmarkNamespace}.Strong`);
+        // every child of Strong must be inline (no Paragraph leaked in)
+        strong.nodes.forEach(child => {
+            expect(child.$class).not.toBe(`${commonmarkNamespace}.Paragraph`);
+        });
+        expect(strong.nodes).toEqual([
+            { $class: `${commonmarkNamespace}.Text`, text: 'See ' },
+            {
+                $class: `${commonmarkNamespace}.Emph`,
+                nodes: [{ $class: `${commonmarkNamespace}.Text`, text: 'also' }]
+            }
+        ]);
+        expect(ciceroMarkDom.nodes[1].$class).toBe(`${commonmarkNamespace}.Table`);
+    });
+
+    it('does not leak a caption node when it appears outside a table', () => {
+        const ciceroMarkDom = htmlTransformer.toCiceroMark('<caption>Orphan caption</caption>');
+
+        // the old caption rule produced a node with no $class; ensure none leak
+        ciceroMarkDom.nodes.forEach(n => expect(typeof n.$class).toBe('string'));
+        expect(ciceroMarkDom.nodes.some(n => n.type === 'caption')).toBe(false);
+    });
+
     it('normalizes whitespace in table cells', () => {
         const ciceroMarkDom = htmlTransformer.toCiceroMark(`
             <table>

packages/markdown-html/src/rules.js

@@ -498,16 +498,39 @@ const HTML_BLOCK_RULE = {
     }
 };
 
-const CAPTION_RULE = {
-    deserialize(el, next, ignoreSpace) {
-        if (el.tagName && el.tagName.toLowerCase() === 'caption') {
-            return {
-                type: 'caption',
-                nodes: next(el.childNodes, ignoreSpace)
-            };
-        }
+// CommonMark inline node classes. A <caption> may contain flow content
+// (paragraphs, lists, etc.), but a Strong node may only contain inline
+// children, so caption content is flattened to these classes before it is
+// wrapped in Strong.
+const INLINE_CLASSES = [
+    'Text', 'Emph', 'Strong', 'Code', 'Link', 'Image',
+    'Softbreak', 'Linebreak', 'HtmlInline'
+].map(name => `${CommonMarkModel.NAMESPACE}.${name}`);
+
+/**
+ * Flatten caption content to inline-only nodes so it can be safely wrapped in
+ * a Strong node. Block-level wrappers (e.g. Paragraph) are unwrapped to their
+ * inline children; nodes with no inline content are dropped.
+ * @param {Array} nodes - the list of nodes
+ * @returns {Array} - the inline-only list of nodes
+ */
+function toInlineNodes(nodes) {
+    if (!nodes) {
+        return [];
     }
-};
+    const list = Array.isArray(nodes) ? nodes : [nodes];
+    return list.reduce((acc, node) => {
+        if (!node) {
+            return acc;
+        }
+        if (INLINE_CLASSES.includes(node.$class)) {
+            acc.push(node);
+        } else if (node.nodes) {
+            acc.push(...toInlineNodes(node.nodes));
+        }
+        return acc;
+    }, []);
+}
 
 /**
  * Clean table cell nodes by removing Softbreaks and normalizing whitespace.
@@ -570,7 +593,6 @@ const TABLE_RULE = {
     deserialize(el, next, ignoreSpace) {
         if (el.tagName && el.tagName.toLowerCase() === 'table') {
             const children = next(el.childNodes, ignoreSpace);
-            const captionNode = children.find(c => c.type === 'caption');
             let tableNodes = children.filter(node =>
                 node.$class === `${CommonMarkModel.NAMESPACE}.TableHead` ||
                 node.$class === `${CommonMarkModel.NAMESPACE}.TableBody`
@@ -601,21 +623,29 @@ const TABLE_RULE = {
                 nodes: tableNodes,
             };
 
-            if (captionNode) {
-                const captionParagraph = {
-                    $class: `${CommonMarkModel.NAMESPACE}.Paragraph`,
-                    nodes: [
-                        {
-                            $class: `${CommonMarkModel.NAMESPACE}.Strong`,
-                            nodes: cleanTableNodes(captionNode.nodes)
-                        },
-                        {
-                            $class: `${CommonMarkModel.NAMESPACE}.Text`,
-                            text: '\n\n'
-                        }
-                    ]
-                };
-                return [captionParagraph, table];
+            // A <caption> is handled here (rather than via its own rule) so the
+            // caption node never leaks into the output when it appears outside
+            // of a table. Its content is flattened to inline-only nodes so the
+            // Strong wrapper stays valid CommonMark, and the bolded caption is
+            // emitted as its own Paragraph block before the table - block-level
+            // spacing is left to the Markdown serializer.
+            const captionElement = Array.from(el.childNodes).find(
+                child => child.tagName && child.tagName.toLowerCase() === 'caption'
+            );
+            if (captionElement) {
+                const captionNodes = cleanTableNodes(toInlineNodes(next(captionElement.childNodes, ignoreSpace)));
+                if (captionNodes.length > 0) {
+                    const captionParagraph = {
+                        $class: `${CommonMarkModel.NAMESPACE}.Paragraph`,
+                        nodes: [
+                            {
+                                $class: `${CommonMarkModel.NAMESPACE}.Strong`,
+                                nodes: captionNodes
+                            }
+                        ]
+                    };
+                    return [captionParagraph, table];
+                }
             }
 
             return table;
@@ -677,8 +707,7 @@ const rules = [
     HTML_INLINE_RULE,
     HTML_BLOCK_RULE,
     IMAGE_RULE,
-    TABLE_RULE,
-    CAPTION_RULE
+    TABLE_RULE
 ];