cardreport 0.2.1__tar.gz

cardreport-0.2.1/.gitattributes

@@ -0,0 +1,2 @@
+# Preserve the bundled third-party license verbatim.
+src/cardreport/assets/LICENSE_DEJAVU -whitespace

cardreport-0.2.1/.github/workflows/main.yml

@@ -0,0 +1,142 @@
+name: CI and release
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      pypi_tag:
+        description: 'Publish an existing verified GitHub Release to PyPI (vX.Y.Z)'
+        required: true
+        type: string
+permissions:
+  contents: read
+concurrency:
+  group: cardreport-${{ github.event_name == 'workflow_dispatch' && 'pypi-dispatch' || github.ref }}
+  cancel-in-progress: false
+jobs:
+  setup-required:
+    if: github.event_name == 'workflow_dispatch' && (vars.PYPI_PUBLISH_ENABLED != 'true' || github.ref != 'refs/heads/main')
+    runs-on: ubuntu-24.04
+    steps:
+      - run: |
+          echo 'Select main, configure the PyPI Trusted Publisher and enable PYPI_PUBLISH_ENABLED first. See docs/project/releases.md.'
+          exit 1
+  verify:
+    if: github.event_name != 'workflow_dispatch'
+    runs-on: macos-15
+    timeout-minutes: 25
+    permissions:
+      contents: read
+      actions: read
+    outputs:
+      action: ${{ steps.plan.outputs.action }}
+      tag: ${{ steps.plan.outputs.tag }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          version: '0.10.6'
+      - name: Install native PDF libraries and dependencies
+        run: |
+          brew install pango
+          echo "DYLD_FALLBACK_LIBRARY_PATH=$(brew --prefix)/lib" >> "$GITHUB_ENV"
+          uv sync --all-extras --locked
+          uv run --all-extras python -m playwright install chromium
+      - name: Lint and types
+        run: |
+          uv run --all-extras ruff check src tests examples scripts
+          uv run --all-extras ruff format --check src tests examples scripts
+          uv run --all-extras mypy
+      - name: Runtime and documentation
+        run: |
+          uv run --all-extras pytest -q --junitxml=local/ci-tests.xml
+          uv run --all-extras python scripts/check_test_results.py local/ci-tests.xml
+          uv run --all-extras python scripts/check_docs.py
+      - id: plan
+        name: Select release candidate
+        run: python scripts/release.py plan
+      - id: restore
+        name: Restore this run's verified distribution on retry
+        if: github.event_name == 'push' && github.repository == 'arch7tect/cardreport'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/release.py restore
+      - name: Build and freeze distribution
+        if: steps.restore.outputs.restored != 'true'
+        run: |
+          uv build --no-sources
+          rm -f dist/.gitignore
+          python scripts/release.py freeze
+      - name: Check packaged files and installed wheel
+        run: |
+          uvx --from twine==7.0.0 twine check --strict dist/*.whl dist/*.tar.gz
+          uv run --all-extras python scripts/check_dist.py
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: steps.restore.outputs.restored != 'true'
+        with:
+          name: distribution
+          path: dist/
+          if-no-files-found: error
+          retention-days: 90
+  release:
+    needs: verify
+    if: github.event_name == 'push' && github.repository == 'arch7tect/cardreport' && needs.verify.outputs.action != 'skip'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distribution
+          path: dist/
+      - name: Tag and publish the verified GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: python scripts/release.py github
+      - name: Report PyPI setup status
+        if: vars.PYPI_PUBLISH_ENABLED != 'true'
+        run: echo 'PyPI upload is disabled until the Trusted Publisher is configured. See docs/project/releases.md.' >> "$GITHUB_STEP_SUMMARY"
+  pypi:
+    needs: [verify, release]
+    if: >-
+      always() && !cancelled() && github.repository == 'arch7tect/cardreport' &&
+      github.ref == 'refs/heads/main' && vars.PYPI_PUBLISH_ENABLED == 'true' &&
+      (needs.release.result == 'success' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          version: '0.10.6'
+      - name: Download and verify the canonical release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.pypi_tag || needs.verify.outputs.tag }}
+        run: python scripts/release.py download --tag "$RELEASE_TAG"
+      - name: Publish the same bytes using Trusted Publishing
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/ dist/*.whl dist/*.tar.gz

cardreport-0.2.1/.gitignore

@@ -0,0 +1,24 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local IDE, configuration, and generated reports
+.idea/
+.env
+.env.*
+!.env.template
+output/
+local/
+.DS_Store
+
+# Local check caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

cardreport-0.2.1/.python-version

@@ -0,0 +1 @@
+3.12

cardreport-0.2.1/AGENTS.md

@@ -0,0 +1,30 @@
+# CardReport contributor instructions
+
+Use Python 3.12+ and uv. Write source, comments and documentation in English.
+Read docs/project/architecture.md and the relevant decision before changing the
+public API. Keep README.md and docs/user/api.md aligned with implemented behavior.
+README is the user entry point; tutorials/reference live in docs/user. Project
+rationale lives in docs/project; dated history is not the current API contract.
+
+Chromium is the production default. The provisional Renderer protocol also supports
+an experimental SVG/WeasyPrint subset. See docs/user/renderers.md for capabilities
+and docs/project/decisions/renderer-extension.md for rationale. Keep renderers behind
+typed public components. No arbitrary Plotly kwargs, user HTML/CSS or template
+plugins. Prefer small concrete modules to a framework; no BI server, query layer,
+telemetry or network-dependent report assets.
+
+Use uv sync --all-extras --locked for development and uv build for packaging.
+Follow docs/project/development.md for checks; validate snippets and links with
+uv run --all-extras python scripts/check_docs.py when changing documentation.
+PDF implementation must include selected-engine integration checks, output
+inspection, font readiness, hostile-label coverage and overflow rejection. Browser
+lifecycle checks apply only if the browser candidate is selected. Never silently
+shrink, truncate or rasterize unsupported content. Add meaningful tests with
+implementation, not tests for the existence of scaffold files.
+
+Keep .venv, .idea, local config and generated reports ignored. Do not overwrite
+existing reports by default. A user-authorized version bump pushed to main requests
+release through .github/workflows/main.yml. That workflow may create the matching
+tag/GitHub Release and publish the same verified assets to PyPI when its setup gate
+is enabled. Never move released tags or replace released artifacts. Repository
+creation and unrelated publication still require a request. See docs/project/releases.md.

cardreport-0.2.1/LICENSE

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

cardreport-0.2.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: cardreport
+Version: 0.2.1
+Summary: Composable Python reports with cards, constrained charts, and HTML-to-PDF output
+Project-URL: Repository, https://github.com/arch7tect/cardreport
+Project-URL: Documentation, https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md
+Project-URL: Issues, https://github.com/arch7tect/cardreport/issues
+Author: Oleg Orlov
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fonttools<5,>=4.59
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: plotly<7,>=6.9
+Provides-Extra: pandas
+Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
+Provides-Extra: pdf
+Requires-Dist: playwright==1.64.1; extra == 'pdf'
+Requires-Dist: psutil<8,>=7; extra == 'pdf'
+Requires-Dist: pypdf<7,>=6; extra == 'pdf'
+Provides-Extra: weasyprint
+Requires-Dist: matplotlib==3.11.2; extra == 'weasyprint'
+Requires-Dist: pdfplumber<1,>=0.11.10; extra == 'weasyprint'
+Requires-Dist: psutil<8,>=7; extra == 'weasyprint'
+Requires-Dist: pypdf<7,>=6; extra == 'weasyprint'
+Requires-Dist: weasyprint==70.0; extra == 'weasyprint'
+Description-Content-Type: text/markdown
+
+# CardReport
+
+[![Latest release](https://img.shields.io/github/v/release/arch7tect/cardreport)](https://github.com/arch7tect/cardreport/releases/latest)
+[![PyPI version](https://img.shields.io/pypi/v/cardreport)](https://pypi.org/project/cardreport/)
+
+Build static reports in Python from cards, KPIs, charts and tables. Compose a
+report, then get standalone HTML or PDF bytes for your application. PDF text is
+selectable and charts are vector graphics.
+
+## Install in your project
+
+Python 3.12+ is required. Install from PyPI with uv, then install the PDF browser runtime:
+
+```sh
+uv add "cardreport[pdf]"
+uv run python -m playwright install chromium
+```
+
+Keep your application’s uv.lock to pin the installed version. For HTML-only use, omit `[pdf]` and the
+browser-install command. See [installation and quickstart](https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md)
+for local checkouts, wheels and how to embed exports.
+
+## Use from Python
+
+```python
+from cardreport import BarChart, Card, KPI, Report
+
+report = Report("Call results")
+report.add(Card(KPI("Total calls", 34)))
+report.row(
+    Card(BarChart(labels=["Answered", "No answer"], values=[24, 10])),
+    height_mm=70,
+)
+
+html: str = report.to_html()
+pdf: bytes = report.to_pdf()
+```
+
+Return `pdf` from your application, put it in storage, or use
+`report.write_pdf("report.pdf")` to save a file. Existing files are preserved by
+default. Reports reject content that does not fit rather than silently shrinking it.
+
+## Documentation
+
+- [Quickstart](https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md) — build from application data; return strings/bytes.
+- [Templates](https://github.com/arch7tect/cardreport/blob/main/docs/user/templates.md) — JSON presentation with separate named datasets.
+- [Datasets](https://github.com/arch7tect/cardreport/blob/main/docs/user/datasets.md) — native Python data and typed JSON storage.
+- [User guide](https://github.com/arch7tect/cardreport/blob/main/docs/user/guide.md) — cards, layout, formatting and multiple pages.
+- [API reference](https://github.com/arch7tect/cardreport/blob/main/docs/user/api.md) — signatures, defaults, constraints and errors.
+- [Renderers](https://github.com/arch7tect/cardreport/blob/main/docs/user/renderers.md) — installation, supported features and extensions.
+- [Examples and integration](https://github.com/arch7tect/cardreport/blob/main/docs/user/examples.md) — the original report, tables and async code.
+- [Command-line examples](https://github.com/arch7tect/cardreport/blob/main/docs/user/command-line.md) — optional script runners.
+
+Chromium is the default renderer. The experimental SVG/WeasyPrint renderer works
+without JavaScript or a browser, with a smaller supported feature set. Both can
+render the [original reference example](https://github.com/arch7tect/cardreport/blob/main/docs/user/examples.md#reference-report).
+Local macOS/Python 3.12 is verified; Linux and Windows are not yet verified.
+
+For architecture, decisions and contributing, see [project documentation](https://github.com/arch7tect/cardreport/blob/main/docs/project/README.md).
+
+## License
+
+[MIT](https://github.com/arch7tect/cardreport/blob/main/LICENSE). Bundled DejaVu fonts retain their [font license](https://github.com/arch7tect/cardreport/blob/main/src/cardreport/assets/LICENSE_DEJAVU).
+Third-party rendering packages retain their own licenses.

cardreport-0.2.1/README.md

@@ -0,0 +1,64 @@
+# CardReport
+
+[![Latest release](https://img.shields.io/github/v/release/arch7tect/cardreport)](https://github.com/arch7tect/cardreport/releases/latest)
+[![PyPI version](https://img.shields.io/pypi/v/cardreport)](https://pypi.org/project/cardreport/)
+
+Build static reports in Python from cards, KPIs, charts and tables. Compose a
+report, then get standalone HTML or PDF bytes for your application. PDF text is
+selectable and charts are vector graphics.
+
+## Install in your project
+
+Python 3.12+ is required. Install from PyPI with uv, then install the PDF browser runtime:
+
+```sh
+uv add "cardreport[pdf]"
+uv run python -m playwright install chromium
+```
+
+Keep your application’s uv.lock to pin the installed version. For HTML-only use, omit `[pdf]` and the
+browser-install command. See [installation and quickstart](https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md)
+for local checkouts, wheels and how to embed exports.
+
+## Use from Python
+
+```python
+from cardreport import BarChart, Card, KPI, Report
+
+report = Report("Call results")
+report.add(Card(KPI("Total calls", 34)))
+report.row(
+    Card(BarChart(labels=["Answered", "No answer"], values=[24, 10])),
+    height_mm=70,
+)
+
+html: str = report.to_html()
+pdf: bytes = report.to_pdf()
+```
+
+Return `pdf` from your application, put it in storage, or use
+`report.write_pdf("report.pdf")` to save a file. Existing files are preserved by
+default. Reports reject content that does not fit rather than silently shrinking it.
+
+## Documentation
+
+- [Quickstart](https://github.com/arch7tect/cardreport/blob/main/docs/user/quickstart.md) — build from application data; return strings/bytes.
+- [Templates](https://github.com/arch7tect/cardreport/blob/main/docs/user/templates.md) — JSON presentation with separate named datasets.
+- [Datasets](https://github.com/arch7tect/cardreport/blob/main/docs/user/datasets.md) — native Python data and typed JSON storage.
+- [User guide](https://github.com/arch7tect/cardreport/blob/main/docs/user/guide.md) — cards, layout, formatting and multiple pages.
+- [API reference](https://github.com/arch7tect/cardreport/blob/main/docs/user/api.md) — signatures, defaults, constraints and errors.
+- [Renderers](https://github.com/arch7tect/cardreport/blob/main/docs/user/renderers.md) — installation, supported features and extensions.
+- [Examples and integration](https://github.com/arch7tect/cardreport/blob/main/docs/user/examples.md) — the original report, tables and async code.
+- [Command-line examples](https://github.com/arch7tect/cardreport/blob/main/docs/user/command-line.md) — optional script runners.
+
+Chromium is the default renderer. The experimental SVG/WeasyPrint renderer works
+without JavaScript or a browser, with a smaller supported feature set. Both can
+render the [original reference example](https://github.com/arch7tect/cardreport/blob/main/docs/user/examples.md#reference-report).
+Local macOS/Python 3.12 is verified; Linux and Windows are not yet verified.
+
+For architecture, decisions and contributing, see [project documentation](https://github.com/arch7tect/cardreport/blob/main/docs/project/README.md).
+
+## License
+
+[MIT](https://github.com/arch7tect/cardreport/blob/main/LICENSE). Bundled DejaVu fonts retain their [font license](https://github.com/arch7tect/cardreport/blob/main/src/cardreport/assets/LICENSE_DEJAVU).
+Third-party rendering packages retain their own licenses.

cardreport-0.2.1/docs/project/README.md

@@ -0,0 +1,38 @@
+# Project documentation
+
+[User documentation](../../README.md)
+
+These documents explain implementation and maintenance. Application developers
+should begin with the [quickstart](../user/quickstart.md) and [API reference](../user/api.md).
+
+## Current implementation
+
+- [Release operations](releases.md) — version bumps, GitHub/PyPI setup and recovery.
+
+- [Architecture](architecture.md) — module boundaries, snapshots and rendering.
+- [Development](development.md) — setup, checks, packaging and documentation maintenance.
+- [Renderer extension decision](decisions/renderer-extension.md) — current extension scope.
+
+## Decisions and history
+
+- [Release automation review](history/reviews/2026-11-04-release-automation.md) — implementation findings and verification.
+
+- [Template implementation review](history/reviews/2026-11-04-template-implementation.md) — delivery, advisory findings and release checks.
+
+- [Template implementation plan](template-implementation-plan.md) — six delivery slices with documentation and acceptance checks.
+- [JSON templates and named datasets](decisions/report-templates.md) — implemented extension above the Python API.
+- [Template architecture review](history/reviews/2026-11-04-template-architecture.md) — findings, scope decisions and verification.
+- [Initial backend selection](decisions/backend-selection.md) — historical Chromium selection.
+- [Original design](history/design.md) — reviewed baseline, superseded where current docs differ.
+- [Implementation plan](history/implementation-plan.md) — completed initial stages.
+- [Implementation status](history/implementation-status.md) — dated delivery record.
+- [P0 comparison](history/p0-results.md) — original renderer experiment.
+- [Reference inventory](history/reference-report.md) — source composition and provenance.
+- [Architecture audit](history/reviews/2026-11-03-architecture-audit.md).
+- [Renderer refactor and verification](history/reviews/2026-11-04-renderer-refactor.md).
+- [Final renderer advisory review](history/reviews/2026-11-04-claude-refactor-final.md).
+- [Documentation review and verification](history/reviews/2026-11-04-documentation.md).
+
+Other dated [review records](history/reviews) preserve the earlier discussions.
+History documents record what was decided/tested at that time; they are not the
+current user API specification. No report evidence or original source PDF is published.

cardreport-0.2.1/docs/project/architecture.md

@@ -0,0 +1,100 @@
+# Architecture
+
+[Project documentation](README.md) · [Public API](../user/api.md)
+
+CardReport is a Python library. Applications own data access and business metrics.
+The library owns typed composition, semantic validation, rendering and output
+publication. It has no service, query layer, plugin registry or custom geometry IR.
+
+## Export path
+
+```text
+Optional ReportTemplate + named Dataset snapshots
+  -> bind -> Report + frozen components
+  -> semantic validation and chart normalization
+  -> frozen ReportDocument
+  -> Renderer (HTML preview or checked PDF)
+  -> optional atomic file publication
+```
+
+`Report` is a mutable builder. Components copy their input sequences and table rows.
+Validation checks structure, values, formats, glyph coverage and bounds on input
+size. It creates a snapshot retaining the public component types and a read-only
+mapping of normalized chart data. Chart coordinates are floats; value labels are
+formatted from original values. Strings remain unescaped until output generation.
+A snapshot contains no page coordinates. PDF deadlines start before validation.
+
+## Modules
+
+| Module | Responsibility |
+| --- | --- |
+| [data.py](../../src/cardreport/data.py) | Immutable tables, schemas, bounded native and tagged JSON input |
+| [templates.py](../../src/cardreport/templates.py) | Closed JSON grammar and binding to existing components |
+| [_inputs.py](../../src/cardreport/_inputs.py) | Shared bounded parsing and located errors |
+| [adapters](../../src/cardreport/adapters/) | Single CSV file and lazy optional pandas ingestion |
+| [model.py](../../src/cardreport/model.py) | Components, aliases, formats, errors and Report facade |
+| [validation.py](../../src/cardreport/validation.py) | Independent semantic checks and normalization |
+| [document.py](../../src/cardreport/document.py) | Frozen export and chart records |
+| [renderers.py](../../src/cardreport/renderers.py) | Provisional Renderer Protocol and Chromium entry point |
+| [html.py](../../src/cardreport/html.py) | Escaped shared fragments and Chromium HTML document |
+| [charts.py](../../src/cardreport/charts.py) | Private Plotly specification adapter |
+| [pdf.py](../../src/cardreport/pdf.py) | Owned worker, deadline, error transport and cleanup |
+| [output.py](../../src/cardreport/output.py) | Atomic publication and no-clobber policy |
+| [weasyprint.py](../../src/cardreport/weasyprint.py) | Experimental renderer and capability checks |
+
+## Chromium
+
+The HTML embeds fonts, Plotly (when needed), settings and the
+[layout script](../../src/cardreport/assets/layout.js). The browser loads fonts,
+places blocks on fixed pages, fragments top-level flow tables, draws charts and
+checks page/component/chart-label bounds. Plotly DOM inspection stays within this
+engine. `window.cardreport` signals ready/pages or a typed error; the
+[worker](../../src/cardreport/_worker.py) waits, prints and checks page count.
+Network requests are blocked. PDF export runs in an owned subprocess to avoid
+caller event-loop conflicts and to stop the process tree on timeout/interruption.
+
+## Experimental WeasyPrint
+
+Capabilities are defined in the [user-facing table](../user/renderers.md#capabilities).
+The engine reuses validated components, shared markup, themes and publication.
+It owns native layout and checks; it does not reuse Chromium pagination code.
+
+The [box adapter](../../src/cardreport/_weasy_boxes.py) isolates private WeasyPrint
+70.0 geometry. Positive/negative bundled-font canaries fail closed on incompatibility.
+Two document layout passes measure placeholders and verify final SVG placement.
+[Matplotlib SVG bars](../../src/cardreport/_svg_charts.py) use isolated default settings
+and the bundled font. A separate native SVG preflight checks actual PDF glyph bounds
+with pdfplumber, because Matplotlib and native text metrics can differ.
+[PDF checks](../../src/cardreport/_pdf_checks.py) recurse through form resources and
+compare embedded font identity/version with bundled fonts.
+
+The [worker](../../src/cardreport/_weasy_worker.py) allows only exact bundled font
+URLs and rejects any other attempted fetch. Its version-specific fetcher flag is
+also tied to the WeasyPrint pin. Native system-library setup belongs to the caller.
+Unsupported features fail explicitly rather than switching engines or weakening checks.
+
+## Maintenance boundaries
+
+Keep the component vocabulary closed and strongly typed. A new component requires
+validation, rendering support or explicit rejection, API documentation and tests.
+New renderer implementations satisfy the shared semantic/error/output contract,
+while owning their geometry and lifecycle. Do not add a registry or inheritance
+framework merely to reuse helpers. See the [extension decision](decisions/renderer-extension.md)
+for the rationale and the [development guide](development.md) for verification.
+
+## Separate presentation and data
+
+Version 0.2.0 adds a layer above Report, with independent `cardreport.template/1`
+and `cardreport.data/1` envelopes. Templates snapshot a bounded validated definition;
+Dataset copies native rows and fixed-offset datetimes. Schemas distinguish missing,
+null and empty input. Binding checks every declared contract, constructs ordinary
+components and calls existing validation; no unresolved expressions reach renderers.
+Semantic errors map known component paths back to template paths, preserving causes.
+Static validation uses one representative row per declared field type plus explicit
+binding/type checks. Real row counts, values and geometry are checked later.
+
+`from_csv` requires a schema and uses the standard library. `from_pandas` imports its
+optional dependency only on invocation. Neither source access nor normalization is
+part of bind/render. No source registry, SQL execution, directory scanner, expressions
+or model-to-template serializer is introduced. See the [decision](decisions/report-templates.md)
+and [delivery plan](template-implementation-plan.md).

cardreport-0.2.1/docs/project/decisions/backend-selection.md

@@ -0,0 +1,107 @@
+# Rendering backend decision gate
+
+> Update 2026-11-03: the owner authorized typed components, independent validation
+> and a provisional renderer extension with an experimental SVG/WeasyPrint path.
+> See [renderer extension](renderer-extension.md); the original decision below is historical.
+
+
+Date: 2026-11-03. Status: A selected for v0.1 after a local comparative experiment and Claude review.
+Owner: Oleg Orlov. Current result: [P0 findings](../history/p0-results.md) and
+[Claude checkpoint](../history/reviews/2026-11-03-claude-p0.md). The user subsequently authorized
+autonomous implementation and routine internal choices. A provides direct measured
+overflow checks without a second layout engine. Final implementation verification
+is tracked in [implementation status](../history/implementation-status.md).
+
+The sections below preserve the original decision criteria and candidate discussion;
+future-tense experiment/install statements describe the pre-implementation state.
+This record supersedes any unconditional choice of Chromium
+in the initial draft. There will be one production renderer, not a plugin system.
+
+## Requirement and review outcome
+
+The user wants a small CardReport API with cards, KPIs, constrained charts, rows
+and columns. Interactivity is unnecessary. The user explicitly asked to keep a
+JavaScript-free and browser-free option open and consult Claude.
+
+[Claude's comparison](../history/reviews/2026-11-03-claude-backends.md) recommends testing
+static Python-generated SVG + Jinja2 + WeasyPrint first, with Plotly + Jinja2 +
+Chromium as fallback. This is advice based on document review, not tested evidence.
+The maintainer has not selected a final renderer. The external API remains the
+same in both candidates.
+
+## Candidates
+
+| Concern | A: Plotly + Chromium | B: static SVG + WeasyPrint |
+| --- | --- | --- |
+| Charts | Mature private chart adapter; disable interaction and force SVG traces | Matplotlib SVG or a deliberately small direct-SVG subset; no Plotly |
+| Installation | Playwright plus explicitly installed Chromium/system libraries | WeasyPrint with Pango and related native libraries; Matplotlib adds dependencies |
+| Report layout | Browser is sole measurement/layout authority | WeasyPrint is final PDF authority; usable geometry/overflow strategy must be proved |
+| Preview | Standalone HTML needs JavaScript; test against the pinned Chromium | Static HTML has no JavaScript, but browser and PDF layout may differ |
+| Hard part | Readiness, label sizing, browser lifecycle and PDF inspection | Text metrics, CSS support, overflow checks and possibly chart/line-breaking code |
+
+The [Plotly documentation](https://plotly.com/python/static-image-export/)
+confirms that current Kaleido static export needs Chrome; it is not candidate B.
+[WeasyPrint installation](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html)
+requires Pango, so browser-free does not mean system-dependency-free.
+[WeasyPrint API/versioning](https://doc.courtbouillon.org/weasyprint/stable/api_reference.html)
+warns that rendering may change across major releases and private APIs are not stable.
+[Matplotlib fonts](https://matplotlib.org/stable/users/explain/text/fonts.html)
+describes SVG text output options. Preserving text nodes alone does not prove
+selectable text or font fidelity after conversion to PDF.
+
+## Disposition of Claude's recommendations
+
+Accepted: keep B open; no automatic backend abstraction; evaluate selectable text,
+fonts, clipping, native installation and table splitting on actual output; keep
+browser-specific implementation conditional. No backend implementation is included
+in the project-creation task.
+
+Qualified: Claude favors direct SVG and Python-owned geometry/line breaking. This
+would create chart axes, legends, wrapping and pagination code. It is not accepted
+as an architectural decision without evidence that it is simpler to maintain than
+Matplotlib or the existing browser engine. A bundled font reduces metric drift but
+does not prove identical layout across FreeType, Pango and a preview browser.
+
+Rejected as a pass condition: dependence on undocumented WeasyPrint box-tree APIs
+must not silently count as success. Any need for private APIs or a second text
+layout engine is a recorded decision tradeoff, not a default implementation detail.
+Resource loading must allow exact bundled font/image resources via a controlled
+resolver; a blanket failing URL fetcher would also break those embedded assets.
+No network or arbitrary filesystem loading is allowed.
+
+Claude's sample reused the old 90 mm / [3,1] geometry. Use the corrected 100 mm /
+[2,1] fixture from design.md so the KPI share exceeds its 28 mm minimum.
+
+## Small staged experiment (future implementation work)
+
+1. One shared fixture: A4 landscape, 3 KPI cards, weighted nested row/column,
+   funnel, grouped bar, date line with a gap; long English/Cyrillic labels and
+   literal markup; a deliberate overflow variant. Use synthetic data only.
+2. Produce A and B versions outside src, with no common backend framework.
+   First test Matplotlib SVG with text retained; test direct SVG only for the
+   representative bar/funnel if that could materially simplify dependency/code cost.
+3. Check selectable expected labels and numbers, no raster images, no clipping,
+   pinned-font use, visual alignment, explicit overflow failure and zero external
+   fetches. Compare measured text/box positions with an initial 0.5 mm tolerance.
+4. If B passes dashboard checks, test a separate 120-row flow report with repeated
+   headings, exactly-once row IDs and oversized-row rejection. Flow remains Slice 2,
+   but this probe must reveal whether the later requirement is achievable.
+5. Record installation steps, dependency footprint, code needed and failures on
+   macOS and Linux. Windows support remains unspecified; confirm before claiming
+   cross-platform readiness. Do not install new OS packages silently as part of
+   this design-only task.
+
+Select B only if vector/selectable text, layout, reliable overflow detection and
+acceptable installation pass without disproportionate chart/layout code. Otherwise
+retain A and record the concrete failing gate. If neither passes, revise the
+requirements or design explicitly; do not weaken no-clipping guarantees silently.
+For B, the PDF is authoritative and browser preview is approximate unless fixtures
+prove parity for the supported subset. Resolve this contract before implementation.
+
+## Dependency status
+
+The uv scaffold initially resolved Jinja2, Plotly and Playwright for candidate A.
+These are not a final runtime commitment. Candidate-A packages are now in the
+optional browser extra. B dependencies will be added only for the comparative
+spike or after selection; WeasyPrint/Matplotlib are not tested or installed by
+this task. Chromium is not downloaded by this task.