tempest-fastapi-sdk 0.87.1__tar.gz → 0.89.0__tar.gz

{tempest_fastapi_sdk-0.87.1 → tempest_fastapi_sdk-0.89.0}/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.89.0] — 2026-07-04
+
+### Added
+
+- **Typed server-side rendering (`tempest_fastapi_sdk.ssr`, extra
+  `[ssr]`).** A first-class SSR surface: FastAPI routes return typed
+  Python components rendered to HTML — full-stack, typed, no template
+  language.
+  - `Page` — a typed component base (`tempest_core` `Component`). Declare
+    typed fields, implement `body() -> Widget`, and optionally override
+    `shell(body)` to wrap every page in a shared header/nav/footer layout
+    inherited through normal Python inheritance. `render()` composes
+    `shell(body())` for you.
+  - `html_response(widget, *, title=None, status_code=200, htmx=False,
+    document=True, lang="pt-BR")` — renders a widget tree to a FastAPI
+    `HTMLResponse`. `document=True` emits a full HTML5 document (requires
+    `title`); `document=False` emits a bare fragment for HTMX partial
+    swaps. `htmx=True` injects a locally-served HTMX `<script>` tag
+    (never a CDN).
+  - `make_htmx_router(prefix="/_ssr")` — serves a **bundled** HTMX 2.x
+    (shipped inside the wheel) at `GET {prefix}/htmx.js` with an
+    `application/javascript` media type — CSP- and offline-friendly, no
+    external host contacted.
+  - The renderer (`tempestweb`) is imported lazily, so
+    `import tempest_fastapi_sdk` never hard-requires the extra; install
+    with `pip install "tempest-fastapi-sdk[ssr]"`.
+
+## [0.88.0] — 2026-07-03
+
+### Added
+
+- **Split-endpoint presigned URLs for MinIO/S3.** `AsyncMinIOClient`
+  gained `public_endpoint` / `public_secure` args, and `MinIOSettings`
+  the matching `MINIO_PUBLIC_ENDPOINT` / `MINIO_PUBLIC_SECURE`. When set,
+  `presigned_get_url` / `presigned_put_url` are signed against the public
+  host (so the browser can reach them) while every server-side operation
+  keeps using the internal `MINIO_ENDPOINT` (fast private network). A
+  second `minio.Minio` client signs the URLs — the host is part of the
+  SigV4 signature, so it must be signed against the public endpoint
+  rather than rewritten afterwards. Fully opt-in: without
+  `MINIO_PUBLIC_ENDPOINT`, presigned URLs are signed with `MINIO_ENDPOINT`
+  as before. A `https://` scheme (or trailing path) on the public
+  endpoint is tolerated and stripped; `https://` implies HTTPS.
+
 ## [0.87.1] — 2026-07-02
 
 ### Fixed

{tempest_fastapi_sdk-0.87.1 → tempest_fastapi_sdk-0.89.0}/CLAUDE.md

@@ -114,6 +114,14 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   `ort-vision-sdk`: lazy `Detector`/`Classifier`/`Segmenter` + prediction
   schemas + `to_detection_schemas`/`to_classification_schema`/
   `to_segmentation_schemas` mappers.
+- **SSR** (`[ssr]` extra) — `tempest_fastapi_sdk.ssr`: typed Python
+  pages rendered to HTML via `tempestweb`'s `render_to_html` /
+  `render_document`. `Page` (typed `Component` base — `body()` +
+  overridable `shell()` layout), `html_response` (widget tree →
+  `HTMLResponse`, full document or bare HTMX fragment), and
+  `make_htmx_router` (serves a wheel-bundled HTMX 2.x locally, no CDN).
+  `tempestweb` imported lazily so `import tempest_fastapi_sdk` never
+  needs the extra.
 - **Upload** — `UploadUtils` with pluggable backends
   (`LocalUploadStorage`, `MinIOUploadStorage`), download helpers,
   presigned URLs.

{tempest_fastapi_sdk-0.87.1 → tempest_fastapi_sdk-0.89.0}/Makefile

@@ -65,6 +65,8 @@ smoke: build ## Install the freshly built wheel in a clean venv and import the t
 		assert m.PasswordUtils and m.JWTUtils and m.EmailUtils and m.UploadUtils, 'utils missing'; \
 		assert m.is_valid_cpf and m.is_valid_cnpj and m.is_valid_phone_br, 'BR regex helpers missing'; \
 		print('Smoke OK · version =', m.__version__)"
+	/tmp/$(PACKAGE)-smoke/bin/python -c "from $(PACKAGE).ssr import Page, html_response, make_htmx_router; \
+		print('SSR extra OK ·', Page.__name__, html_response.__name__, make_htmx_router.__name__)"
 	@rm -rf /tmp/$(PACKAGE)-smoke
 
 version: ## Print the version recorded in pyproject.toml and __init__.py

{tempest_fastapi_sdk-0.87.1 → tempest_fastapi_sdk-0.89.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.87.1
+Version: 0.89.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -59,6 +59,7 @@ Requires-Dist: pywebpush>=2.0.0; extra == 'all'
 Requires-Dist: redis>=5.0.0; extra == 'all'
 Requires-Dist: taskiq-aio-pika>=0.4.0; extra == 'all'
 Requires-Dist: taskiq>=0.11.0; extra == 'all'
+Requires-Dist: tempestweb>=0.9.0; extra == 'all'
 Provides-Extra: auth
 Requires-Dist: bcrypt>=5.0.0; extra == 'auth'
 Requires-Dist: pyjwt>=2.12.1; extra == 'auth'
@@ -91,6 +92,8 @@ Provides-Extra: queue
 Requires-Dist: faststream[rabbit]>=0.7.1; extra == 'queue'
 Provides-Extra: sqlite
 Requires-Dist: aiosqlite>=0.20.0; extra == 'sqlite'
+Provides-Extra: ssr
+Requires-Dist: tempestweb>=0.9.0; extra == 'ssr'
 Provides-Extra: tasks
 Requires-Dist: taskiq-aio-pika>=0.4.0; extra == 'tasks'
 Requires-Dist: taskiq>=0.11.0; extra == 'tasks'
@@ -116,7 +119,7 @@ Description-Content-Type: text/markdown
 
 > 💡 `uv run mkdocs serve` (ou `make docs-serve`) é só para preview local — em produção use as URLs do GitHub Pages acima. / For local preview only — in production use the GitHub Pages URLs above.
 
-Shared FastAPI/SQLAlchemy/Pydantic building blocks used across Tempest projects: base schemas, ORM model, async repository, pagination, settings, exceptions, Alembic helper, FastStream/TaskIQ broker managers, Redis cache, Server-Sent Events, Web Push, a Django-style **admin site** (`AdminSite` + `AdminModel`), and the utility classes (`PasswordUtils`, `JWTUtils`, `EmailUtils`, `UploadUtils`, `DownloadUtils`, `MetricsUtils`, `LogUtils`).
+Shared FastAPI/SQLAlchemy/Pydantic building blocks used across Tempest projects: base schemas, ORM model, async repository, pagination, settings, exceptions, Alembic helper, FastStream/TaskIQ broker managers, Redis cache, Server-Sent Events, Web Push, a Django-style **admin site** (`AdminSite` + `AdminModel`), **typed SSR pages** (`Page` + `html_response`, HTMX-ready), and the utility classes (`PasswordUtils`, `JWTUtils`, `EmailUtils`, `UploadUtils`, `DownloadUtils`, `MetricsUtils`, `LogUtils`).
 
 The goal is to start every new backend with the same opinionated foundation already in place — no copy-pasting `BaseModel`, no rewriting the same CRUD repository, no re-inventing the exception envelope.
 
@@ -223,6 +226,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
 | `[vision]` | `ort-vision-sdk` | `Detector` / `Classifier` / `Segmenter` (ONNX) + prediction schemas |
+| `[ssr]` | `tempestweb` | `Page`, `html_response`, `make_htmx_router` — typed Python pages rendered to HTML |
 | `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
@@ -264,10 +268,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
 | `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas` |
+| `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX locally, no CDN) |
 | `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
-Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks` and `tempest_fastapi_sdk.vision` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
+Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks`, `tempest_fastapi_sdk.vision` and `tempest_fastapi_sdk.ssr` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
 
 ---
 

{tempest_fastapi_sdk-0.87.1 → tempest_fastapi_sdk-0.89.0}/README.md

@@ -10,7 +10,7 @@
 
 > 💡 `uv run mkdocs serve` (ou `make docs-serve`) é só para preview local — em produção use as URLs do GitHub Pages acima. / For local preview only — in production use the GitHub Pages URLs above.
 
-Shared FastAPI/SQLAlchemy/Pydantic building blocks used across Tempest projects: base schemas, ORM model, async repository, pagination, settings, exceptions, Alembic helper, FastStream/TaskIQ broker managers, Redis cache, Server-Sent Events, Web Push, a Django-style **admin site** (`AdminSite` + `AdminModel`), and the utility classes (`PasswordUtils`, `JWTUtils`, `EmailUtils`, `UploadUtils`, `DownloadUtils`, `MetricsUtils`, `LogUtils`).
+Shared FastAPI/SQLAlchemy/Pydantic building blocks used across Tempest projects: base schemas, ORM model, async repository, pagination, settings, exceptions, Alembic helper, FastStream/TaskIQ broker managers, Redis cache, Server-Sent Events, Web Push, a Django-style **admin site** (`AdminSite` + `AdminModel`), **typed SSR pages** (`Page` + `html_response`, HTMX-ready), and the utility classes (`PasswordUtils`, `JWTUtils`, `EmailUtils`, `UploadUtils`, `DownloadUtils`, `MetricsUtils`, `LogUtils`).
 
 The goal is to start every new backend with the same opinionated foundation already in place — no copy-pasting `BaseModel`, no rewriting the same CRUD repository, no re-inventing the exception envelope.
 
@@ -117,6 +117,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
 | `[vision]` | `ort-vision-sdk` | `Detector` / `Classifier` / `Segmenter` (ONNX) + prediction schemas |
+| `[ssr]` | `tempestweb` | `Page`, `html_response`, `make_htmx_router` — typed Python pages rendered to HTML |
 | `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
@@ -158,10 +159,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
 | `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas` |
+| `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX locally, no CDN) |
 | `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `version` / `--version` |
 
-Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks` and `tempest_fastapi_sdk.vision` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
+Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks`, `tempest_fastapi_sdk.vision` and `tempest_fastapi_sdk.ssr` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
 
 ---
 

{tempest_fastapi_sdk-0.87.1 → tempest_fastapi_sdk-0.89.0}/docs/recipes/storage.en.md

@@ -180,6 +180,28 @@ async def get_download_url(key: str) -> dict[str, str]:
     return {"url": url}
 ```
 
+### Separate public endpoint for presigned URLs *(v0.88.0+)*
+
+Common production shape: the backend talks to MinIO over a **fast private network** (`servus-storage:9000`, no TLS), but the **browser** can't reach that host — it needs a **public HTTPS** host. If you sign the presigned URL with the internal endpoint, the link carries `servus-storage:9000` and the browser can't open it.
+
+Fix: `MINIO_PUBLIC_ENDPOINT`. Presigned URLs (`presigned_get_url` / `presigned_put_url`) are then **signed against the public host**, while **every server→MinIO operation keeps using the internal endpoint**.
+
+```bash
+# .env
+MINIO_ENDPOINT=servus-storage:9000            # internal Docker network (ops)
+MINIO_SECURE=false
+MINIO_PUBLIC_ENDPOINT=https://storage.example.com   # browser (presigned)
+# MINIO_PUBLIC_SECURE=true                     # optional; https:// already implies it
+```
+
+!!! info "Why two clients, not a host replace"
+    A presigned URL is SigV4-signed including the `Host` header. Rewriting the host **after** signing invalidates the signature. So the SDK keeps a second `minio.Minio` (same credentials) whose only job is to **sign** against the public host — the internal `AsyncMinIOClient.client` still does put/get/stat/ensure_bucket over the private network.
+
+!!! tip "Without `MINIO_PUBLIC_ENDPOINT`"
+    Unchanged behaviour: presigned URLs are signed with `MINIO_ENDPOINT` (single-endpoint mode). The split is fully opt-in.
+
+The public host's proxy must route to the **MinIO S3 API (port 9000)** over TLS and forward the correct `Host` (the signature validates it).
+
 ### List objects by prefix
 
 ```python

{tempest_fastapi_sdk-0.87.1 → tempest_fastapi_sdk-0.89.0}/docs/recipes/storage.md

@@ -180,6 +180,28 @@ async def get_download_url(key: str) -> dict[str, str]:
     return {"url": url}
 ```
 
+### Endpoint público separado para presigned URLs *(v0.88.0+)*
+
+Cenário comum em produção: o backend fala com o MinIO por uma **rede privada rápida** (`servus-storage:9000`, sem TLS), mas o **browser** não alcança esse host — precisa de um host **público com HTTPS**. Se você assinar a presigned URL com o endpoint interno, o link vem com `servus-storage:9000` e o navegador não abre.
+
+Solução: `MINIO_PUBLIC_ENDPOINT`. As presigned URLs (`presigned_get_url` / `presigned_put_url`) passam a ser **assinadas contra o host público**, enquanto **todas as operações servidor→MinIO continuam no endpoint interno**.
+
+```bash
+# .env
+MINIO_ENDPOINT=servus-storage:9000            # rede interna Docker (ops)
+MINIO_SECURE=false
+MINIO_PUBLIC_ENDPOINT=https://storage.example.com   # browser (presigned)
+# MINIO_PUBLIC_SECURE=true                     # opcional; https:// já implica true
+```
+
+!!! info "Por que dois clients e não um replace de host"
+    A presigned URL é assinada (SigV4) incluindo o header `Host`. Trocar o host **depois** de assinar invalida a assinatura. Por isso o SDK mantém um segundo `minio.Minio` (mesmas credenciais) só para **assinar** contra o host público — o `AsyncMinIOClient.client` interno segue fazendo put/get/stat/ensure_bucket pela rede privada.
+
+!!! tip "Sem `MINIO_PUBLIC_ENDPOINT`"
+    Comportamento inalterado: presigned URLs são assinadas com `MINIO_ENDPOINT` (modo endpoint único). O split é 100% opt-in.
+
+O proxy do host público precisa rotear para a **API S3 do MinIO (porta 9000)** com TLS e repassar o `Host` correto (a assinatura valida o host).
+
 ### Listar objetos por prefixo
 
 ```python

tempest_fastapi_sdk-0.89.0/docs/ssr.en.md

@@ -0,0 +1,286 @@
+# SSR: typed Python pages rendered to HTML
+
+Your FastAPI service, full-stack, **typed**, with no template language. 🚀
+
+The SDK's SSR (Server-Side Rendering) layer lets you describe pages as
+**typed Python components** and return them from a route already rendered
+to HTML. No Jinja, no loose strings: the same type checker that covers
+your schemas and services now covers your UI too.
+
+!!! info "What you'll need"
+    The SSR layer lives in the optional `[ssr]` extra, which pulls in the
+    [`tempestweb`](https://pypi.org/project/tempestweb/) renderer (and,
+    transitively, `tempest-core` with the typed widgets).
+
+    ```bash
+    pip install "tempest-fastapi-sdk[ssr]"
+    ```
+
+## Why this exists
+
+In a traditional API you return JSON and a separate front-end draws the
+screen. When all you need are server-driven pages (an internal panel, an
+onboarding flow, a landing page), spinning up a whole SPA is dead weight.
+
+The classic alternative — a templating engine — drops you out of the typed
+world: the template is a string, the editor can't help you, and a field
+renamed in the schema only breaks in production.
+
+The SSR layer solves this by keeping **everything in typed Python**:
+
+- You declare the page as a class (`Page`) with typed fields.
+- You build the body with widgets (`Column`, `Row`, `Text`, `Button`, ...).
+- You return `html_response(...)` from the route — and get an `HTMLResponse`.
+
+## Minimal complete example
+
+This is a complete, runnable program. Save it as `main.py`, install the
+extra, and run it with `uvicorn main:app`.
+
+```python
+from tempest_core import Column, Text, Widget
+from fastapi import FastAPI
+
+from tempest_fastapi_sdk.ssr import Page, html_response
+
+app: FastAPI = FastAPI()
+
+
+class HomePage(Page):
+    """The home page, with a single typed field."""
+
+    user: str
+
+    def body(self) -> Widget:
+        """The page's main content."""
+        return Column(
+            tag="main",
+            children=[
+                Text(content=f"Hello, {self.user}!", tag="h1"),
+                Text(content="Welcome to your typed app.", tag="p"),
+            ],
+        )
+
+
+@app.get("/")
+def home() -> object:
+    """Render HomePage as a full HTML document."""
+    return html_response(HomePage(title="Home", user="Ana"), title="Home")
+```
+
+Open `http://127.0.0.1:8000/` and you get a full HTML5 document with
+`<!doctype html>`, `<title>Home</title>`, and a `<main>` body — all
+generated from the classes above.
+
+## Piece by piece
+
+### The `Page` class
+
+```python
+class HomePage(Page):
+    user: str
+
+    def body(self) -> Widget:
+        return Column(tag="main", children=[Text(content=f"Hello, {self.user}!")])
+```
+
+`Page` is a **`tempest_core` component** (a Pydantic model). That means the
+page's data are **typed fields** — here, `user: str`. The inherited
+`title: str` field feeds the document `<title>`.
+
+You implement **`body()`**, which returns the widget tree for the main
+content. It is the only required method.
+
+!!! tip "Semantic tags"
+    Every widget accepts `tag=` and `attrs=`. Use `tag="main"`,
+    `tag="h1"`, `tag="nav"` to emit semantic HTML instead of the neutral
+    defaults (`<div>` / `<span>`).
+
+### The `html_response` function
+
+```python
+return html_response(HomePage(title="Home", user="Ana"), title="Home")
+```
+
+`html_response` renders the tree and returns a FastAPI `HTMLResponse`.
+Its signature:
+
+```python
+def html_response(
+    widget: Widget,
+    *,
+    title: str | None = None,
+    status_code: int = 200,
+    htmx: bool = False,
+    document: bool = True,
+    lang: str = "pt-BR",
+) -> HTMLResponse: ...
+```
+
+- **`document=True`** (default) → full HTML5 document. Requires `title`
+  (raises `ValueError` if `title is None`).
+- **`document=False`** → bare HTML fragment (no `<!doctype>`), ideal for
+  partial swaps with HTMX.
+- **`status_code`** → passed through to the `HTMLResponse`.
+- **`htmx=True`** → inject the HTMX `<script>` **served locally** (never
+  from a CDN — see below).
+
+!!! warning "`title` is required for documents"
+    Calling `html_response(page)` with `document=True` (the default) and
+    no `title` raises `ValueError`. For fragments (`document=False`),
+    `title` is ignored.
+
+## Shared layout with `shell()`
+
+Every page usually shares the same header, navigation, and footer. Instead
+of repeating it, override **`shell()`** on a base page and inherit through
+normal Python inheritance.
+
+```python
+from tempest_core import Column, Row, Text, Widget
+
+from tempest_fastapi_sdk.ssr import Page, html_response
+
+
+class BasePage(Page):
+    """Shared layout: navigation bar + main area."""
+
+    def shell(self, body: Widget) -> Widget:
+        return Column(
+            tag="body",
+            children=[
+                Row(tag="nav", children=[Text(content="MyApp")]),
+                Column(tag="main", children=[body]),
+            ],
+        )
+
+
+class DashboardPage(BasePage):
+    """Inherits the navigation, defines only its own body."""
+
+    def body(self) -> Widget:
+        return Text(content="Dashboard", tag="h2")
+
+
+class ReportsPage(BasePage):
+    """Same navigation, different body."""
+
+    def body(self) -> Widget:
+        return Text(content="Reports", tag="h2")
+```
+
+`render()` (the component hook) already composes `shell(body())` for you —
+**do not override `render()`**; override `body()` and, optionally,
+`shell()`.
+
+!!! note "How composition works"
+    `Page.render()` returns `self.shell(self.body())`. The renderer expands
+    components recursively, so a page is just another widget in the tree.
+
+## HTMX served locally (no CDN)
+
+For server-driven interactivity without writing JavaScript, the SDK bundles
+HTMX 2.x **inside the package** and serves it from your own app — CSP-
+friendly and offline-capable. No CDN.
+
+Mount the router and flip `htmx=True`:
+
+```python
+from tempest_fastapi_sdk.ssr import make_htmx_router
+
+app.include_router(make_htmx_router())  # serves GET /_ssr/htmx.js
+```
+
+When you call `html_response(page, title=..., htmx=True)`, the generated
+document points at `/_ssr/htmx.js` (the same path served by the router),
+never at `https://unpkg.com/...`.
+
+### Recipe: server-driven counter with HTMX
+
+A button that increments a counter on the server and swaps just a fragment —
+no JavaScript. Complete program:
+
+```python
+from tempest_core import Button, Column, Text, Widget
+from fastapi import FastAPI
+
+from tempest_fastapi_sdk.ssr import Page, html_response, make_htmx_router
+
+app: FastAPI = FastAPI()
+app.include_router(make_htmx_router())
+
+_count: int = 0
+
+
+class CounterFragment(Page):
+    """The fragment swapped on each click."""
+
+    value: int
+
+    def body(self) -> Widget:
+        return Column(
+            attrs={"id": "counter"},
+            children=[
+                Text(content=f"Total: {self.value}", tag="p"),
+                Button(
+                    label="Increment",
+                    attrs={
+                        "hx-post": "/increment",
+                        "hx-target": "#counter",
+                        "hx-swap": "outerHTML",
+                    },
+                ),
+            ],
+        )
+
+
+class CounterPage(Page):
+    """The full page that loads HTMX and shows the counter."""
+
+    value: int
+
+    def body(self) -> Widget:
+        return CounterFragment(title="", value=self.value)
+
+
+@app.get("/")
+def index() -> object:
+    """Full document, with the local HTMX loaded (htmx=True)."""
+    return html_response(
+        CounterPage(title="Counter", value=_count), title="Counter", htmx=True
+    )
+
+
+@app.post("/increment")
+def increment() -> object:
+    """Increment and return only the fragment (document=False)."""
+    global _count
+    _count += 1
+    return html_response(CounterFragment(title="", value=_count), document=False)
+```
+
+How it works:
+
+1. `GET /` returns the **full document** (`document=True`, `htmx=True`), so
+   the local HTMX is loaded.
+2. The button has `hx-post="/increment"` and `hx-swap="outerHTML"`.
+3. `POST /increment` returns only the **fragment** (`document=False`), and
+   HTMX swaps the `<div id="counter">` in place.
+
+!!! check "Safe by default"
+    All text is escaped on render. A `Text(content="<script>")` becomes
+    `&lt;script&gt;` in the final HTML — no accidental injection.
+
+## Recap
+
+- **`Page`** — typed component; declare fields, implement `body()`,
+  optionally override `shell()` for a shared layout. Do not override
+  `render()`.
+- **`html_response(widget, *, title, status_code, htmx, document, lang)`** —
+  renders and returns an `HTMLResponse`. `document=True` requires `title`;
+  `document=False` returns a fragment for HTMX swaps.
+- **`make_htmx_router(prefix="/_ssr")`** — serves the bundled HTMX locally
+  at `GET /_ssr/htmx.js`; combine with `htmx=True`.
+- Everything lives in the `[ssr]` extra
+  (`pip install "tempest-fastapi-sdk[ssr]"`), loaded on demand —
+  `import tempest_fastapi_sdk` never requires the extra.