texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/ui/cli/state.py

@@ -0,0 +1,263 @@
+"""Shared CLI state management utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+import sys
+from typing import TYPE_CHECKING, Any, cast
+
+import click
+import typer
+
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+__all__ = [
+    "CLIState",
+    "debug_enabled",
+    "emit_error",
+    "emit_warning",
+    "ensure_rich_compat",
+    "get_cli_state",
+    "render_message",
+    "set_cli_state",
+]
+
+
+def ensure_rich_compat() -> None:
+    """Patch Rich stub modules provided by tests to expose required attributes."""
+    import importlib.machinery
+    import sys as _sys
+    import types
+
+    rich_mod = _sys.modules.get("rich")
+    if rich_mod is None:
+        return
+    if getattr(rich_mod, "__spec__", None) is None:
+        rich_mod.__spec__ = importlib.machinery.ModuleSpec("rich", loader=None)
+
+    is_stub = getattr(rich_mod, "__file__", None) is None
+
+    if is_stub:
+        try:
+            import typer.core as typer_core
+
+            cast(Any, typer_core).HAS_RICH = False
+        except ImportError:  # pragma: no cover - typer not available
+            pass
+        try:
+            import typer.main as typer_main
+
+            cast(Any, typer_main).HAS_RICH = False
+        except ImportError:  # pragma: no cover - typer not available
+            pass
+
+    if not hasattr(rich_mod, "box"):
+        box_module = types.ModuleType("rich.box")
+        cast(Any, box_module).SQUARE = object()
+        cast(Any, box_module).MINIMAL_DOUBLE_HEAD = object()
+        cast(Any, box_module).SIMPLE = object()
+        cast(Any, rich_mod).box = box_module
+        _sys.modules.setdefault("rich.box", box_module)
+
+
+@dataclass(slots=True)
+class CLIState:
+    """Shared state controlling CLI diagnostics."""
+
+    verbosity: int = 0
+    show_tracebacks: bool = False
+    events: dict[str, list[dict[str, Any]]] = field(default_factory=dict, init=False)
+    _console: Console | None = field(default=None, init=False, repr=False)
+    _err_console: Console | None = field(default=None, init=False, repr=False)
+
+    @property
+    def console(self) -> Console:
+        """Return a lazily instantiated stdout console."""
+        from rich.console import Console
+
+        current = getattr(self._console, "file", None)
+        if self._console is None or current is not sys.stdout:
+            try:
+                self._console = Console(file=sys.stdout)
+            except TypeError:  # pragma: no cover - stub Console fallback
+                self._console = Console()
+        return self._console
+
+    @property
+    def err_console(self) -> Console:
+        """Return a lazily instantiated stderr console."""
+        from rich.console import Console
+
+        current = getattr(self._err_console, "file", None)
+        if self._err_console is None or current is not sys.stderr:
+            try:
+                self._err_console = Console(file=sys.stderr, highlight=False)
+            except TypeError:  # pragma: no cover - stub Console fallback
+                self._err_console = Console()
+        return self._err_console
+
+    def record_event(self, name: str, payload: Mapping[str, Any] | None = None) -> None:
+        """Store a structured diagnostic event for later presentation."""
+        entry = dict(payload or {})
+        self.events.setdefault(name, []).append(entry)
+
+    def consume_events(self, name: str) -> list[dict[str, Any]]:
+        """Retrieve and clear events for the given name."""
+        return self.events.pop(name, [])
+
+
+_STATE_VAR: ContextVar[CLIState | None] = ContextVar("texsmith_cli_state", default=None)
+
+
+def get_cli_state(
+    ctx: typer.Context | click.Context | None = None,
+    *,
+    create: bool = True,
+) -> CLIState:
+    """Return the CLI state associated with the active Typer context."""
+    if ctx is None:
+        try:
+            candidate = click.get_current_context(silent=True)
+        except RuntimeError:
+            candidate = None
+        if isinstance(candidate, typer.Context):
+            ctx = candidate
+
+    state: CLIState | None = None
+
+    if isinstance(ctx, typer.Context):
+        current_ctx: typer.Context | None = ctx
+        while current_ctx is not None:
+            obj = getattr(current_ctx, "obj", None)
+            if isinstance(obj, CLIState):
+                state = obj
+                break
+            current_ctx = getattr(current_ctx, "parent", None)
+        if state is None and create:
+            state = CLIState()
+            current_ctx = ctx
+            current_ctx.obj = state
+        if state is not None:
+            _STATE_VAR.set(state)
+
+    if state is None:
+        fallback = _STATE_VAR.get(None)
+        if fallback is None:
+            if not create:
+                raise RuntimeError("CLI state is not initialised for this context.")
+            fallback = CLIState()
+            _STATE_VAR.set(fallback)
+        state = fallback
+
+    return state
+
+
+def set_cli_state(
+    *,
+    ctx: typer.Context | None = None,
+    verbosity: int | None = None,
+    debug: bool | None = None,
+) -> CLIState:
+    """Update the CLI state, returning the current instance."""
+    state = get_cli_state(ctx)
+    if verbosity is not None:
+        state.verbosity = max(0, verbosity)
+    if debug is not None:
+        state.show_tracebacks = debug
+    return state
+
+
+def _exception_chain(exc: BaseException) -> list[str]:
+    chain: list[str] = []
+    visited: set[int] = set()
+    current = exc.__cause__ or exc.__context__
+    while current is not None and id(current) not in visited:
+        visited.add(id(current))
+        chain.append(f"{type(current).__name__}: {current}")
+        current = current.__cause__ or current.__context__
+    return chain
+
+
+def render_message(
+    level: str,
+    message: str,
+    *,
+    exception: BaseException | None = None,
+) -> None:
+    """Render a formatted message to the console, including optional diagnostics."""
+    state = get_cli_state()
+
+    if level == "info":
+        # Use a neutral console log for info to align with pipeline logging.
+        console = state.console
+        if getattr(console, "log", None):
+            console.log(message)
+        return
+
+    from rich.text import Text
+
+    style = "red" if level == "error" else "yellow"
+    label_style = f"bold {style}"
+    if hasattr(Text, "assemble"):
+        text = Text.assemble((f"{level}: ", label_style), (message, style))
+    else:  # pragma: no cover - stub Text fallback
+        text = Text()
+        text.append(f"{level}: ")
+        text.append(message)
+    extra_lines: list[str] = []
+    if exception is not None and state.verbosity >= 1:
+        detail = str(exception).strip()
+        if detail and detail not in message:
+            extra_lines.append(detail)
+        extra_lines.append(f"type: {type(exception).__name__}")
+        notes = getattr(exception, "__notes__", None)
+        if notes:
+            extra_lines.extend(str(note) for note in notes)
+        if state.verbosity >= 2:
+            chain = _exception_chain(exception)
+            if chain:
+                extra_lines.append("caused by:")
+                extra_lines.extend(f"  {entry}" for entry in chain)
+        if state.verbosity >= 3:
+            extra_lines.append(f"repr: {exception!r}")
+
+    if extra_lines:
+        if hasattr(text, "append"):
+            text.append("\n")
+            if hasattr(Text, "assemble"):
+                text.append("\n".join(extra_lines), style=style)
+            else:  # pragma: no cover - stub Text fallback
+                text.append("\n".join(extra_lines))
+        else:  # pragma: no cover - fallback if text is a plain string
+            text = f"{text}\n" + "\n".join(extra_lines)
+
+    console = state.err_console if level != "info" else state.console
+    if type(console).__name__.startswith("_Stub"):  # pragma: no cover - stub Console fallback
+        target = sys.stderr if level != "info" else sys.stdout
+        print(text if isinstance(text, str) else str(text), file=target)
+    else:
+        console.print(text)
+
+
+def emit_warning(message: str, *, exception: BaseException | None = None) -> None:
+    """Log a warning-level message to stderr respecting verbosity settings."""
+    render_message("warning", message, exception=exception)
+
+
+def emit_error(message: str, *, exception: BaseException | None = None) -> None:
+    """Log an error-level message to stderr respecting verbosity settings."""
+    if exception is not None and getattr(exception, "_texsmith_logged", False):
+        return
+    render_message("error", message, exception=exception)
+
+
+def debug_enabled() -> bool:
+    """Return whether full tracebacks should be displayed."""
+    try:
+        return get_cli_state(create=False).show_tracebacks
+    except RuntimeError:
+        return False

texsmith/ui/cli/utils.py

@@ -0,0 +1,235 @@
+"""Auxiliary helpers used by CLI commands."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+import typer
+
+from texsmith.api.service import SlotAssignment
+from texsmith.core.conversion.inputs import DOCUMENT_SELECTOR_SENTINEL
+
+
+def parse_slot_option(values: Iterable[str] | None) -> dict[str, str]:
+    """Parse CLI slot overrides declared as 'slot:Section' pairs."""
+    overrides: dict[str, str] = {}
+    if not values:
+        return overrides
+
+    for raw in values:
+        if not isinstance(raw, str):
+            continue
+        entry = raw.strip()
+        if not entry:
+            continue
+        if ":" not in entry:
+            raise ValueError(f"Invalid slot override '{raw}', expected format 'slot:Section'.")
+        slot_name, selector = entry.split(":", 1)
+        slot_name = slot_name.strip()
+        selector = selector.strip()
+        if not slot_name or not selector:
+            raise ValueError(f"Invalid slot override '{raw}', expected format 'slot:Section'.")
+        overrides[slot_name] = selector
+
+    return overrides
+
+
+def determine_output_target(
+    template_selected: bool,
+    documents: list[Path],
+    output_option: Path | None,
+) -> tuple[str, Path | None]:
+    """Infer where conversion output should be written based on CLI arguments."""
+    if template_selected:
+        if output_option is None:
+            base_dir = documents[0].parent if documents else Path()
+            return "template", (base_dir / "build")
+        suffix = output_option.suffix.lower()
+        if suffix == ".pdf":
+            return "template-pdf", output_option
+        if output_option.exists() and output_option.is_file():
+            raise typer.BadParameter("Template output must be a directory.")
+        if suffix:
+            raise typer.BadParameter("Template output must be a directory path.")
+        return "template", output_option
+
+    if output_option is None:
+        return "stdout", None
+
+    if output_option.exists() and output_option.is_dir():
+        return "directory", output_option
+
+    if output_option.suffix:
+        return "file", output_option
+
+    return "directory", output_option
+
+
+def write_output_file(target: Path, content: str) -> None:
+    """Persist LaTeX content to disk, creating parent directories as needed."""
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    except OSError as exc:  # pragma: no cover - filesystem errors
+        raise OSError(f"Failed to write LaTeX output to '{target}': {exc}") from exc
+
+
+def looks_like_document_path(candidate: str) -> bool:
+    """Return True when the string has an extension resembling a document."""
+    suffix = Path(candidate).suffix.lower()
+    return bool(suffix) and suffix in {
+        ".md",
+        ".markdown",
+        ".mdown",
+        ".mkd",
+        ".html",
+        ".htm",
+    }
+
+
+def normalise_selector(selector: str | None) -> str | None:
+    """Strip surrounding quotes and whitespace from user-provided selectors."""
+    if selector is None:
+        return None
+    candidate = selector.strip()
+    if len(candidate) >= 2 and candidate[0] == candidate[-1] and candidate[0] in {'"', "'"}:
+        candidate = candidate[1:-1].strip()
+    return candidate or None
+
+
+def parse_cli_slot_tokens(
+    values: Iterable[str] | None,
+) -> list[tuple[str, str | None, str | None, str]]:
+    """Tokenise slot overrides into (slot, path, selector, raw) tuples."""
+    tokens: list[tuple[str, str | None, str | None, str]] = []
+    if not values:
+        return tokens
+
+    for raw in values:
+        if not isinstance(raw, str):
+            continue
+        entry = raw.strip()
+        if not entry:
+            continue
+        if ":" not in entry:
+            raise typer.BadParameter(
+                f"Invalid slot override '{raw}', expected format "
+                f"'slot:selector' or 'slot:file[:selector]'."
+            )
+        slot_name, remainder = entry.split(":", 1)
+        slot_name = slot_name.strip()
+        remainder = remainder.strip()
+        if not slot_name or not remainder:
+            raise typer.BadParameter(
+                f"Invalid slot override '{raw}', expected format "
+                f"'slot:selector' or 'slot:file[:selector]'."
+            )
+
+        path_hint: str | None
+        selector_value: str | None
+        if ":" in remainder:
+            path_part, selector_part = remainder.split(":", 1)
+            path_part = path_part.strip()
+            selector_value = normalise_selector(selector_part)
+            path_hint = path_part or None
+        else:
+            if looks_like_document_path(remainder):
+                path_hint = remainder
+                selector_value = None
+            else:
+                path_hint = None
+                selector_value = normalise_selector(remainder)
+
+        tokens.append((slot_name, path_hint, selector_value, raw))
+
+    return tokens
+
+
+def resolve_slot_assignments(
+    tokens: list[tuple[str, str | None, str | None, str]],
+    documents: list[Path],
+) -> dict[Path, list[SlotAssignment]]:
+    """Resolve parsed slot tokens against provided documents."""
+    assignments: dict[Path, list[SlotAssignment]] = {doc: [] for doc in documents}
+    if not tokens:
+        return assignments
+
+    resolved_index = {doc.resolve(): doc for doc in documents}
+    name_index: dict[str, list[Path]] = {}
+    for doc in documents:
+        name_index.setdefault(doc.name, []).append(doc)
+
+    for slot_name, path_hint, selector_value, raw in tokens:
+        target_doc: Path | None = None
+        if path_hint is None:
+            if len(documents) == 1:
+                target_doc = documents[0]
+            else:
+                raise typer.BadParameter(
+                    f"slot override '{raw}' requires a document "
+                    "path when multiple inputs are provided."
+                )
+        else:
+            candidate_path = Path(path_hint)
+            resolved_candidate: Path | None = None
+            try:
+                base = (
+                    candidate_path if candidate_path.is_absolute() else Path.cwd() / candidate_path
+                )
+                resolved_candidate = base.resolve()
+            except OSError:
+                resolved_candidate = None
+
+            if resolved_candidate is not None and resolved_candidate in resolved_index:
+                target_doc = resolved_index[resolved_candidate]
+            else:
+                matches = name_index.get(candidate_path.name, [])
+                if len(matches) == 1:
+                    target_doc = matches[0]
+                elif len(matches) > 1:
+                    raise typer.BadParameter(
+                        f"slot override '{raw}' is ambiguous; multiple "
+                        f"documents match '{candidate_path.name}'."
+                    )
+
+        if target_doc is None:
+            raise typer.BadParameter(f"slot override '{raw}' does not match any provided document.")
+
+        selector_clean = selector_value
+        include_document = False
+        if selector_clean is None:
+            include_document = True
+        else:
+            token_lower = selector_clean.strip().lower()
+            if token_lower in {"*", DOCUMENT_SELECTOR_SENTINEL.lower()}:
+                include_document = True
+                selector_clean = None
+
+        assignments[target_doc].append(
+            SlotAssignment(
+                slot=slot_name, selector=selector_clean, include_document=include_document
+            )
+        )
+
+    return assignments
+
+
+def organise_slot_overrides(
+    values: Iterable[str] | None,
+    documents: list[Path],
+) -> tuple[dict[Path, dict[str, str]], dict[Path, list[SlotAssignment]]]:
+    """Produce slot selector overrides and assignments for downstream processing."""
+    tokens = parse_cli_slot_tokens(values)
+    assignments = resolve_slot_assignments(tokens, documents)
+
+    slot_overrides: dict[Path, dict[str, str]] = {}
+    for doc, entries in assignments.items():
+        if not entries:
+            continue
+        mapping = slot_overrides.setdefault(doc, {})
+        for entry in entries:
+            if entry.selector is not None:
+                mapping[entry.slot] = entry.selector
+
+    return slot_overrides, assignments

texsmith-0.0.2.dev0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: texsmith
+Version: 0.0.2.dev0
+Summary: A Markdown to LaTeX converter.
+Project-URL: Homepage, https://github.com/yves-chevallier/texsmith
+Author-email: Yves Chevallier <yves.chevalier@heig-vd.ch>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: convert,extensions,latex,markdown,mkdocs
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.14.2
+Requires-Dist: emoji>=2.12.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: markdown>=3.7
+Requires-Dist: pint>=0.24
+Requires-Dist: playwright>=1.56.0
+Requires-Dist: pybtex>=0.24.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pygments>=2.18.0
+Requires-Dist: pylatexenc>=2.10
+Requires-Dist: pymdown-extensions>=10.9
+Requires-Dist: pymupdf>=1.24.3
+Requires-Dist: python-markdown-math>=0.9
+Requires-Dist: python-slugify>=8.0.4
+Requires-Dist: pyxindy>=0.0.3
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=13.9.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12.5
+Requires-Dist: unicodeblocks>=0.3
+Description-Content-Type: text/markdown
+
+# TeXSmith
+
+[![CI](https://github.com/yves-chevallier/texsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/yves-chevallier/texsmith/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/yves-chevallier/texsmith/branch/main/graph/badge.svg)](https://codecov.io/gh/yves-chevallier/texsmith)
+[![PyPI](https://img.shields.io/pypi/v/texsmith.svg)](https://pypi.org/project/texsmith/)
+[![Repo Size](https://img.shields.io/github/repo-size/yves-chevallier/texsmith.svg)](https://github.com/yves-chevallier/texsmith)
+[![Python Versions](https://img.shields.io/pypi/pyversions/texsmith.svg?logo=python)](https://pypi.org/project/texsmith/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.md)
+
+![MkDocs](https://img.shields.io/badge/MkDocs-1.6+-blue.svg?logo=mkdocs)
+![MkDocs Material](https://img.shields.io/badge/MkDocs%20Material-supported-success.svg?logo=materialdesign)
+![Python](https://img.shields.io/badge/Python-typed-blue.svg?logo=python)
+
+TeXSmith is a [Python](https://www.python.org/) package and CLI tool to convert **Markdown** or **HTML** documents into LaTeX format. It is designed to be extensible via templates and integrates with [MkDocs](https://www.mkdocs.org/) for generating printable documents from documentation sites.
+
+<p align="center">
+<img src="docs/assets/ts-logo.svg" width="70%" />
+</p>
+
+## TL;DR
+
+```bash
+pip install texsmith
+texsmith input.md input.bib -o build/ --build
+```
+
+## Key features
+
+- **MkDocs-native Markdown** – Ships with the same Material + pymdown extension stack you use in MkDocs, so tabs, callouts, annotations, tooltips, and data tables survive the conversion.
+- **Template-first runtime** – Bundle multiple fragments into slots, merge front matter metadata, and emit LaTeX projects ready for Tectonic or latexmk with Docker-friendly manifests.
+- **CLI and Python parity** – The Typer-powered CLI wraps the same ConversionService you can consume as a library, making CI/CD and notebooks behave like local runs.
+- **Actionable diagnostics** – Structured emitters, verbosity switches, and `--debug` traces keep LaTeX issues debuggable even in automated pipelines.
+- **Extensible converters** – Override Markdown parsers, hook into RenderPhase handlers, or ship diagram transformers (Mermaid, Draw.io, Svgbob) that plug directly into the engine.
+
+## Installation
+
+```bash
+# uv (recommended for isolated CLI installs)
+uv tool install texsmith
+
+# pip / pipx
+pip install texsmith
+pipx install texsmith
+```
+
+TeXSmith targets Python 3.10+ and expects a LaTeX distribution (TeX Live, MiKTeX, or MacTeX) when you pass `--build`. Optional converters such as Mermaid rely on Docker (`minlag/mermaid-cli`) unless you register custom handlers.
+
+### Platform notes
+
+- **Linux** – Install TeX Live (full) via your package manager or `install-tl`. When running inside CI containers, cache `~/.texliveYY` so repeated latexmk runs stay fast—or use the default Tectonic engine to minimise setup.
+- **macOS** – Use [MacTeX](https://www.tug.org/mactex/) or `BasicTeX` plus the tlmgr packages reported by `texsmith --template <name> --template-info`. Homebrew’s `mactex` cask works well when paired with `uv`.
+- **Windows** – TeXSmith runs via native Python or WSL. For PDF builds we recommend [MiKTeX](https://miktex.org/) + PowerShell, or WSL2 with TeX Live and Docker Desktop (needed for Mermaid).
+- **Docker workflows** – Run `texsmith --build` inside a TeX Live container, mounting your project plus the template directory. Copy tlmgr prerequisites from `--template-info` so images compile without network access.
+
+See the [Getting Started guide](docs/guide/getting-started.md) for a step-by-step walkthrough, verification commands, and Python API examples.
+
+## Documentation
+
+Browse the full documentation at [yves-chevallier.github.io/texsmith](https://yves-chevallier.github.io/texsmith) for:
+
+- [Getting Started](docs/guide/getting-started.md): installation, prerequisites, and API snippets.
+- [CLI Reference](docs/cli/index.md): every flag, including the template inspector.
+- [Markdown Directory](docs/markdown/supported.md): exhaustive syntax coverage.
+- [API Reference](docs/api/index.md): ConversionService, TemplateSession, handlers, and plugins.
+- [Template Cookbook](docs/guide/template-cookbook.md): practical recipes for slots, overrides, packaging, and testing.
+- [Release Notes & Compatibility](docs/guide/release-notes.md): TeXSmith feature history plus template/TeX Live requirements.
+
+## Template catalog
+
+Inspect templates by name or path to understand their slots, metadata attributes, TeX Live requirements, and declared assets:
+
+```bash
+texsmith --template article --template-info
+# or inspect a local path
+texsmith --template ./templates/nature --template-info
+texsmith templates  # view discovery order across built-ins/packages/local/home
+```
+
+Use this command before wiring slots or when you need to confirm which tlmgr packages to preinstall in CI.
+
+## Examples
+
+The `examples/` directory includes reproducible demos:
+
+- `examples/paper` – end-to-end render with bibliographies and latexmk (or Tectonic with `--engine tectonic`).
+- `examples/diagrams` – Mermaid and Draw.io conversions.
+- `examples/markdown` – exhaustive Markdown showcase with diagram/front-matter overrides.
+
+Each example ships build instructions inside [`docs/examples/index.md`](docs/examples/index.md).
+
+## Project layout
+
+The source tree is organised around three top-level namespaces:
+
+- `texsmith.core` contains the conversion pipeline, document models, diagnostics, and template helpers.
+- `texsmith.adapters` hosts infrastructure integrations such as Markdown parsing, LaTeX rendering, Docker helpers, and transformer utilities.
+- `texsmith.ui` provides end-user interfaces, including the Typer-powered CLI.
+
+## Core architecture highlights
+
+- `ConversionService` encapsulates the orchestration that previously lived in `texsmith.api.service` helpers. Provide a `ConversionRequest` and receive a `ConversionResponse` with rendered bundles and diagnostics.
+- `TemplateRenderer` now owns slot aggregation and LaTeX assembly. `TemplateSession` focuses on session state, template options, and bibliography tracking.
+- `DocumentSlots` unify slot directives from front matter, CLI flags, and programmatic overrides. Every entry point now speaks the same data model.
+- `DiagnosticEmitter` replaces ad-hoc callback bags so warnings, errors, and structured events flow through a predictable interface (CLI uses `CliEmitter`; libraries can plug in their own).
+- Fragments use a `BaseFragment` + config dataclass model (`fragment = YourFragment()` export referenced by `fragment.toml` entrypoints). No legacy factories remain.
+
+### Programmatic conversions with `ConversionService`
+
+```python
+from pathlib import Path
+
+from texsmith.api.service import ConversionRequest, ConversionService
+
+service = ConversionService()
+request = ConversionRequest(
+    documents=[Path("docs/index.html")],
+    bibliography_files=[Path("references.bib")],
+    template="article",
+    render_dir=Path("build"),
+)
+prepared = service.prepare_documents(request)
+response = service.execute(request, prepared=prepared)
+
+print("Main TeX:", response.render_result.main_tex_path)
+print("Diagnostics:", [event.name for event in response.diagnostics])
+```
+
+If you only need a quick conversion, the high-level helpers (`texsmith.Document`, `texsmith.convert_documents`, `texsmith.TemplateSession`) continue to work, but they now reuse the same ConversionService plumbing as the CLI.
+
+> Refer to `UPGRADE.md` for release notes and migration guidance from earlier builds.
+
+## Render engine phases
+
+The rendering pipeline walks the BeautifulSoup tree four times. Each pass maps
+to a value of `RenderPhase` so handlers can opt into the point where their
+transform should fire:
+
+- `RenderPhase.PRE`: Early normalisation. Use it to clean the DOM and
+  replace nodes before structural changes happen (e.g. unwrap unwanted tags,
+  turn inline `<code>` into LaTeX).
+- `RenderPhase.BLOCK`: Block-level transformations once the tree structure
+  is stable. Typical consumers convert paragraphs, lists, or blockquotes into
+  LaTeX environments.
+- `RenderPhase.INLINE`: Inline formatting where block layout is already
+  resolved. It is the right place for emphasis, inline math, or link handling.
+- `RenderPhase.POST`: Final pass after children are processed. Use it for
+  tasks that depend on previous passes such as heading numbering or emitting
+  collected assets.