From 3933dc061656cfb8801c0874d4366137bda4a4c3 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 28 Jan 2026 02:22:12 +0000
Subject: [PATCH] feat: Add RenderResult dataclass and render_content()
 function

- Add RenderResult dataclass with content, width, height fields
- Add to_svg() method for convenience when you need the full SVG
- Add render_content() method to SVGRenderer class
- Add render_content() convenience function at module level
- Export RenderResult and render_content from __init__.py
- Add comprehensive tests for the new API
- Update README with documentation and examples

This allows callers to compose multiple mdsvg outputs into larger SVGs
without needing regex extraction to strip wrappers.

Co-authored-by: davefowler <davefowler@gmail.com>
---
 README.md              |  43 ++++++++++
 src/mdsvg/__init__.py  |  12 ++-
 src/mdsvg/renderer.py  | 181 +++++++++++++++++++++++++++++++++++++++--
 tests/test_renderer.py | 121 +++++++++++++++++++++++++++
 4 files changed, 349 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 167f325..9a4b659 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,49 @@ size = measure("# Hello\n\nLong paragraph...", width=400)
 print(f"Height needed: {size.height}px")
 ```
 
+### Structured Result (for Composing SVGs)
+
+When you need to embed mdsvg output in larger SVG compositions, use `render_content()` to get the SVG elements without the wrapper, along with the actual dimensions:
+
+```python
+from mdsvg import render_content, RenderResult
+
+# Get structured result
+result: RenderResult = render_content("# Hello World", width=400)
+
+result.content  # SVG elements without <svg> wrapper (includes style block)
+result.width    # 400.0
+result.height   # Actual rendered height
+
+# Convert to full SVG when needed
+svg = result.to_svg()  # Full SVG with wrapper
+
+# Embed in a larger SVG composition
+large_svg = f"""
+<svg xmlns="http://www.w3.org/2000/svg" width="800" height="600">
+  <rect fill="#f0f0f0" width="800" height="600"/>
+  <g transform="translate(50, 100)">
+    {result.content}
+  </g>
+</svg>
+"""
+```
+
+This eliminates the need for regex extraction when composing multiple mdsvg outputs:
+
+```python
+# Compose multiple sections side by side
+left = render_content("# Section 1\n\nLeft content", width=350)
+right = render_content("# Section 2\n\nRight content", width=350)
+
+combined = f"""
+<svg xmlns="http://www.w3.org/2000/svg" width="750" height="{max(left.height, right.height)}">
+  <g transform="translate(0, 0)">{left.content}</g>
+  <g transform="translate(400, 0)">{right.content}</g>
+</svg>
+"""
+```
+
 ### Custom Styling
 
 ```python
diff --git a/src/mdsvg/__init__.py b/src/mdsvg/__init__.py
index fef6ff3..e949388 100644
--- a/src/mdsvg/__init__.py
+++ b/src/mdsvg/__init__.py
@@ -16,6 +16,14 @@
     >>> from mdsvg import measure
     >>> size = measure("# Hello\n\nLong paragraph...")
     >>> print(f"Height: {size.height}px")
+
+Get structured result for composing into larger SVGs:
+    >>> from mdsvg import render_content, RenderResult
+    >>> result = render_content("# Hello", width=400)
+    >>> result.content  # SVG elements without <svg> wrapper
+    >>> result.width    # 400.0
+    >>> result.height   # Actual rendered height
+    >>> result.to_svg() # Full SVG with wrapper
 """
 
 # Precise text measurement
@@ -37,7 +45,7 @@
 )
 from .measure import Size, TextMetrics, estimate_text_width, measure_spans, wrap_text
 from .parser import MarkdownParser, parse
-from .renderer import SVGRenderer, measure, render, render_blocks
+from .renderer import RenderResult, SVGRenderer, measure, render, render_blocks, render_content
 from .style import (
     COMPACT_PRESET,
     DARK_THEME,
@@ -75,11 +83,13 @@
 __all__ = [
     # Main API
     "render",
+    "render_content",
     "render_blocks",
     "measure",
     "parse",
     # Classes
     "Style",
+    "RenderResult",
     "MarkdownParser",
     "SVGRenderer",
     # Themes
diff --git a/src/mdsvg/renderer.py b/src/mdsvg/renderer.py
index 7a4b5af..2c2b7a1 100644
--- a/src/mdsvg/renderer.py
+++ b/src/mdsvg/renderer.py
@@ -30,6 +30,54 @@
 from .utils import escape_svg_text, format_number
 
 
+@dataclass
+class RenderResult:
+    """Result of rendering markdown content.
+
+    Contains the rendered SVG content (without wrapper), along with dimensions.
+    This allows callers to compose multiple mdsvg outputs into a larger SVG
+    without needing to regex-strip wrappers.
+
+    Attributes:
+        content: SVG elements without the <svg> wrapper (includes <style> block).
+        width: Width of the rendered content in pixels.
+        height: Height of the rendered content in pixels.
+
+    Example:
+        >>> from mdsvg import render_content
+        >>> result = render_content("# Hello", width=400)
+        >>> result.content  # SVG elements without wrapper
+        >>> result.width    # 400.0
+        >>> result.height   # Actual rendered height
+        >>> result.to_svg() # Full SVG with wrapper
+    """
+
+    content: str
+    width: float
+    height: float
+
+    def to_svg(self) -> str:
+        """Wrap content in a complete SVG element.
+
+        Returns:
+            Complete SVG string with xmlns, width, height, and viewBox attributes.
+
+        Example:
+            >>> result = render_content("# Hello", width=400)
+            >>> svg = result.to_svg()
+            >>> with open("output.svg", "w") as f:
+            ...     f.write(svg)
+        """
+        svg_parts = [
+            f'<svg xmlns="http://www.w3.org/2000/svg" '
+            f'width="{format_number(self.width)}" height="{format_number(self.height)}" '
+            f'viewBox="0 0 {format_number(self.width)} {format_number(self.height)}">',
+            self.content,
+            "</svg>",
+        ]
+        return "\n".join(svg_parts)
+
+
 @dataclass
 class RenderContext:
     """Context passed through rendering for tracking state."""
@@ -187,14 +235,16 @@ def _measure_text(
         # Apply safety margin for browser rendering differences
         return width * self.style.text_width_scale
 
-    def render(
+    def _render_blocks_to_elements(
         self,
         blocks: Document,
-        width: float = 400,
-        padding: float = 0,
-    ) -> str:
+        width: float,
+        padding: float,
+    ) -> Tuple[List[str], float]:
         """
-        Render blocks to an SVG string.
+        Render blocks to SVG elements and return total height.
+
+        This is the core rendering logic shared by render() and render_content().
 
         Args:
             blocks: Document AST to render.
@@ -202,7 +252,7 @@ def render(
             padding: Padding inside the SVG.
 
         Returns:
-            SVG string.
+            Tuple of (svg_elements, total_height).
         """
         content_width = width - (padding * 2)
 
@@ -226,11 +276,81 @@ def render(
             current_y -= self.style.paragraph_spacing
 
         total_height = current_y + padding
+        return svg_elements, total_height
+
+    def render(
+        self,
+        blocks: Document,
+        width: float = 400,
+        padding: float = 0,
+    ) -> str:
+        """
+        Render blocks to an SVG string.
+
+        Args:
+            blocks: Document AST to render.
+            width: Width of the SVG in pixels.
+            padding: Padding inside the SVG.
 
-        # Build SVG
+        Returns:
+            SVG string.
+        """
+        svg_elements, total_height = self._render_blocks_to_elements(blocks, width, padding)
         svg = self._build_svg(svg_elements, width, total_height)
         return svg
 
+    def render_content(
+        self,
+        blocks: Document,
+        width: float = 400,
+        padding: float = 0,
+    ) -> RenderResult:
+        """
+        Render blocks and return structured result with content and dimensions.
+
+        Unlike render(), this returns the SVG content without the <svg> wrapper,
+        along with the actual dimensions. This is useful when composing multiple
+        mdsvg outputs into a larger SVG.
+
+        Args:
+            blocks: Document AST to render.
+            width: Width of the SVG in pixels.
+            padding: Padding inside the SVG.
+
+        Returns:
+            RenderResult with content (SVG elements without wrapper),
+            width, and height.
+
+        Example:
+            >>> renderer = SVGRenderer()
+            >>> blocks = parse("# Hello")
+            >>> result = renderer.render_content(blocks, width=400)
+            >>> result.content  # SVG elements without wrapper
+            >>> result.width    # 400.0
+            >>> result.height   # Actual rendered height
+            >>> result.to_svg() # Full SVG with wrapper
+        """
+        svg_elements, total_height = self._render_blocks_to_elements(blocks, width, padding)
+
+        # Build content (style block + elements) without SVG wrapper
+        content_parts = [
+            f"""  <style>
+    .md-text {{ font-family: {self.style.font_family}; fill: {self.style.text_color}; }}
+    .md-mono {{ font-family: {self.style.mono_font_family}; }}
+    .md-heading {{ font-family: {self.style.font_family}; fill: {self.style.get_heading_color()}; font-weight: {self.style.heading_font_weight}; }}
+    .md-code {{ font-family: {self.style.mono_font_family}; fill: {self.style.code_color}; }}
+    .md-link {{ fill: {self.style.link_color}; }}
+    .md-blockquote {{ fill: {self.style.blockquote_color}; }}
+  </style>"""
+        ]
+        content_parts.extend(svg_elements)
+
+        return RenderResult(
+            content="\n".join(content_parts),
+            width=width,
+            height=total_height,
+        )
+
     def measure(
         self,
         blocks: Document,
@@ -1160,3 +1280,50 @@ def measure(
     blocks = parse(markdown)
     renderer = SVGRenderer(style=style)
     return renderer.measure(blocks, width=width, padding=padding)
+
+
+def render_content(
+    markdown: str,
+    width: float = 400,
+    padding: float = 20,
+    style: Optional[Style] = None,
+) -> RenderResult:
+    """
+    Render Markdown and return structured result with content and dimensions.
+
+    Unlike render(), this returns the SVG content without the <svg> wrapper,
+    along with the actual dimensions. This is useful when composing multiple
+    mdsvg outputs into a larger SVG without needing regex-based extraction.
+
+    Args:
+        markdown: Markdown text to render.
+        width: Width of the SVG in pixels.
+        padding: Padding inside the SVG.
+        style: Style configuration. Uses default if None.
+
+    Returns:
+        RenderResult with content (SVG elements without wrapper),
+        width, and height.
+
+    Example:
+        >>> from mdsvg import render_content
+        >>> result = render_content("# Hello World", width=400)
+        >>> result.content  # SVG elements without <svg> wrapper
+        >>> result.width    # 400.0
+        >>> result.height   # Actual rendered height
+        >>> result.to_svg() # Full SVG with wrapper (convenience method)
+
+        # Embed in a larger SVG:
+        >>> large_svg = f'''
+        ... <svg xmlns="http://www.w3.org/2000/svg" width="800" height="600">
+        ...   <g transform="translate(50, 100)">
+        ...     {result.content}
+        ...   </g>
+        ... </svg>
+        ... '''
+    """
+    from .parser import parse
+
+    blocks = parse(markdown)
+    renderer = SVGRenderer(style=style)
+    return renderer.render_content(blocks, width=width, padding=padding)
diff --git a/tests/test_renderer.py b/tests/test_renderer.py
index 5bbbb4f..c769320 100644
--- a/tests/test_renderer.py
+++ b/tests/test_renderer.py
@@ -4,12 +4,14 @@
 from mdsvg import (
     DARK_THEME,
     GITHUB_THEME,
+    RenderResult,
     Size,
     Style,
     measure,
     parse,
     render,
     render_blocks,
+    render_content,
 )
 from mdsvg.renderer import SVGRenderer
 
@@ -279,3 +281,122 @@ def hello():
         assert "Main Title" in svg
         assert "bold" in svg
         assert "print" in svg
+
+
+class TestRenderContent:
+    """Test render_content function and RenderResult dataclass."""
+
+    def test_render_content_returns_render_result(self) -> None:
+        """Test that render_content returns a RenderResult object."""
+        result = render_content("# Hello World")
+        assert isinstance(result, RenderResult)
+
+    def test_render_result_has_content(self) -> None:
+        """Test that RenderResult has content without SVG wrapper."""
+        result = render_content("Hello World")
+        assert result.content is not None
+        # Content should not have the outer SVG tags
+        assert not result.content.strip().startswith("<svg")
+        assert not result.content.strip().endswith("</svg>")
+        # But should have actual content
+        assert "Hello World" in result.content
+
+    def test_render_result_has_dimensions(self) -> None:
+        """Test that RenderResult has width and height."""
+        result = render_content("# Hello", width=400)
+        assert result.width == 400
+        assert result.height > 0
+
+    def test_render_result_height_matches_measure(self) -> None:
+        """Test that RenderResult height matches measure()."""
+        markdown = "# Title\n\nSome paragraph text here."
+        result = render_content(markdown, width=400, padding=20)
+        size = measure(markdown, width=400, padding=20)
+        assert result.height == size.height
+        assert result.width == size.width
+
+    def test_render_result_to_svg(self) -> None:
+        """Test RenderResult.to_svg() method."""
+        result = render_content("# Hello World", width=400)
+        svg = result.to_svg()
+
+        # Should have SVG wrapper
+        assert svg.startswith("<svg")
+        assert svg.endswith("</svg>")
+        assert 'xmlns="http://www.w3.org/2000/svg"' in svg
+        assert 'width="400"' in svg
+
+        # Should contain the content
+        assert "Hello World" in svg
+
+    def test_to_svg_matches_render(self) -> None:
+        """Test that to_svg() produces same result as render()."""
+        markdown = "# Hello\n\nThis is a paragraph."
+        width = 400
+        padding = 20
+
+        result = render_content(markdown, width=width, padding=padding)
+        svg_from_result = result.to_svg()
+
+        svg_from_render = render(markdown, width=width, padding=padding)
+
+        # Both should produce valid SVGs with same dimensions
+        assert f'width="{width}"' in svg_from_result
+        assert f'width="{width}"' in svg_from_render
+        # Both should contain the content
+        assert "Hello" in svg_from_result
+        assert "Hello" in svg_from_render
+
+    def test_render_content_includes_style_block(self) -> None:
+        """Test that content includes the CSS style block."""
+        result = render_content("Hello")
+        assert "<style>" in result.content
+        assert ".md-text" in result.content
+
+    def test_render_content_with_custom_style(self) -> None:
+        """Test render_content with custom style."""
+        style = Style(text_color="#ff0000")
+        result = render_content("Hello", style=style)
+        assert "#ff0000" in result.content
+
+    def test_render_content_composability(self) -> None:
+        """Test that content can be composed into larger SVG."""
+        result1 = render_content("# Section 1", width=300)
+        result2 = render_content("# Section 2", width=300)
+
+        # Compose into a larger SVG
+        combined_svg = f"""<svg xmlns="http://www.w3.org/2000/svg" width="700" height="400">
+  <g transform="translate(0, 0)">
+    {result1.content}
+  </g>
+  <g transform="translate(350, 0)">
+    {result2.content}
+  </g>
+</svg>"""
+
+        # Should be valid SVG with both sections
+        assert 'xmlns="http://www.w3.org/2000/svg"' in combined_svg
+        assert "Section 1" in combined_svg
+        assert "Section 2" in combined_svg
+
+    def test_svg_renderer_render_content_method(self) -> None:
+        """Test SVGRenderer.render_content() method directly."""
+        renderer = SVGRenderer()
+        blocks = parse("# Hello\n\nWorld")
+        result = renderer.render_content(blocks, width=400)
+
+        assert isinstance(result, RenderResult)
+        assert result.width == 400
+        assert result.height > 0
+        assert "Hello" in result.content
+        assert "World" in result.content
+
+    def test_render_result_empty_input(self) -> None:
+        """Test render_content with empty input."""
+        result = render_content("")
+        assert isinstance(result, RenderResult)
+        assert result.width > 0
+        assert result.height >= 0
+        # to_svg() should still work
+        svg = result.to_svg()
+        assert "<svg" in svg