feat: Add JSON indentation option to decode() method

## Description
Implements Issue #10 by adding optional JSON indentation support to the
decode() function. Users can now request JSON-formatted output with
configurable indentation by passing a json_indent parameter to DecodeOptions.

## Changes Made
- Added json_indent parameter to DecodeOptions class
- Updated decode() to return JSON string when json_indent is specified
- Enhanced docstrings with usage examples
- Added 11 comprehensive tests covering all use cases

## Type of Change
- [x] New feature (non-breaking change that adds functionality)

## SPEC Compliance
- [x] Non-breaking change (default behavior unchanged)
- [x] Backward compatible (json_indent=None by default)
- [x] Python-specific feature (output formatting enhancement)

## Testing
- [x] All existing tests pass
- [x] Added new tests (11 total, 100% pass rate)
- [x] Comprehensive coverage (basic, nested, arrays, unicode, edge cases)
- [x] No breaking changes

## Code Quality
- [x] All type hints present (mypy passes)
- [x] Ruff linting passes (0 errors)
- [x] Code formatted (ruff format)
- [x] Python 3.8+ compatible

## Example Usage
```python
from toon_format import decode, DecodeOptions

# Default behavior - returns Python object
result = decode("name: Alice\nage: 30")
# {'name': 'Alice', 'age': 30}

# With JSON indentation - returns formatted JSON string
result = decode("name: Alice\nage: 30", DecodeOptions(json_indent=2))
# {\n  "name": "Alice",\n  "age": 30\n}
```

Author: jreakin

src/toon_format/decoder.py

@@ -8,6 +8,7 @@
 and validates array lengths and delimiters.
 """
 
+import json
 from typing import Any, Dict, List, Optional, Tuple
 
 from ._literal_utils import is_boolean_or_null_literal, is_numeric_literal
@@ -228,18 +229,38 @@ def split_key_value(line: str) -> Tuple[str, str]:
     return (key, value)
 
 
-def decode(input_str: str, options: Optional[DecodeOptions] = None) -> JsonValue:
+def decode(input_str: str, options: Optional[DecodeOptions] = None) -> Any:
     """Decode a TOON-formatted string to a Python value.
 
+    This function parses TOON format and returns the decoded data. By default,
+    it returns a Python object (dict, list, str, int, float, bool, or None).
+
+    The DecodeOptions.json_indent parameter is a Python-specific feature that
+    enables returning a JSON-formatted string instead of a Python object.
+    This is useful for applications that need pretty-printed JSON output.
+
     Args:
-        input_str: TOON-formatted string
-        options: Optional decoding options
+        input_str: TOON-formatted string to decode
+        options: Optional DecodeOptions with indent, strict, and json_indent
+                 settings. If not provided, defaults are used (indent=2,
+                 strict=True, json_indent=None).
 
     Returns:
-        Decoded Python value
+        By default (json_indent=None): Decoded Python value (object, array,
+            string, number, boolean, or null).
+        When json_indent is set: A JSON-formatted string with the specified
+            indentation level. Example: DecodeOptions(json_indent=2) returns
+            pretty-printed JSON with 2-space indentation.
 
     Raises:
-        ToonDecodeError: If input is malformed
+        ToonDecodeError: If input is malformed or violates strict-mode rules
+
+    Example:
+        >>> toon = "name: Alice\\nage: 30"
+        >>> decode(toon)
+        {'name': 'Alice', 'age': 30}
+        >>> decode(toon, DecodeOptions(json_indent=2))
+        '{\\n  "name": "Alice",\\n  "age": 30\\n}'
     """
     if options is None:
         options = DecodeOptions()
@@ -273,32 +294,41 @@ def decode(input_str: str, options: Optional[DecodeOptions] = None) -> JsonValue
     # Check for empty input (per spec Section 8: empty/whitespace-only → empty object)
     non_blank_lines = [ln for ln in lines if not ln.is_blank]
     if not non_blank_lines:
-        return {}
-
-    # Determine root form (Section 5)
-    first_line = non_blank_lines[0]
-
-    # Check if it's a root array header
-    header_info = parse_header(first_line.content)
-    if header_info is not None and header_info[0] is None:  # No key = root array
-        # Root array
-        return decode_array(lines, 0, 0, header_info, strict)
+        result: Any = {}
+    else:
+        # Determine root form (Section 5)
+        first_line = non_blank_lines[0]
+
+        # Check if it's a root array header
+        header_info = parse_header(first_line.content)
+        if header_info is not None and header_info[0] is None:  # No key = root array
+            # Root array
+            result = decode_array(lines, 0, 0, header_info, strict)
+        else:
+            # Check if it's a single primitive
+            if len(non_blank_lines) == 1:
+                line_content = first_line.content
+                # Check if it's not a key-value line
+                try:
+                    split_key_value(line_content)
+                    # It's a key-value, so root object
+                    result = decode_object(lines, 0, 0, strict)
+                except ToonDecodeError:
+                    # Not a key-value, check if it's a header
+                    if header_info is None:
+                        # Single primitive
+                        result = parse_primitive(line_content)
+                    else:
+                        result = decode_object(lines, 0, 0, strict)
+            else:
+                # Otherwise, root object
+                result = decode_object(lines, 0, 0, strict)
 
-    # Check if it's a single primitive
-    if len(non_blank_lines) == 1:
-        line_content = first_line.content
-        # Check if it's not a key-value line
-        try:
-            split_key_value(line_content)
-            # It's a key-value, so root object
-        except ToonDecodeError:
-            # Not a key-value, check if it's a header
-            if header_info is None:
-                # Single primitive
-                return parse_primitive(line_content)
+    # If json_indent is specified, return JSON-formatted string
+    if options.json_indent is not None:
+        return json.dumps(result, indent=options.json_indent, ensure_ascii=False)
 
-    # Otherwise, root object
-    return decode_object(lines, 0, 0, strict)
+    return result
 
 
 def decode_object(

src/toon_format/types.py

@@ -52,12 +52,26 @@ class DecodeOptions:
 
     Attributes:
         indent: Number of spaces per indentation level (default: 2)
+                Used for parsing TOON format.
         strict: Enable strict validation (default: True)
+                Enforces spec conformance checks.
+        json_indent: Optional number of spaces for JSON output formatting
+                     (default: None). When set, decode() returns a JSON-formatted
+                     string instead of a Python object. This is a Python-specific
+                     feature for convenient output formatting. When None, returns
+                     a Python object as normal. Pass an integer (e.g., 2 or 4)
+                     to enable pretty-printed JSON output.
     """
 
-    def __init__(self, indent: int = 2, strict: bool = True) -> None:
+    def __init__(
+        self,
+        indent: int = 2,
+        strict: bool = True,
+        json_indent: Union[int, None] = None,
+    ) -> None:
         self.indent = indent
         self.strict = strict
+        self.json_indent = json_indent
 
 
 # Depth type for tracking indentation level

tests/test_api.py

@@ -286,3 +286,98 @@ def test_roundtrip_with_length_marker(self):
         toon = encode(original, {"lengthMarker": "#"})
         decoded = decode(toon)
         assert decoded == original
+
+
+class TestDecodeJSONIndentation:
+    """Test decode() JSON indentation feature (Issue #10)."""
+
+    def test_decode_with_json_indent_returns_string(self):
+        """decode() with json_indent should return JSON string."""
+        toon = "id: 123\nname: Alice"
+        options = DecodeOptions(json_indent=2)
+        result = decode(toon, options)
+        assert isinstance(result, str)
+        # Verify it's valid JSON
+        import json
+
+        parsed = json.loads(result)
+        assert parsed == {"id": 123, "name": "Alice"}
+
+    def test_decode_with_json_indent_2(self):
+        """decode() with json_indent=2 should format with 2 spaces."""
+        toon = "id: 123\nname: Alice"
+        result = decode(toon, DecodeOptions(json_indent=2))
+        expected = '{\n  "id": 123,\n  "name": "Alice"\n}'
+        assert result == expected
+
+    def test_decode_with_json_indent_4(self):
+        """decode() with json_indent=4 should format with 4 spaces."""
+        toon = "id: 123\nname: Alice"
+        result = decode(toon, DecodeOptions(json_indent=4))
+        expected = '{\n    "id": 123,\n    "name": "Alice"\n}'
+        assert result == expected
+
+    def test_decode_with_json_indent_nested(self):
+        """decode() with json_indent should handle nested structures."""
+        toon = "user:\n  name: Alice\n  age: 30"
+        result = decode(toon, DecodeOptions(json_indent=2))
+        expected = '{\n  "user": {\n    "name": "Alice",\n    "age": 30\n  }\n}'
+        assert result == expected
+
+    def test_decode_with_json_indent_array(self):
+        """decode() with json_indent should handle arrays."""
+        toon = "items[2]: apple,banana"
+        result = decode(toon, DecodeOptions(json_indent=2))
+        expected = '{\n  "items": [\n    "apple",\n    "banana"\n  ]\n}'
+        assert result == expected
+
+    def test_decode_with_json_indent_none_returns_object(self):
+        """decode() with json_indent=None should return Python object."""
+        toon = "id: 123\nname: Alice"
+        options = DecodeOptions(json_indent=None)
+        result = decode(toon, options)
+        assert isinstance(result, dict)
+        assert result == {"id": 123, "name": "Alice"}
+
+    def test_decode_with_json_indent_default_returns_object(self):
+        """decode() without json_indent should return Python object (default)."""
+        toon = "id: 123\nname: Alice"
+        result = decode(toon)
+        assert isinstance(result, dict)
+        assert result == {"id": 123, "name": "Alice"}
+
+    def test_decode_json_indent_with_unicode(self):
+        """decode() with json_indent should preserve unicode characters."""
+        toon = 'name: "José"'
+        result = decode(toon, DecodeOptions(json_indent=2))
+        assert "José" in result
+        import json
+
+        parsed = json.loads(result)
+        assert parsed["name"] == "José"
+
+    def test_decode_json_indent_empty_object(self):
+        """decode() with json_indent on empty input should return empty object JSON."""
+        result = decode("", DecodeOptions(json_indent=2))
+        assert result == "{}"
+
+    def test_decode_json_indent_single_primitive(self):
+        """decode() with json_indent on single primitive should return JSON number."""
+        result = decode("42", DecodeOptions(json_indent=2))
+        assert result == "42"
+
+    def test_decode_json_indent_complex_nested(self):
+        """decode() with json_indent should handle complex nested structures."""
+        toon = """users[2]{id,name}:
+  1,Alice
+  2,Bob
+metadata:
+  version: 1
+  active: true"""
+        result = decode(toon, DecodeOptions(json_indent=2))
+        import json
+
+        parsed = json.loads(result)
+        assert parsed["users"][0] == {"id": 1, "name": "Alice"}
+        assert parsed["metadata"]["version"] == 1
+        assert parsed["metadata"]["active"] is True