xmlcst 0.1.0__tar.gz

xmlcst-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff format --check src/ tests/ samples/
+      - run: ruff check src/ tests/ samples/
+      - run: basedpyright
+      - run: pytest tests/ -v

xmlcst-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff format --check src/ tests/ samples/
+      - run: ruff check src/ tests/ samples/
+      - run: basedpyright
+      - run: pytest tests/ -v
+
+  publish:
+    needs: check
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

xmlcst-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+*.egg-info

xmlcst-0.1.0/DEV.md

@@ -0,0 +1,171 @@
+# Developer Guide
+
+This guide is for contributors who want to work on `xmlcst` itself.
+
+## Prerequisites
+
+- Python 3.12+
+- Git
+
+No other system dependencies are required. The project is pure Python.
+
+## Setup
+
+```bash
+git clone <repo-url>
+cd xmlcst
+./dev.sh test
+```
+
+On first run, `dev.sh` automatically creates a virtual environment at `.venv/`, installs the package in editable mode with dev dependencies (`pytest`, `ruff`), and runs the test suite.
+
+## Development Commands
+
+All development tasks go through `dev.sh`:
+
+| Command | Description |
+|---|---|
+| `./dev.sh check` | Run all checks: format, lint, typecheck, test (fails on first error) |
+| `./dev.sh test` | Run the test suite with pytest (verbose output) |
+| `./dev.sh lint` | Run ruff check on `src/` and `tests/` |
+| `./dev.sh format` | Run ruff format on `src/` and `tests/` |
+| `./dev.sh typecheck` | Run basedpyright on `src/` and `tests/` |
+| `./dev.sh clean` | Remove `__pycache__/`, `.pytest_cache/`, `dist/`, `*.egg-info` |
+
+Extra arguments are forwarded. For example, to run a single test:
+
+```bash
+./dev.sh test -k test_roundtrip_simple_element
+```
+
+## Project Structure
+
+```
+pyproject.toml             Build config (hatchling), dev dependencies, pytest settings
+dev.sh                     Development task runner
+SPEC.md                    Full specification (source of truth for behaviour)
+README.md                  Consumer-facing documentation
+src/xmlcst/
+  __init__.py              Public API exports
+  py.typed                 PEP 561 marker (ships inline types)
+  _api.py                  parse(), parse_bytes(), parse_file()
+  _tokenizer.py            Lexical tokenizer: str -> list[Token]
+  _tokens.py               Token dataclass and TokenType enum (22 types)
+  _builder.py              Tree builder: list[Token] -> Document
+  _nodes.py                All node types (Document, Element, Attribute, etc.)
+  _entities.py             Entity/character reference encoding and decoding
+  _errors.py               ParseError exception
+tests/
+  test_roundtrip.py        Core invariant: parse(x).to_string() == x
+  test_tokenizer.py        Token stream correctness
+  test_tree.py             Tree navigation and property access
+  test_mutation.py         Editing, dirty-tracking, formatting ownership
+  test_encoding.py         BOM handling, bytes vs string input
+samples/
+  bump_pom_version/        Maven POM version bumper (see README.md)
+```
+
+## Architecture
+
+The implementation follows the dual-layer model described in [SPEC.md](SPEC.md) sections 6-8.
+
+### Layer 1: Tokenization
+
+`_tokenizer.py` converts a source string into a flat list of `Token` objects. Each token stores its type, raw text, and byte offset. The fundamental invariant:
+
+```python
+assert source == "".join(t.text for t in tokenize(source))
+```
+
+Every byte of the input belongs to exactly one token. The 22 token types are defined in `_tokens.py`.
+
+### Layer 2: Tree Building
+
+`_builder.py` walks the token list and constructs a tree of `Node` objects (defined in `_nodes.py`). Each node stores:
+
+- A **token span** `(start, end)` -- indices into the token list identifying the tokens that produced this node
+- A **dirty flag** -- initially `False`, set to `True` when any property is modified
+
+### Serialization
+
+When serializing, each node checks whether it can use its token span:
+
+- **Clean nodes** (unmodified): join their original tokens -- guaranteed byte-identical to source
+- **Dirty nodes** (modified): rebuild from current properties and formatting metadata
+- **New nodes** (created programmatically): rebuild with inferred or default formatting
+
+This is the mechanism that produces minimal diffs on edit.
+
+## Conventions
+
+### Code Style
+
+- Formatted with `ruff format` (default line length: 88)
+- Linted with `ruff check`
+- Type-checked with `basedpyright` (strict mode with select rules disabled in `pyproject.toml`)
+- Run `./dev.sh check` before committing to validate formatting, lint, types, and tests in one step
+
+### Module Naming
+
+- Public API is exported from `__init__.py`
+- Internal modules use an underscore prefix: `_tokenizer.py`, `_nodes.py`, `_builder.py`, etc.
+- Private methods and attributes use a single underscore prefix
+
+### Testing
+
+- Tests live in `tests/` and use `pytest`
+- Test files are grouped by feature area
+- The round-trip test (`test_roundtrip.py`) is the most important invariant: any change must not break `parse(x).to_string() == x`
+- Prefer testing through the public API (`xmlcst.parse`, `doc.to_string()`) rather than reaching into internal methods
+- When adding a new feature, add both a round-trip test case and specific behavioural tests
+
+## Common Workflows
+
+### Adding a New Node Type
+
+1. Define the class in `_nodes.py` following existing patterns (`__slots__`, property accessors with dirty-tracking, `_rebuild()` method)
+2. Add any new token types to the `TokenType` enum in `_tokens.py`
+3. Update the tokenizer in `_tokenizer.py` to emit the new tokens
+4. Update the tree builder in `_builder.py` to construct the new node
+5. Export from `__init__.py` and add to `__all__`
+6. Add round-trip and tree-level tests
+
+### Adding a New Feature
+
+1. Check whether the behaviour is already specified in [SPEC.md](SPEC.md)
+2. If not, update the specification first (spec-driven development)
+3. Implement against the spec
+4. Verify that all existing round-trip tests still pass
+
+## Build and Packaging
+
+- **Build system**: [hatchling](https://hatch.pypa.io/)
+- **Package layout**: `src/xmlcst/` (src layout)
+- **Build**: `python -m build` (produces wheel and sdist in `dist/`)
+- **No compiled extensions** -- the wheel is pure Python and platform-independent
+- **Type annotations** -- the package ships inline types with a `py.typed` marker (PEP 561); type checkers recognize annotations without stubs
+
+## CI
+
+GitHub Actions runs the full check suite (format, lint, typecheck, test) on every push to `main` and every pull request, across Python 3.12 and 3.13. See `.github/workflows/ci.yml`.
+
+## Releasing
+
+1. Update the version in `pyproject.toml`
+2. Commit: `git commit -am "Bump version to X.Y.Z"`
+3. Tag: `git tag vX.Y.Z`
+4. Push: `git push && git push --tags`
+
+The [`publish`](.github/workflows/publish.yml) workflow runs CI checks, builds the package, and publishes to PyPI automatically via [trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+## Specification
+
+[SPEC.md](SPEC.md) is the source of truth for all behavioural decisions:
+
+- Fidelity guarantees (what must be preserved)
+- Token model (every token type and its semantics)
+- Tree model (node types, dirty-tracking, token spans)
+- Mutation semantics (formatting ownership, inferred formatting)
+- Serialization modes (exact, normalized)
+- Error handling
+- Future roadmap

xmlcst-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Cook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xmlcst-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: xmlcst
+Version: 0.1.0
+Summary: Full-fidelity XML parser with lossless round-trip editing
+Project-URL: Repository, https://github.com/rcook/xmlcst
+Project-URL: Issues, https://github.com/rcook/xmlcst/issues
+Author: Richard Cook
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cst,editing,parser,round-trip,xml
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: basedpyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# xmlcst
+
+Full-fidelity XML concrete syntax tree for Python -- parse, edit, and serialize with zero formatting loss.
+
+## Why xmlcst?
+
+Existing Python XML libraries (ElementTree, lxml, minidom) parse XML into a semantic tree that discards lexical details: whitespace, comment placement, attribute quote styles, entity reference forms, and more. When you serialize back, the output differs from the input even if you changed nothing.
+
+`xmlcst` takes a different approach. It treats XML as **source text first** and semantic structure second, producing a concrete syntax tree (CST) that retains every byte of the original document. When you edit a single attribute, only that attribute changes in the output -- surrounding formatting, comments, and whitespace remain untouched.
+
+This makes `xmlcst` ideal for programmatic editing of XML configuration files (Maven POMs, `.csproj` files, Spring configs, Android manifests) where changes must produce minimal, reviewable diffs.
+
+### How xmlcst compares
+
+| Feature | ElementTree | lxml | minidom | xmlcst |
+|---|---|---|---|---|
+| Attribute order | Partial | Partial | Partial | Preserved |
+| Quote style (`'` vs `"`) | No | No | No | Preserved |
+| Whitespace / indentation | No | No | No | Preserved |
+| Comments | No | Yes | Yes | Preserved |
+| Entity reference form | No | No | No | Preserved |
+| CDATA vs escaped text | No | Yes | Yes | Preserved |
+| Empty-element syntax (`<x/>` vs `<x />`) | No | No | No | Preserved |
+| Byte-identical round-trip | No | No | No | Yes |
+
+The closest conceptual analogue is [ruamel.yaml](https://yaml.readthedocs.io/) -- a round-trip-capable YAML library -- applied to XML.
+
+## Installation
+
+```
+pip install xmlcst
+```
+
+Requires Python 3.12+. Pure Python -- no compiled dependencies. Ships [PEP 561](https://peps.python.org/pep-0561/) type annotations for full mypy / pyright support.
+
+## Quick Start
+
+### Parse and round-trip
+
+```python
+import xmlcst
+
+source = '<project xmlns="http://maven.apache.org/POM/4.0.0">\n  <version>1.0</version>\n</project>'
+
+doc = xmlcst.parse(source)
+assert doc.to_string() == source  # byte-identical round-trip
+```
+
+### Edit an attribute (minimal diff)
+
+```python
+doc = xmlcst.parse('<root version="1.0" author="alice"/>')
+doc.root.attributes["version"] = "2.0"
+print(doc.to_string())
+# <root version="2.0" author="alice"/>
+# Only the value changed -- quotes, whitespace, other attributes untouched
+```
+
+### Navigate the tree
+
+```python
+doc = xmlcst.parse("""\
+<project>
+  <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+    </dependency>
+  </dependencies>
+</project>""")
+
+deps = doc.root.find("dependencies")
+dep = deps.find("dependency")
+group = dep.find("groupId")
+print(group.children[0].content)  # "junit" (a Text node)
+
+# Or search recursively
+dep2 = doc.root.find_recursive("dependency")
+all_deps = doc.root.findall_recursive("dependency")
+```
+
+### Add and remove elements
+
+```python
+doc = xmlcst.parse("<root>\n  <a/>\n  <b/>\n</root>")
+doc.root.append(xmlcst.Element("c"))
+print(doc.to_string())
+# <root>
+#   <a/>
+#   <b/>
+#   <c/>
+# </root>
+```
+
+### Access formatting metadata
+
+```python
+doc = xmlcst.parse('<root  id = "1"  name=\'foo\'/>')
+attr = doc.root.attributes["id"]
+print(attr.raw_value)          # "1"
+print(attr.quote)              # '"'
+print(attr.leading_whitespace) # "  "
+print(attr.eq_whitespace)      # (" ", " ")
+```
+
+### Work with entity references
+
+```python
+doc = xmlcst.parse("<root>a &amp; b</root>")
+text = doc.root.children[0]
+print(text.content)            # "a &amp; b"  (raw, as in the source)
+print(text.decoded_content())  # "a & b"      (entities resolved)
+
+text.set_content("x < y")     # auto-escapes
+print(text.content)            # "x &lt; y"
+```
+
+## Sample Application
+
+The [`samples/bump_pom_version/`](samples/bump_pom_version/) directory contains a complete example: a Maven POM version bumper that reads a `pom.xml`, increments the patch version, and writes the file back. Only the version string changes -- all comments, whitespace, attribute quoting, and other formatting are preserved exactly.
+
+```bash
+python samples/bump_pom_version/bump_pom_version.py
+# 1.2.3 -> 1.2.4
+```
+
+The script accepts an optional path argument to operate on any POM file:
+
+```bash
+python samples/bump_pom_version/bump_pom_version.py /path/to/your/pom.xml
+```
+
+## API Overview
+
+### Parsing
+
+| Function | Input | Returns |
+|---|---|---|
+| `xmlcst.parse(text)` | `str` | `Document` |
+| `xmlcst.parse_bytes(data)` | `bytes` | `Document` |
+| `xmlcst.parse_file(path)` | `str \| Path` | `Document` |
+
+All parse functions raise `xmlcst.ParseError` on malformed input. The error includes `message`, `line`, `column`, and `offset` attributes.
+
+### Node Types
+
+| Type | Description |
+|---|---|
+| `Document` | Root container; holds all top-level nodes |
+| `Element` | An XML element with tag, attributes, and children |
+| `Attribute` | Name-value pair with formatting metadata (quote style, whitespace) |
+| `AttributeList` | Ordered collection with dict-like access by name |
+| `Text` | Character data (entity references preserved in raw form) |
+| `Whitespace` | Whitespace-only character data between markup |
+| `Comment` | `<!-- ... -->` |
+| `ProcessingInstruction` | `<?target data?>` |
+| `CData` | `<![CDATA[...]]>` |
+| `Doctype` | `<!DOCTYPE ...>` (preserved verbatim) |
+| `XmlDeclaration` | `<?xml version="1.0" ...?>` |
+
+### Serialization
+
+| Method | Description |
+|---|---|
+| `doc.to_string()` | Exact round-trip serialization (default) |
+| `doc.to_string(mode="normalized")` | Pretty-printed with consistent formatting |
+| `doc.to_bytes()` | UTF-8 encoded; BOM preserved if present in input |
+| `doc.write(path)` | Write to file |
+
+## Design
+
+`xmlcst` uses a dual-layer architecture:
+
+1. **Token stream** (Layer 1) -- a lossless sequence of tokens covering every byte of the input. The fundamental invariant: `"".join(t.text for t in tokens) == source`.
+2. **Tree API** (Layer 2) -- mutable nodes backed by the token stream. Each node tracks a token span and a dirty flag.
+
+Unmodified nodes serialize by replaying their original tokens (byte-identical). Modified nodes rebuild from their current properties. This guarantees that edits produce the smallest possible diff.
+
+See [SPEC.md](SPEC.md) for the full specification.
+
+## Limitations (v1)
+
+- UTF-8 encoding only
+- XML 1.0 well-formed documents only (no error recovery)
+- No DTD validation or schema support
+- No XPath query engine
+- No streaming / SAX-style parsing
+- Pure Python (no compiled acceleration)
+
+See the [future roadmap](SPEC.md#15-future-roadmap) in the specification for planned enhancements.
+
+## License
+
+MIT

xmlcst-0.1.0/README.md

@@ -0,0 +1,193 @@
+# xmlcst
+
+Full-fidelity XML concrete syntax tree for Python -- parse, edit, and serialize with zero formatting loss.
+
+## Why xmlcst?
+
+Existing Python XML libraries (ElementTree, lxml, minidom) parse XML into a semantic tree that discards lexical details: whitespace, comment placement, attribute quote styles, entity reference forms, and more. When you serialize back, the output differs from the input even if you changed nothing.
+
+`xmlcst` takes a different approach. It treats XML as **source text first** and semantic structure second, producing a concrete syntax tree (CST) that retains every byte of the original document. When you edit a single attribute, only that attribute changes in the output -- surrounding formatting, comments, and whitespace remain untouched.
+
+This makes `xmlcst` ideal for programmatic editing of XML configuration files (Maven POMs, `.csproj` files, Spring configs, Android manifests) where changes must produce minimal, reviewable diffs.
+
+### How xmlcst compares
+
+| Feature | ElementTree | lxml | minidom | xmlcst |
+|---|---|---|---|---|
+| Attribute order | Partial | Partial | Partial | Preserved |
+| Quote style (`'` vs `"`) | No | No | No | Preserved |
+| Whitespace / indentation | No | No | No | Preserved |
+| Comments | No | Yes | Yes | Preserved |
+| Entity reference form | No | No | No | Preserved |
+| CDATA vs escaped text | No | Yes | Yes | Preserved |
+| Empty-element syntax (`<x/>` vs `<x />`) | No | No | No | Preserved |
+| Byte-identical round-trip | No | No | No | Yes |
+
+The closest conceptual analogue is [ruamel.yaml](https://yaml.readthedocs.io/) -- a round-trip-capable YAML library -- applied to XML.
+
+## Installation
+
+```
+pip install xmlcst
+```
+
+Requires Python 3.12+. Pure Python -- no compiled dependencies. Ships [PEP 561](https://peps.python.org/pep-0561/) type annotations for full mypy / pyright support.
+
+## Quick Start
+
+### Parse and round-trip
+
+```python
+import xmlcst
+
+source = '<project xmlns="http://maven.apache.org/POM/4.0.0">\n  <version>1.0</version>\n</project>'
+
+doc = xmlcst.parse(source)
+assert doc.to_string() == source  # byte-identical round-trip
+```
+
+### Edit an attribute (minimal diff)
+
+```python
+doc = xmlcst.parse('<root version="1.0" author="alice"/>')
+doc.root.attributes["version"] = "2.0"
+print(doc.to_string())
+# <root version="2.0" author="alice"/>
+# Only the value changed -- quotes, whitespace, other attributes untouched
+```
+
+### Navigate the tree
+
+```python
+doc = xmlcst.parse("""\
+<project>
+  <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+    </dependency>
+  </dependencies>
+</project>""")
+
+deps = doc.root.find("dependencies")
+dep = deps.find("dependency")
+group = dep.find("groupId")
+print(group.children[0].content)  # "junit" (a Text node)
+
+# Or search recursively
+dep2 = doc.root.find_recursive("dependency")
+all_deps = doc.root.findall_recursive("dependency")
+```
+
+### Add and remove elements
+
+```python
+doc = xmlcst.parse("<root>\n  <a/>\n  <b/>\n</root>")
+doc.root.append(xmlcst.Element("c"))
+print(doc.to_string())
+# <root>
+#   <a/>
+#   <b/>
+#   <c/>
+# </root>
+```
+
+### Access formatting metadata
+
+```python
+doc = xmlcst.parse('<root  id = "1"  name=\'foo\'/>')
+attr = doc.root.attributes["id"]
+print(attr.raw_value)          # "1"
+print(attr.quote)              # '"'
+print(attr.leading_whitespace) # "  "
+print(attr.eq_whitespace)      # (" ", " ")
+```
+
+### Work with entity references
+
+```python
+doc = xmlcst.parse("<root>a &amp; b</root>")
+text = doc.root.children[0]
+print(text.content)            # "a &amp; b"  (raw, as in the source)
+print(text.decoded_content())  # "a & b"      (entities resolved)
+
+text.set_content("x < y")     # auto-escapes
+print(text.content)            # "x &lt; y"
+```
+
+## Sample Application
+
+The [`samples/bump_pom_version/`](samples/bump_pom_version/) directory contains a complete example: a Maven POM version bumper that reads a `pom.xml`, increments the patch version, and writes the file back. Only the version string changes -- all comments, whitespace, attribute quoting, and other formatting are preserved exactly.
+
+```bash
+python samples/bump_pom_version/bump_pom_version.py
+# 1.2.3 -> 1.2.4
+```
+
+The script accepts an optional path argument to operate on any POM file:
+
+```bash
+python samples/bump_pom_version/bump_pom_version.py /path/to/your/pom.xml
+```
+
+## API Overview
+
+### Parsing
+
+| Function | Input | Returns |
+|---|---|---|
+| `xmlcst.parse(text)` | `str` | `Document` |
+| `xmlcst.parse_bytes(data)` | `bytes` | `Document` |
+| `xmlcst.parse_file(path)` | `str \| Path` | `Document` |
+
+All parse functions raise `xmlcst.ParseError` on malformed input. The error includes `message`, `line`, `column`, and `offset` attributes.
+
+### Node Types
+
+| Type | Description |
+|---|---|
+| `Document` | Root container; holds all top-level nodes |
+| `Element` | An XML element with tag, attributes, and children |
+| `Attribute` | Name-value pair with formatting metadata (quote style, whitespace) |
+| `AttributeList` | Ordered collection with dict-like access by name |
+| `Text` | Character data (entity references preserved in raw form) |
+| `Whitespace` | Whitespace-only character data between markup |
+| `Comment` | `<!-- ... -->` |
+| `ProcessingInstruction` | `<?target data?>` |
+| `CData` | `<![CDATA[...]]>` |
+| `Doctype` | `<!DOCTYPE ...>` (preserved verbatim) |
+| `XmlDeclaration` | `<?xml version="1.0" ...?>` |
+
+### Serialization
+
+| Method | Description |
+|---|---|
+| `doc.to_string()` | Exact round-trip serialization (default) |
+| `doc.to_string(mode="normalized")` | Pretty-printed with consistent formatting |
+| `doc.to_bytes()` | UTF-8 encoded; BOM preserved if present in input |
+| `doc.write(path)` | Write to file |
+
+## Design
+
+`xmlcst` uses a dual-layer architecture:
+
+1. **Token stream** (Layer 1) -- a lossless sequence of tokens covering every byte of the input. The fundamental invariant: `"".join(t.text for t in tokens) == source`.
+2. **Tree API** (Layer 2) -- mutable nodes backed by the token stream. Each node tracks a token span and a dirty flag.
+
+Unmodified nodes serialize by replaying their original tokens (byte-identical). Modified nodes rebuild from their current properties. This guarantees that edits produce the smallest possible diff.
+
+See [SPEC.md](SPEC.md) for the full specification.
+
+## Limitations (v1)
+
+- UTF-8 encoding only
+- XML 1.0 well-formed documents only (no error recovery)
+- No DTD validation or schema support
+- No XPath query engine
+- No streaming / SAX-style parsing
+- Pure Python (no compiled acceleration)
+
+See the [future roadmap](SPEC.md#15-future-roadmap) in the specification for planned enhancements.
+
+## License
+
+MIT