Add children macro and TOC maxLevel round-trip support

[CHILDREN] maps to ac:name="children" (self-closing); [TOC maxLevel=N]
preserves the maxLevel parameter through pull and push. Nine new tests
cover both macros.

Author: kellenmurphy

CLAUDE.md

@@ -1,3 +1,4 @@
+
 # CLAUDE.md
 
 This file provides context for Claude Code when working in this project.
@@ -74,7 +75,8 @@ open/close pairs and cannot consume content across tag boundaries.
 |---|---|---|---|
 | `code` | ` ```lang ``` ` fenced block | `ac:structured-macro ac:name="code"` | Full round-trip |
 | `noformat` | ` ```noformat ``` ` fenced block | `ac:structured-macro ac:name="noformat"` | Full round-trip |
-| `toc` | `[TOC]` placeholder | `ac:structured-macro ac:name="toc"` | Full round-trip |
+| `toc` | `[TOC]` or `[TOC maxLevel=N]` placeholder | `ac:structured-macro ac:name="toc"` | Full round-trip; `maxLevel` param preserved |
+| `children` | `[CHILDREN]` placeholder | `ac:structured-macro ac:name="children"` | Full round-trip |
 | `expand` | `> [!EXPAND] Title` blockquote | `ac:structured-macro ac:name="expand"` | Full round-trip; code inside expand becomes fenced on pull |
 | `note`/`info`/`warning`/`tip` | `> [!NOTE]` etc. GFM alerts | `ac:structured-macro ac:name="note\|info\|..."` | Full round-trip |
 | `jira` | `[KEY-123](jira_url/browse/KEY-123)` | `ac:structured-macro ac:name="jira"` | Full round-trip |

py_conf_sync.py

@@ -203,6 +203,10 @@ def update_page(self, page_id: str, title: str, storage_body: str, version: int)
     r'<ac:structured-macro[^>]*\bac:name="toc"(?:[^/>]|/(?!>))*(?:/>|>.*?</ac:structured-macro>)',
     re.DOTALL,
 )
+_CHILDREN_MACRO_RE = re.compile(
+    r'<ac:structured-macro[^>]*\bac:name="children"(?:[^/>]|/(?!>))*(?:/>|>.*?</ac:structured-macro>)',
+    re.DOTALL,
+)
 _PANEL_MACRO_RE = re.compile(
     r'<ac:structured-macro[^>]*\bac:name="(note|info|warning|tip)"[^>]*>'
     r'.*?<ac:rich-text-body[^>]*>(.*?)</ac:rich-text-body>'
@@ -360,7 +364,12 @@ def storage_to_markdown(storage_html: str, jira_url: str | None = None, base_url
     # TODO: add round-trip support for status badges
     #       (ac:structured-macro ac:name="status") →
     #       inline marker e.g. `[STATUS:colour:label]`, restored on push.
-    cleaned = _TOC_MACRO_RE.sub('<p>[TOC]</p>', storage_html)
+    def _replace_toc_macro(m):
+        ml = re.search(r'<ac:parameter\s+ac:name="maxLevel">(\d+)</ac:parameter>', m.group(0))
+        return f'<p>[TOC maxLevel={ml.group(1)}]</p>' if ml else '<p>[TOC]</p>'
+
+    cleaned = _TOC_MACRO_RE.sub(_replace_toc_macro, storage_html)
+    cleaned = _CHILDREN_MACRO_RE.sub('<p>[CHILDREN]</p>', cleaned)
     cleaned = _CODE_MACRO_RE.sub(lambda m: _replace_code_macro(m.group(0)), cleaned)
     cleaned = _NOFORMAT_MACRO_RE.sub(lambda m: _replace_noformat_macro(m.group(0)), cleaned)
     cleaned = _JIRA_MACRO_RE.sub(lambda m: _replace_jira_macro(m.group(0), jira_url), cleaned)
@@ -432,9 +441,19 @@ def markdown_to_storage(markdown_text: str, base_url: str | None = None, page_id
 
     html = re.sub(r"<br>", "<br />", html)
     html = re.sub(r"<hr>", "<hr />", html)
+    def _toc_to_storage(m):
+        if m.group(1):
+            return (
+                '<ac:structured-macro ac:name="toc" ac:schema-version="1">'
+                f'<ac:parameter ac:name="maxLevel">{m.group(1)}</ac:parameter>'
+                '</ac:structured-macro>'
+            )
+        return '<ac:structured-macro ac:name="toc" ac:schema-version="1"></ac:structured-macro>'
+
+    html = re.sub(r'<p>\[TOC(?:\s+maxLevel=(\d+))?\]</p>', _toc_to_storage, html)
     html = re.sub(
-        r'<p>\[TOC\]</p>',
-        '<ac:structured-macro ac:name="toc" ac:schema-version="1"></ac:structured-macro>',
+        r'<p>\[CHILDREN\]</p>',
+        '<ac:structured-macro ac:name="children" ac:schema-version="1"></ac:structured-macro>',
         html,
     )
 

tests/test_conversion.py

@@ -442,6 +442,64 @@ def test_toc_round_trip(self):
         result = markdown_to_storage(md)
         assert 'ac:name="toc"' in result
 
+    def test_pull_toc_with_max_level(self):
+        storage = (
+            '<ac:structured-macro ac:name="toc" ac:schema-version="1" ac:macro-id="abc">'
+            '<ac:parameter ac:name="maxLevel">2</ac:parameter>'
+            '</ac:structured-macro>'
+        )
+        result = storage_to_markdown(storage)
+        assert "[TOC maxLevel=2]" in result
+
+    def test_push_toc_with_max_level(self):
+        result = markdown_to_storage("[TOC maxLevel=3]")
+        assert 'ac:name="toc"' in result
+        assert '<ac:parameter ac:name="maxLevel">3</ac:parameter>' in result
+
+    def test_toc_max_level_round_trip(self):
+        storage = (
+            '<ac:structured-macro ac:name="toc" ac:schema-version="1">'
+            '<ac:parameter ac:name="maxLevel">2</ac:parameter>'
+            '</ac:structured-macro>'
+        )
+        md = storage_to_markdown(storage)
+        result = markdown_to_storage(md)
+        assert 'ac:name="toc"' in result
+        assert '<ac:parameter ac:name="maxLevel">2</ac:parameter>' in result
+
+    def test_push_toc_without_max_level_has_no_param(self):
+        result = markdown_to_storage("[TOC]")
+        assert 'ac:name="toc"' in result
+        assert 'maxLevel' not in result
+
+
+class TestChildren:
+    def test_pull_children_self_closing(self):
+        storage = '<ac:structured-macro ac:name="children" ac:schema-version="2" ac:macro-id="abc123" />'
+        result = storage_to_markdown(storage)
+        assert "[CHILDREN]" in result
+
+    def test_push_children_placeholder(self):
+        result = markdown_to_storage("[CHILDREN]")
+        assert 'ac:name="children"' in result
+
+    def test_children_round_trip(self):
+        storage = '<ac:structured-macro ac:name="children" ac:schema-version="2" ac:macro-id="abc" />'
+        md = storage_to_markdown(storage)
+        result = markdown_to_storage(md)
+        assert 'ac:name="children"' in result
+
+    def test_pull_children_does_not_eat_following_content(self):
+        storage = (
+            '<ac:structured-macro ac:name="children" ac:schema-version="2" ac:macro-id="abc" />'
+            '<h2>Section Heading</h2>'
+            '<p>Paragraph text.</p>'
+        )
+        result = storage_to_markdown(storage)
+        assert "[CHILDREN]" in result
+        assert "Section Heading" in result
+        assert "Paragraph text" in result
+
 
 class TestNoformat:
     def test_pull_noformat_macro(self):