legaldown-render 0.2.0__tar.gz

legaldown_render-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/

legaldown_render-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForLegalAI
+
+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.

legaldown_render-0.2.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: legaldown-render
+Version: 0.2.0
+Summary: Reference renderer for the LegalDown legal document format: HTML and plain text, DOCX and PDF planned
+Project-URL: Homepage, https://github.com/ForLegalAI/legaldown-render
+Project-URL: Repository, https://github.com/ForLegalAI/legaldown-render
+Project-URL: Issues, https://github.com/ForLegalAI/legaldown-render/issues
+Project-URL: Specification, https://github.com/ForLegalAI/LegalDown
+Author: ForLegalAI s.r.o.
+Maintainer: ForLegalAI s.r.o.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: contracts,html,legal,legaldown,legaltech,markdown,renderer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: babel<3,>=2.14
+Requires-Dist: legaldown-validator<0.4,>=0.3.0
+Requires-Dist: markdown-it-py<5,>=3.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# legaldown-render 🖨️
+
+### The reference renderer for [LegalDown](https://github.com/ForLegalAI/LegalDown)
+
+**Turn a LegalDown document into HTML or plain text, with section numbers, cross-references,
+defined terms, and formatted values all generated at render time.**
+
+Targets specification **v0.2** · Conformance level **Rendering** · DOCX and PDF planned
+
+</div>
+
+---
+
+## What it does
+
+[LegalDown](https://github.com/ForLegalAI/LegalDown) documents never hardcode section numbers,
+reference text, or formatted values. The source says `{{ref: late-payment}}`, and the renderer
+turns it into "4.2(b)" with a link. This package is that renderer:
+
+🔢 **Numbers** sections, list items, and paragraphs under a configurable scheme (§13.1, §13.2).
+References to items resolve to designations such as "2.1(b)".
+
+🔗 **Resolves** cross-references, defined terms, parties, sides, and attachment references into
+display text with links (§13.3–§13.5).
+
+🌍 **Formats** dates, money, and durations for a locale chosen at render time. A Czech locale
+gives "1. června 2026", "10 000,00 Kč", and "12 měsíců", and amounts are never rounded (§10).
+
+🎨 **Applies a style template**, so the same source renders as a US-style contract or a
+continental one without editing the text (§13.7).
+
+📝 **Shows templates as templates, or fills them in.** Without answers, conditional clauses are
+marked, every `{{choose:}}` phrase is shown, drafting notes are styled, and placeholders render as
+blanks. With an answers set, the template is assembled and the finished document rendered (§15.8).
+
+🚩 **Never hides a problem.** Anything unresolved renders as a visible marker, such as
+`[BROKEN REF: id]`, and is reported with the specification's stable rule id. Nothing is dropped
+silently (§17.5).
+
+Parsing and Core validation come from
+[`legaldown-validator`](https://github.com/ForLegalAI/legaldown-validator), the reference parser.
+This package never reimplements the LegalDown grammar.
+
+## Install
+
+```bash
+pip install legaldown-render
+```
+
+Python 3.11 or newer. The dependencies are all pure Python: `legaldown-validator`,
+`markdown-it-py`, `babel`, and `pyyaml`.
+
+## Command line
+
+```bash
+legaldown-render contract.lgd -o contract.html                  # HTML page
+legaldown-render contract.lgd -o contract.txt                   # plain text (format from extension)
+legaldown-render contract.lgd --style continental --locale cs-CZ -o smlouva.html
+legaldown-render contract.lgd --set numbering.scheme=legal-outline --set enumeration.enabled=false
+legaldown-render contract.lgd --set contents.enabled=true --set contents.depth=3   # table of contents
+legaldown-render contract.lgd --strict                          # refuse if the document has errors
+legaldown-render contract.lgd --final --strict                  # refuse if blanks or template constructs remain
+legaldown-render template.lgd --answers answers.yaml -o nda.html # fill in a template, then render it
+legaldown-render --print-style --style continental              # every setting, as YAML
+```
+
+Diagnostics go to stderr, one per line with its rule id. The exit code is 0 when the document
+rendered, even if it has errors (they show as markers), 1 when rendering was refused (strict mode,
+or a template that cannot be assembled with its answers) or a file cannot be read, and 2 for an
+invalid style or setting.
+
+## Python
+
+```python
+from legaldown_render import render
+
+result = render(open("contract.lgd").read(), format="html", style="continental", locale="cs-CZ")
+for diagnostic in result.diagnostics:
+    print(diagnostic.level, diagnostic.rule, diagnostic.message)
+open("contract.html", "w").write(result.output)
+```
+
+`render()` also accepts a `RenderOptions`. Pass `answers={...}` to render a template filled in.
+Problems in the document never raise. Only an invalid style (`StyleError`), an unreadable document
+(`DocumentError`), strict mode, or a template that cannot be assembled with its answers
+(`RenderRefused`) do.
+
+## Styles and preferences
+
+A **style template** says how documents look: numbering, list enumeration, locale, labels,
+typography. It is a YAML file you can share across a team:
+
+```yaml
+version: 1
+extends: continental
+locale: cs-CZ
+numbering:
+  levels:
+    - { counter: decimal, label: "Článek {n}", ref: "{n}" }
+definitions: { style: small-caps }
+typography: { font_family: "Georgia, serif", justify: true }
+```
+
+**Render options** say what one job does: the output format, strict mode, the final check, the
+answers to a template, a full page or an HTML fragment. Values layer in this order: built-in defaults, then the `extends` chain, then your
+style, then per-job `--set` overrides. Every value is validated before rendering starts. See
+[Styles and preferences](docs/style-templates.md).
+
+Built-in styles are `default` (1. / 1.1, with (a) / (i) list items), `continental` (numbered
+articles, 2.1-style items, numbered paragraphs), and `outline` (I. / A. / 1. / a.).
+
+## Documentation
+
+| Document | What it covers |
+|---|---|
+| [Concepts](docs/concepts.md) | What a renderer is responsible for, principles, and vocabulary |
+| [Architecture](docs/architecture.md) | The pipeline, the render tree, the package layout, and testing |
+| [Styles and preferences](docs/style-templates.md) | The style format, layering, and every setting |
+| [Conformance](CONFORMANCE.md) | What the Rendering level requires, and what is covered |
+| [Roadmap](docs/roadmap.md) | Milestones, and the changes needed upstream |
+| [Decision records](docs/decisions/) | Why the main choices were made |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                       # unit, golden, and CLI tests
+pytest --update-golden       # regenerate tests/golden/ after an intended output change
+LEGALDOWN_SPEC_DIR=../LegalDown pytest -m conformance   # the specification's examples and fixtures
+ruff check .
+```
+
+Releases go to PyPI from a GitHub Release; see [PUBLISHING.md](.github/PUBLISHING.md).
+
+## License
+
+[MIT](LICENSE)

legaldown_render-0.2.0/README.md

@@ -0,0 +1,139 @@
+<div align="center">
+
+# legaldown-render 🖨️
+
+### The reference renderer for [LegalDown](https://github.com/ForLegalAI/LegalDown)
+
+**Turn a LegalDown document into HTML or plain text, with section numbers, cross-references,
+defined terms, and formatted values all generated at render time.**
+
+Targets specification **v0.2** · Conformance level **Rendering** · DOCX and PDF planned
+
+</div>
+
+---
+
+## What it does
+
+[LegalDown](https://github.com/ForLegalAI/LegalDown) documents never hardcode section numbers,
+reference text, or formatted values. The source says `{{ref: late-payment}}`, and the renderer
+turns it into "4.2(b)" with a link. This package is that renderer:
+
+🔢 **Numbers** sections, list items, and paragraphs under a configurable scheme (§13.1, §13.2).
+References to items resolve to designations such as "2.1(b)".
+
+🔗 **Resolves** cross-references, defined terms, parties, sides, and attachment references into
+display text with links (§13.3–§13.5).
+
+🌍 **Formats** dates, money, and durations for a locale chosen at render time. A Czech locale
+gives "1. června 2026", "10 000,00 Kč", and "12 měsíců", and amounts are never rounded (§10).
+
+🎨 **Applies a style template**, so the same source renders as a US-style contract or a
+continental one without editing the text (§13.7).
+
+📝 **Shows templates as templates, or fills them in.** Without answers, conditional clauses are
+marked, every `{{choose:}}` phrase is shown, drafting notes are styled, and placeholders render as
+blanks. With an answers set, the template is assembled and the finished document rendered (§15.8).
+
+🚩 **Never hides a problem.** Anything unresolved renders as a visible marker, such as
+`[BROKEN REF: id]`, and is reported with the specification's stable rule id. Nothing is dropped
+silently (§17.5).
+
+Parsing and Core validation come from
+[`legaldown-validator`](https://github.com/ForLegalAI/legaldown-validator), the reference parser.
+This package never reimplements the LegalDown grammar.
+
+## Install
+
+```bash
+pip install legaldown-render
+```
+
+Python 3.11 or newer. The dependencies are all pure Python: `legaldown-validator`,
+`markdown-it-py`, `babel`, and `pyyaml`.
+
+## Command line
+
+```bash
+legaldown-render contract.lgd -o contract.html                  # HTML page
+legaldown-render contract.lgd -o contract.txt                   # plain text (format from extension)
+legaldown-render contract.lgd --style continental --locale cs-CZ -o smlouva.html
+legaldown-render contract.lgd --set numbering.scheme=legal-outline --set enumeration.enabled=false
+legaldown-render contract.lgd --set contents.enabled=true --set contents.depth=3   # table of contents
+legaldown-render contract.lgd --strict                          # refuse if the document has errors
+legaldown-render contract.lgd --final --strict                  # refuse if blanks or template constructs remain
+legaldown-render template.lgd --answers answers.yaml -o nda.html # fill in a template, then render it
+legaldown-render --print-style --style continental              # every setting, as YAML
+```
+
+Diagnostics go to stderr, one per line with its rule id. The exit code is 0 when the document
+rendered, even if it has errors (they show as markers), 1 when rendering was refused (strict mode,
+or a template that cannot be assembled with its answers) or a file cannot be read, and 2 for an
+invalid style or setting.
+
+## Python
+
+```python
+from legaldown_render import render
+
+result = render(open("contract.lgd").read(), format="html", style="continental", locale="cs-CZ")
+for diagnostic in result.diagnostics:
+    print(diagnostic.level, diagnostic.rule, diagnostic.message)
+open("contract.html", "w").write(result.output)
+```
+
+`render()` also accepts a `RenderOptions`. Pass `answers={...}` to render a template filled in.
+Problems in the document never raise. Only an invalid style (`StyleError`), an unreadable document
+(`DocumentError`), strict mode, or a template that cannot be assembled with its answers
+(`RenderRefused`) do.
+
+## Styles and preferences
+
+A **style template** says how documents look: numbering, list enumeration, locale, labels,
+typography. It is a YAML file you can share across a team:
+
+```yaml
+version: 1
+extends: continental
+locale: cs-CZ
+numbering:
+  levels:
+    - { counter: decimal, label: "Článek {n}", ref: "{n}" }
+definitions: { style: small-caps }
+typography: { font_family: "Georgia, serif", justify: true }
+```
+
+**Render options** say what one job does: the output format, strict mode, the final check, the
+answers to a template, a full page or an HTML fragment. Values layer in this order: built-in defaults, then the `extends` chain, then your
+style, then per-job `--set` overrides. Every value is validated before rendering starts. See
+[Styles and preferences](docs/style-templates.md).
+
+Built-in styles are `default` (1. / 1.1, with (a) / (i) list items), `continental` (numbered
+articles, 2.1-style items, numbered paragraphs), and `outline` (I. / A. / 1. / a.).
+
+## Documentation
+
+| Document | What it covers |
+|---|---|
+| [Concepts](docs/concepts.md) | What a renderer is responsible for, principles, and vocabulary |
+| [Architecture](docs/architecture.md) | The pipeline, the render tree, the package layout, and testing |
+| [Styles and preferences](docs/style-templates.md) | The style format, layering, and every setting |
+| [Conformance](CONFORMANCE.md) | What the Rendering level requires, and what is covered |
+| [Roadmap](docs/roadmap.md) | Milestones, and the changes needed upstream |
+| [Decision records](docs/decisions/) | Why the main choices were made |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                       # unit, golden, and CLI tests
+pytest --update-golden       # regenerate tests/golden/ after an intended output change
+LEGALDOWN_SPEC_DIR=../LegalDown pytest -m conformance   # the specification's examples and fixtures
+ruff check .
+```
+
+Releases go to PyPI from a GitHub Release; see [PUBLISHING.md](.github/PUBLISHING.md).
+
+## License
+
+[MIT](LICENSE)

legaldown_render-0.2.0/docs/architecture.md

@@ -0,0 +1,247 @@
+# Architecture
+
+This page describes how the renderer is built. The decisions behind it are in
+[decision records](decisions/). Read [Concepts](concepts.md) first for the vocabulary, and
+[Styles and preferences](style-templates.md) for configuration.
+
+---
+
+## The pipeline
+
+```
+ source .lgd
+      │  normalize_source(): strip BOM, unify line endings
+      ▼
+ ┌─────────────────────────┐
+ │ 2. Assemble (answers)   │  only with an answers set: legaldown-validator's assemble() turns
+ └───────────┬─────────────┘  the template into its assembled document, which the rest renders
+             ▼
+ ┌─────────────────────────┐
+ │ 1. Parse & validate     │  legaldown-validator: Document, ValidationResult (Core diagnostics,
+ └───────────┬─────────────┘  resolved identifiers, party/side/definition/attachment lookups)
+             ▼
+ ┌─────────────────────────┐
+ │ 3. Build     build.py   │  source + validator → render tree (source inlines)
+ └───────────┬─────────────┘
+             ▼                style template (style/) ──┐
+ ┌─────────────────────────┐                            │
+ │ 4. Resolve   resolve/   │ ◄──────────────────────────┘  numbers, labels, anchors, display text,
+ └───────────┬─────────────┘                               failure markers + Rendering diagnostics
+             ▼
+ ┌─────────────────────────┐
+ │ 5. Write     writers/   │  html │ text   (docx, pdf later)
+ └───────────┬─────────────┘
+             ▼
+ RenderResult(output, diagnostics, format, tree, style)
+```
+
+Stage 2, **assembly** with an answers set (§15.7), runs only when the job has answers, before
+the document is parsed for rendering. A template rendered with answers is assembled first and the
+assembled document rendered; without answers, it renders as its **template view** (§15.8).
+Assembly is the core package's (`legaldown.assemble`), exact to the byte as §15.7.2 requires; the
+renderer only decides when to refuse:
+
+- the template has Errors: §15.7.2 defines assembly only for a template without them
+- the answers do (`answer-invalid`, `answer-missing`)
+- the template needs other files (include fragments, LegalDown attachment files, translations),
+  which the renderer does not read below the Full level (§17.6)
+
+A refusal raises `RenderRefused` with the findings. Assembly Warnings, such as `answer-unknown`,
+are reported with the rest. Blanks left unanswered stay, and render as blanks: the result is a
+draft (§15.1), which `--final` reports.
+
+`api.render()` runs the pipeline. Each stage returns frozen values. Only stage 4 reads the style's
+semantic settings, and only stage 5 knows about file formats.
+
+### 1. Parse and validate
+
+`legaldown.parse_document` and `legaldown.validate_document` provide:
+
+- the **metadata**: title, sides and parties, attachments, questions, language
+- the **section identifiers** exactly as the validator resolved them: explicit `{#id}`, or
+  generated by §5.3 with §5.5 collision handling. These come from `ValidationResult.sections`,
+  so the renderer can never compute a different anchor than the one the validator checked
+- **lookups** for definitions, parties, sides, and attachments, already reduced to display names
+  (§3.6)
+- the **Core diagnostics**, each with a stable rule id
+
+A document that cannot be read at all, such as one whose frontmatter is not a YAML mapping,
+raises `DocumentError`. Every other problem renders.
+
+### 3. Build the render tree (`build.py`)
+
+There is one parser: the validator's ([ADR 0007](decisions/0007-one-parser-validator-model.md)).
+The builder walks the validator's `Document` and turns each block into render-tree blocks. It
+never decides a structural or LegalDown question itself:
+
+| Question | Answered by |
+|---|---|
+| Sections, headings, identifiers | `Document.sections`, `ValidationResult.sections` |
+| Blocks: paragraphs, lists and items, quotes, tables, code, rules | `Document` blocks. List items hold blocks (nested lists, code, quotes, tables), and a quote's content is the validator's `quote_content()` |
+| Where a marker (`{#id when=…}`) is placed, and what it means | `ValidationResult.placed_markers`: each marker's block, field, offset, identifier, and condition |
+| Whether the document is a template | `ValidationResult.is_template` |
+| Whether a quote is a drafting note | The validator's `is_drafting_note()` |
+| Which list item a marker belongs to | `PlacedMarker.item`: the item's number among the list's items, in pre-order |
+| A lifted definition, `{{ref:}}` or `{{term:}}` block's source | The validator's `render_block()` |
+
+The few imports beyond the validator's public API (quote content, fence helpers, the
+answers-file reader) are all in `validator_bridge.py`, the list for roadmap item U3.
+
+Within one block's text, **markdown-it-py parses inline Markdown only**: emphasis, links, code
+spans, inline HTML. Directives are protected first by **sentinels**. Every directive, and every
+`"Term" {{def:}}` span, is replaced with a private-use token, `\ue000<nonce>:<n>\ue001`, so
+Markdown cannot reinterpret directive syntax, such as an underscore in an identifier. The nonce is
+random for each build, so no text in a document, whether written literally, as an entity, or
+percent-encoded, can pass for a sentinel. Emphasis that wraps only a defined term is dropped with
+it, because the style decides how defined terms look (§7.2). A `{{def:}}` becomes a sentinel
+that renders nothing, led by a punctuation character so that an emphasis closer just before it
+still closes. A defined term in a link title or alt text shows its term but is not the
+definition's anchor.
+
+An HTML block in the model (`kind="html"`), a comment block included, renders nothing (§8.6).
+Within a block's text, inline comments and tags are dropped; where one stood between two spaces,
+one space stays. The validator reports raw HTML other than comments (`raw-html`, §8.7). A heading
+in a list item or a quote (`kind="heading"`) is not a section (§4.1) and shows as a bold line.
+
+The builder never works around the validator's model. Where the model loses or misreads
+something, the output follows the model, and the gap is listed in `CONFORMANCE.md` and filed on
+the validator:
+- link reference definitions (`[label]: url`) render as paragraphs
+
+Guessing at lost structure was tried, and it traded each gap for new bugs.
+
+### 4. Resolve (`resolve/`)
+
+`Resolver.run()` works in three steps:
+
+1. **Survey.** It collects which definitions exist, whether template constructs are used, and
+   which placeholder ids are used with conflicting types (§10.7).
+2. **Structure.** Section numbers are the validator's own (`ValidationResult.sections`), so a
+   rendered number always matches the validator's: **alternatives** share a number (§15.8), and
+   a skipped heading level counts as 1. The style only formats them, the n-th part of a number
+   with the n-th level format. For paragraphs and list items, **alternatives** follow the
+   validator's rule, applied the same way: an alternative directly follows its
+   sibling, has the same identifier and a valid condition, and its full presence (its own condition
+   and every enclosing one) excludes that of every unit already holding the number (§15.4, the
+   validator's `exclusive()`). It then labels
+   list items by depth and top-level paragraphs, and allocates output anchors. Every anchor
+   target is registered with its **designation**: "4.2", "4.2(b)(ii)", or "Termination (a)"
+   under the `none` scheme.
+3. **Inlines.** It replaces every source inline with a resolved one:
+
+| Directive | Resolves to | Failure markers |
+|---|---|---|
+| `{{ref:}}` | `CrossRef(designation, anchor)` (§13.3). A ref to an unnumbered item or paragraph falls back to its section's designation, with `ref-not-enumerated` | `[BROKEN REF: id]` |
+| `{{term:}}` | `TermRef(label or term, def anchor)` (§7.3, §13.4) | `[UNDEFINED: id]` |
+| `"Term" {{def:}}` | `DefinedTerm` without quotation marks, anchored at `def:<id>` (§7.2) | n/a |
+| `{{date:}}` `{{money:}}` `{{duration:}}` | `Value`, formatted for the locale by Babel (ADR 0005) | `[INVALID DATE: …]`, `[INVALID AMOUNT: …]`, `[UNKNOWN CURRENCY: …]`, `[INVALID DURATION: …]`, `[INVALID DURATION UNIT: …]` |
+| `{{party:}}` `{{side:}}` | `Value(label or display name)` (§3.6) | `[INVALID PARTY: …]`, `[UNKNOWN PARTY: …]`, and the side forms |
+| `{{field:}}` | `Value(raw value)` | `[INVALID FIELD: …]` |
+| `{{placeholder:}}` | `Blank`, with the question's prompt if the style asks for it | `[INVALID PLACEHOLDER: …]`, `[UNKNOWN CURRENCY: …]`, `[INVALID DURATION UNIT: …]` |
+| `{{attach:}}` | `Value(label or title)`, linked to the attachment placeholder or file (§6.4) | `[UNKNOWN ATTACHMENT: id]` |
+| `{{choose:}}` | `Choice(all phrases)`, shown as `[a / b]` (§15.8) | `[INVALID CHOICE: q]` |
+| `{{include:}}` | Not processed at this level (§17.5), with `render-not-processed` | `[NOT PROCESSED: include path]` |
+| unknown name | Never printed verbatim (§11.5) | `[UNKNOWN DIRECTIVE: name]` |
+
+A `label` never hides a failure marker (§11.5). Frontmatter strings go through the same resolver,
+so placeholders in frontmatter render as blanks (§3.10).
+
+The resolver also builds the **title block** (effective date, sides and parties), **attachment
+placeholders** (§13.8; files are not read at this level), and **signature blocks** (§2.2, always
+with `legal_name`, per §3.6).
+
+**Anchors.** Section, item, paragraph, and attachment anchors use their identifiers. Definition
+anchors are `def:<id>`. Identifiers cannot contain `:`, so the two can never collide in HTML's
+single id space (§5.6). When alternatives share an identifier, only the first keeps the anchor,
+so ids stay unique. A definition's anchor is given out in one place, when its defined term is
+resolved. Terms in titles or alt text get none. After everything is resolved, one pass drops the
+link of any `{{term:}}` whose definition got no anchor, so term links always have a target.
+
+Under the `none` scheme, a section's designation is its heading text, computed by a text-only
+pass that gives out no anchors and leaves references out. Headings are numbered with their level
+clamped to 1–5, as the validator numbers them.
+
+### 5. Write (`writers/`)
+
+> **A writer contains no LegalDown rules.** `tree.assert_resolved()` rejects a tree that still
+> holds a source inline.
+
+| Writer | Notes |
+|---|---|
+| `TextWriter` | Plain text (§13.6). A soft line break inside a paragraph is a space, a hard break a new line, and lists are indented with their labels. It is the **test oracle** for resolution |
+| `HtmlWriter` | A self-contained HTML5 page, or with `standalone=False` just the `<article>`. Semantic markup, with labels as real text rather than CSS counters, and a stylesheet generated from the style's presentation settings, including print rules |
+| DOCX, PDF | Planned ([ADR 0004](decisions/0004-html-first.md)) |
+
+## Package layout
+
+```
+src/legaldown_render/
+├── __init__.py        public API, __version__, SPEC_VERSION, CONFORMANCE_LEVEL
+├── api.py             render(), render_file(), RenderOptions, RenderResult
+├── cli.py             the legaldown-render command
+├── errors.py          RenderError, DocumentError, RenderRefused, InternalError
+├── tree.py            render tree nodes (source and resolved inlines, blocks, document)
+├── build.py           stage 3
+├── resolve/
+│   ├── resolver.py    stage 4
+│   ├── numbering.py   counters, the §13.1 scheme presets, label templates
+│   └── values.py      Babel formatting of dates, money, durations
+├── style/
+│   ├── model.py       the style dataclasses (every field has a default)
+│   ├── loader.py      layering, extends, overrides, validation
+│   ├── labels.py      built-in labels per language (en, cs)
+│   └── builtin/       default.yaml, continental.yaml, outline.yaml
+└── writers/           html.py, text.py
+```
+
+## Dependencies
+
+| Dependency | Why |
+|---|---|
+| `legaldown-validator>=0.3.0,<0.4` | The only LegalDown parser; Core validation |
+| `markdown-it-py` | Inline Markdown inside one block's text (ADR 0007) |
+| `babel` | CLDR locale data (ADR 0005) |
+| `pyyaml` | Style templates |
+
+All of them are pure Python. The DOCX and PDF writers will bring their dependencies in as extras.
+
+The renderer uses the validator's public API (`legaldown`, `legaldown.validator`), except for
+the few names in `validator_bridge.py`: `quote_content` and `MAX_QUOTE_DEPTH`, the fence
+helpers, and the answers-file reader. The pin to one minor version exists because of them.
+Asking the validator to export them publicly is roadmap item U3
+([validator#93](https://github.com/ForLegalAI/legaldown-validator/issues/93)).
+
+## Errors and diagnostics
+
+- **Document problems** render as failure markers and are listed in `diagnostics`. `strict=True`
+  raises `RenderRefused` instead, carrying the diagnostics.
+- **Configuration problems** (an invalid style, setting, locale, or format) raise before
+  rendering, with every problem named.
+- **Internal inconsistencies** raise `InternalError`, and the CLI exits with 70.
+
+Diagnostics reuse `legaldown.Diagnostic`. The renderer adds rules only it can evaluate:
+`ref-not-enumerated`, a specification rule id, plus renderer-specific ids prefixed `render-`:
+`render-not-processed`, `render-locale-fallback`, and `render-ref-ambiguous`. The validator's
+diagnostics carry their line (§16.9), and the CLI prints it as `file:line:`. The renderer's own
+have none yet, because a block's line is not public in the validator (U2).
+
+## Security
+
+- Raw HTML in the source is never emitted (§8.7).
+- Every text node and attribute is escaped.
+- Links and images whose URL has a scheme other than `http`, `https`, `mailto`, or `tel` render
+  as text. markdown-it-py also refuses `javascript:`-style URLs when parsing.
+- At Rendering level, the only files read are the document and the style template. Attachment
+  files and includes are never opened.
+- Style values that are placed into CSS are stripped of `;{}<>`. `html.extra_css` is trusted
+  configuration, so a hosted service must not accept styles from untrusted users.
+
+## Testing
+
+| Suite | What it checks |
+|---|---|
+| `tests/test_golden.py` | The test documents under each built-in style, compared byte for byte with `tests/golden/`. Regenerate with `pytest --update-golden` and review the diff |
+| `tests/test_render.py` | Numbering schemes, designations, fallbacks, every failure marker, template view, labels by language, HTML safety, unique anchors, determinism, strict mode, locales |
+| `tests/test_style.py`, `tests/test_values.py` | Style layering and validation; counters and locale formatting |
+| `tests/test_cli.py` | The command |
+| `tests/conformance/` | Every example and fixture in the specification repository renders, every internal link has a target, and each invalid fixture renders its rule's failure marker. Needs `$LEGALDOWN_SPEC_DIR` or a sibling `../LegalDown` checkout |