initial release v0.1.0: headless browser rendering API

VeilRender is a self-hostable headless browser rendering API built with
zerodep modules and CloakBrowser (stealth Chromium). Accepts a URL,
renders it with the browser, and returns content as HTML, Markdown, or
readability-extracted text.

Features:
- POST /render — URL to rendered HTML/Markdown/readability
- POST /screenshot — URL to PNG screenshot
- GET /health — liveness check
- CDP WebSocket proxy on /cdp for direct browser control
- Token-based authentication via Bearer header or query param
- Per-request browser context isolation with concurrency control
- CloakBrowser with 58 source-level anti-fingerprint patches
- 13 vendored zerodep modules, only external dep is cloakbrowser
- Docker image based on python:3.12-slim
- GitHub CI: pre-commit (ruff + ty), multi-arch Docker (amd64/arm64)
- Auto-deploy to HF Spaces and Docker Hub/GHCR
- Bilingual README (en/zh)

.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+  pull_request:
+    branches: [master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run pre-commit checks
+        uses: pre-commit/action@v3.0.1
+
+  docker:
+    needs: lint
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+            docker.io/${{ github.repository }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy-hf:
+    needs: lint
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Prepare HF Space files
+        run: |
+          cat > README.md <<'FRONTMATTER'
+          ---
+          title: VeilRender
+          emoji: 👻
+          colorFrom: gray
+          colorTo: purple
+          sdk: docker
+          app_port: 7860
+          pinned: false
+          ---
+
+          # VeilRender
+
+          Headless browser rendering API. See [GitHub repo](https://github.com/${{ github.repository }}) for full documentation.
+          FRONTMATTER
+          sed -i 's/^          //' README.md
+          rm -rf .github .pre-commit-config.yaml CLAUDE.md README_en.md README_zh.md Makefile
+
+      - name: Push to HF Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_SPACE: ${{ vars.HF_SPACE }}  # e.g. oaklight/veilrender
+        run: |
+          if [ -z "$HF_SPACE" ]; then
+            echo "::warning::HF_SPACE variable not set, skipping HF deploy"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "deploy from GitHub $(git rev-parse --short HEAD@{1})" --allow-empty
+          git push --force "https://oauth2:${HF_TOKEN}@huggingface.co/spaces/${HF_SPACE}" HEAD:main

.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Docker
+.docker/
+
+# Playwright
+.playwright-mcp/
+
+# Claude
+.claude/
+.ruff_cache/

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+        exclude: ^src/veilrender/_vendor/
+      - id: ruff-format
+        exclude: ^src/veilrender/_vendor/
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        description: Type check src/ with ty.
+        entry: ty check src/
+        language: system
+        pass_filenames: false
+        require_serial: true
+        types: [python]

CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-12
+
+### Added
+
+- Core rendering API with three endpoints:
+  - `POST /render` — URL → rendered HTML / Markdown / readability-extracted text
+  - `POST /screenshot` — URL → PNG screenshot
+  - `GET /health` — liveness check
+- CDP WebSocket proxy at `/cdp` for direct browser control ([#3])
+- Token-based authentication via `Authorization: Bearer` header or `?token=` query param
+- Per-request browser context isolation with configurable concurrency (`VEILRENDER_MAX_CONCURRENT`)
+- [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) integration — stealth Chromium with 58 source-level anti-fingerprint patches ([#14], [#15])
+- 13 vendored [zerodep](https://github.com/Oaklight/zerodep) modules — only external dependency is `cloakbrowser`
+- Docker image based on `python:3.12-slim` with multi-arch support (amd64/arm64)
+- GitHub CI pipeline: pre-commit (ruff + ty), Docker build to GHCR + Docker Hub, auto-deploy to HF Spaces
+- PyPI publishing on tag push
+- `Makefile` with `deploy-dev` (VPS) and `deploy-hf` (HF Spaces) targets
+- Bilingual README (en/zh)
+
+### Fixed
+
+- CDP proxy: preserve FIN bit during WebSocket frame forwarding ([#4], [#12])
+- HTTP multiplexer: pipe remaining POST body data instead of `feed_eof()` ([#5], [#9])
+- CDP proxy: add 16 MB max frame size limit to prevent OOM ([#6], [#10])
+- CDP proxy: cancel both directions when one side closes ([#7], [#11])
+- CDP proxy: use random WebSocket key per connection and forward `Sec-WebSocket-Protocol` ([#8], [#13])
+- Docker: use `CLOAKBROWSER_CACHE_DIR` so build-time binary download is available at runtime ([#16], [#17])
+- Launch Chromium directly via `subprocess.Popen` + `connect_over_cdp()` instead of Playwright's `launch()`, which overrides `--remote-debugging-port`
+
+[Unreleased]: https://github.com/Oaklight/veilrender/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Oaklight/veilrender/releases/tag/v0.1.0
+
+[#1]: https://github.com/Oaklight/veilrender/issues/1
+[#2]: https://github.com/Oaklight/veilrender/issues/2
+[#3]: https://github.com/Oaklight/veilrender/issues/3
+[#4]: https://github.com/Oaklight/veilrender/issues/4
+[#5]: https://github.com/Oaklight/veilrender/issues/5
+[#6]: https://github.com/Oaklight/veilrender/issues/6
+[#7]: https://github.com/Oaklight/veilrender/issues/7
+[#8]: https://github.com/Oaklight/veilrender/issues/8
+[#9]: https://github.com/Oaklight/veilrender/pull/9
+[#10]: https://github.com/Oaklight/veilrender/pull/10
+[#11]: https://github.com/Oaklight/veilrender/pull/11
+[#12]: https://github.com/Oaklight/veilrender/pull/12
+[#13]: https://github.com/Oaklight/veilrender/pull/13
+[#14]: https://github.com/Oaklight/veilrender/issues/14
+[#15]: https://github.com/Oaklight/veilrender/pull/15
+[#16]: https://github.com/Oaklight/veilrender/issues/16
+[#17]: https://github.com/Oaklight/veilrender/pull/17

CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md — VeilRender
+
+## What this project is
+
+Headless browser rendering API. Accepts a URL, renders it with Playwright +
+Chromium, returns HTML/Markdown/readability content. Primary deployment target:
+HF Spaces (free tier). Also runs as standalone Docker container.
+
+## Architecture
+
+- **Zero external deps** except `playwright` — uses vendored `zerodep` modules
+  in `src/veilrender/_vendor/` for HTTP server, HTML parsing, readability, etc.
+- **`httpserver`** (zerodep) as the async HTTP framework — not FastAPI
+- **Playwright** for browser control — shared browser instance, per-request
+  `BrowserContext` isolation
+- **Stateless** — no session management, no database
+
+## Repository layout
+
+```
+src/veilrender/
+├── app.py          # HTTP server setup, route registration, main()
+├── config.py       # Settings from env vars (VEILRENDER_ prefix)
+├── auth.py         # Token verification
+├── browser.py      # Playwright browser lifecycle
+├── models.py       # Request/response dataclasses
+├── routes/         # Route handlers (render, screenshot, health)
+└── _vendor/        # zerodep modules — DO NOT EDIT manually
+```
+
+## Commands
+
+```bash
+make dev          # Run dev server on :7860
+make build        # Docker build
+make run          # Docker run
+make lint         # ruff check --fix && ruff format
+make typecheck    # ty check
+make vendor       # Re-vendor zerodep modules
+```
+
+## Files to never edit
+
+- `src/veilrender/_vendor/**` — vendored zerodep modules, update via
+  `zerodep update` from ~/projects/zerodep
+
+## Definition of done
+
+1. `ruff check --fix && ruff format` on changed Python files
+2. Server starts and `/health` returns 200
+3. `/render` returns valid content for a test URL

Dockerfile

@@ -0,0 +1,43 @@
+FROM python:3.12-slim
+
+# System libraries required by headless Chromium
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libatk1.0-0 \
+        libatk-bridge2.0-0 \
+        libcups2 \
+        libxcb1 \
+        libxkbcommon0 \
+        libatspi2.0-0 \
+        libx11-6 \
+        libxcomposite1 \
+        libxdamage1 \
+        libxext6 \
+        libxfixes3 \
+        libxrandr2 \
+        libgbm1 \
+        libcairo2 \
+        libpango-1.0-0 \
+        libnss3 \
+        libnspr4 \
+        libasound2t64 \
+        libdbus-1-3 \
+        fonts-liberation \
+    && rm -rf /var/lib/apt/lists/*
+
+# HF Spaces runs as non-root user with UID 1000
+RUN useradd -m -u 1000 user || true
+
+WORKDIR /app
+
+# Install Python package (includes cloakbrowser + playwright)
+COPY pyproject.toml .
+COPY src/ src/
+RUN pip install --no-cache-dir .
+
+# Pre-download CloakBrowser Chromium binary so the image is self-contained
+RUN python -c "from cloakbrowser import ensure_binary; ensure_binary()"
+
+USER 1000
+EXPOSE 7860
+
+CMD ["python", "-m", "veilrender"]

Makefile

@@ -0,0 +1,113 @@
+.PHONY: dev build run lint typecheck vendor clean deploy-dev deploy-hf help
+
+REGISTRY_MIRROR ?= docker.io
+DOCKER_IMAGE := oaklight/veilrender
+VERSION := $(shell grep -oE '__version__[[:space:]]*=[[:space:]]*"[^"]+"' src/veilrender/__init__.py | grep -oE '"[^"]+"' | tr -d '"' || echo "0.1.0")
+
+dev:
+	python -m veilrender
+
+build:
+	docker build -t $(DOCKER_IMAGE):latest .
+
+run:
+	docker run --rm -p 7860:7860 -e VEILRENDER_API_TOKEN=dev-token $(DOCKER_IMAGE):latest
+
+lint:
+	ruff check --fix src/veilrender/ --exclude src/veilrender/_vendor/
+	ruff format src/veilrender/ --exclude src/veilrender/_vendor/
+
+typecheck:
+	ty check src/veilrender/
+
+vendor:
+	cd ~/projects/zerodep && python zerodep.py add httpserver readability soup markdown cache config useragent retry structlog -d $(CURDIR)/src/veilrender/_vendor/ -y -f
+
+clean:
+	rm -rf build/ dist/ *.egg-info/ src/*.egg-info/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+# ──────────────────────────────────────────────
+# Dev Deployment
+# ──────────────────────────────────────────────
+
+SSH_TARGET ?=
+DEVTEST_STACK ?= /dockervol/dockge/stacks/veilrender
+
+# Build dev-test image, push to remote VPS, restart container.
+# Usage: make deploy-dev SSH_TARGET=cloud.usa2
+deploy-dev:
+ifndef SSH_TARGET
+	$(error SSH_TARGET is required. Usage: make deploy-dev SSH_TARGET=cloud.usa2)
+endif
+	@set -e; \
+	COMMIT=$$(git rev-parse --short HEAD); \
+	DEV_VER="$(VERSION).dev0+g$$COMMIT"; \
+	echo "==> Building Docker image ($$DEV_VER)..."; \
+	docker build -t $(DOCKER_IMAGE):dev-test -q .; \
+	echo "==> Deploying to $(SSH_TARGET) via zstd..."; \
+	docker save $(DOCKER_IMAGE):dev-test | zstd -3 | ssh $(SSH_TARGET) \
+		'zstd -d | docker load && \
+		 cd $(DEVTEST_STACK) && \
+		 sed -i "s|image:.*|image: $(DOCKER_IMAGE):dev-test|" compose.yaml && \
+		 docker compose up -d --force-recreate && \
+		 sleep 5 && \
+		 echo "=== Health check ===" && \
+		 curl -sS -o /dev/null -w "%{http_code} /health\n" http://127.0.0.1:7860/ || true'; \
+	echo "==> VPS dev-test deployed successfully ($$DEV_VER)."
+
+# Deploy to Hugging Face Spaces by pushing current code.
+# Usage: make deploy-hf HF_SPACE=oaklight/veilrender
+HF_SPACE ?=
+deploy-hf:
+ifndef HF_SPACE
+	$(error HF_SPACE is required. Usage: make deploy-hf HF_SPACE=oaklight/veilrender)
+endif
+	@set -e; \
+	COMMIT=$$(git rev-parse --short HEAD); \
+	echo "==> Deploying to HF Space $(HF_SPACE) ($$COMMIT)..."; \
+	TMP=$$(mktemp -d); \
+	git clone --depth 1 . "$$TMP/repo"; \
+	cd "$$TMP/repo"; \
+	printf '%s\n' \
+		'---' \
+		'title: VeilRender' \
+		'emoji: 👻' \
+		'colorFrom: gray' \
+		'colorTo: purple' \
+		'sdk: docker' \
+		'app_port: 7860' \
+		'pinned: false' \
+		'---' \
+		'' \
+		'# VeilRender' \
+		'' \
+		"Headless browser rendering API. See [GitHub repo]($$(git remote get-url origin | sed 's/\.git$$//; s|git@github.com:|https://github.com/|')) for full documentation." \
+		> README.md; \
+	rm -rf .github .pre-commit-config.yaml CLAUDE.md README_en.md README_zh.md Makefile; \
+	git add -A; \
+	git commit -m "deploy $$COMMIT" --allow-empty; \
+	git push --force "https://oauth2:$${HF_TOKEN}@huggingface.co/spaces/$(HF_SPACE)" HEAD:main; \
+	rm -rf "$$TMP"; \
+	echo "==> HF Space deployed successfully ($$COMMIT)."
+
+help:
+	@echo "Available targets:"
+	@echo "  dev          - Run development server on :7860"
+	@echo "  build        - Build Docker image"
+	@echo "  run          - Run Docker container"
+	@echo "  lint         - Run ruff check and format"
+	@echo "  typecheck    - Run ty check"
+	@echo "  vendor       - Re-vendor zerodep modules"
+	@echo "  clean        - Remove build artifacts"
+	@echo "  deploy-dev   - Build dev image and deploy to remote VPS"
+	@echo "  deploy-hf    - Deploy to Hugging Face Spaces"
+	@echo ""
+	@echo "Variables:"
+	@echo "  SSH_TARGET=<host>     - SSH target for deploy-dev (required)"
+	@echo "  HF_SPACE=<user/repo> - HF Space for deploy-hf (required)"
+	@echo "  HF_TOKEN             - HF token (env var, required for deploy-hf)"
+	@echo ""
+	@echo "Examples:"
+	@echo "  make deploy-dev SSH_TARGET=cloud.usa2"
+	@echo "  make deploy-hf HF_SPACE=oaklight/veilrender"

README.md

@@ -1 +0,0 @@
-# veilrender

README.md

@@ -0,0 +1 @@
+README_en.md

README_en.md

@@ -0,0 +1,88 @@
+# VeilRender
+
+[中文](README_zh.md) | **English**
+
+Headless browser rendering API — self-hostable on HF Spaces, Docker, or bare metal.
+
+VeilRender accepts a URL and returns the fully rendered page content (HTML, Markdown, readability-extracted article) using a headless Chromium browser. Designed as a fallback for fetch tools that fail on JavaScript-rendered pages.
+
+## Quick Start
+
+### Docker
+
+```bash
+docker run -p 7860:7860 -e VEILRENDER_API_TOKEN=your-secret ghcr.io/oaklight/veilrender
+```
+
+### Local Development
+
+```bash
+pip install -e ".[dev]"
+playwright install chromium
+python -m veilrender
+```
+
+## API
+
+### GET /health
+
+Returns `{"status": "ok"}` if the service is running.
+
+### POST /render
+
+Render a URL and return the page content.
+
+```bash
+curl -X POST http://localhost:7860/render \
+  -H "Authorization: Bearer your-secret" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}'
+```
+
+Response:
+
+```json
+{
+  "content": {
+    "html": "...",
+    "markdown": "...",
+    "readability": "..."
+  },
+  "metadata": {
+    "title": "Example Domain",
+    "url": "https://example.com",
+    "status_code": 200
+  },
+  "links": [{"url": "https://www.iana.org/domains/example", "text": "More information..."}]
+}
+```
+
+### POST /screenshot
+
+Capture a screenshot of a URL.
+
+```bash
+curl -X POST http://localhost:7860/screenshot \
+  -H "Authorization: Bearer your-secret" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}' \
+  -o screenshot.png
+```
+
+## Configuration
+
+All settings are configured via environment variables with the `VEILRENDER_` prefix:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VEILRENDER_API_TOKEN` | *(none)* | API token for authentication. If unset, auth is disabled. |
+| `VEILRENDER_PORT` | `7860` | Server port |
+| `VEILRENDER_HOST` | `0.0.0.0` | Server bind address |
+| `VEILRENDER_TIMEOUT` | `30000` | Browser navigation timeout (ms) |
+| `VEILRENDER_VIEWPORT_WIDTH` | `1280` | Browser viewport width |
+| `VEILRENDER_VIEWPORT_HEIGHT` | `720` | Browser viewport height |
+| `VEILRENDER_MAX_CONCURRENT` | `3` | Max concurrent browser contexts |
+
+## License
+
+MIT

README_zh.md

@@ -0,0 +1,88 @@
+# VeilRender
+
+**中文** | [English](README_en.md)
+
+无头浏览器渲染 API——可自托管于 HF Spaces、Docker 或物理机。
+
+VeilRender 接收一个 URL，使用无头 Chromium 浏览器渲染页面，并返回完整内容（HTML、Markdown、readability 提取的文章）。专为 JavaScript 渲染页面的 fetch 降级方案设计。
+
+## 快速开始
+
+### Docker
+
+```bash
+docker run -p 7860:7860 -e VEILRENDER_API_TOKEN=your-secret ghcr.io/oaklight/veilrender
+```
+
+### 本地开发
+
+```bash
+pip install -e ".[dev]"
+playwright install chromium
+python -m veilrender
+```
+
+## API
+
+### GET /health
+
+服务运行中返回 `{"status": "ok"}`。
+
+### POST /render
+
+渲染指定 URL 并返回页面内容。
+
+```bash
+curl -X POST http://localhost:7860/render \
+  -H "Authorization: Bearer your-secret" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}'
+```
+
+响应：
+
+```json
+{
+  "content": {
+    "html": "...",
+    "markdown": "...",
+    "readability": "..."
+  },
+  "metadata": {
+    "title": "Example Domain",
+    "url": "https://example.com",
+    "status_code": 200
+  },
+  "links": [{"url": "https://www.iana.org/domains/example", "text": "More information..."}]
+}
+```
+
+### POST /screenshot
+
+截取指定 URL 的页面截图。
+
+```bash
+curl -X POST http://localhost:7860/screenshot \
+  -H "Authorization: Bearer your-secret" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com"}' \
+  -o screenshot.png
+```
+
+## 配置
+
+所有设置通过 `VEILRENDER_` 前缀的环境变量配置：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `VEILRENDER_API_TOKEN` | *(无)* | API 认证令牌。未设置时认证关闭。 |
+| `VEILRENDER_PORT` | `7860` | 服务端口 |
+| `VEILRENDER_HOST` | `0.0.0.0` | 服务绑定地址 |
+| `VEILRENDER_TIMEOUT` | `30000` | 浏览器导航超时（毫秒） |
+| `VEILRENDER_VIEWPORT_WIDTH` | `1280` | 浏览器视口宽度 |
+| `VEILRENDER_VIEWPORT_HEIGHT` | `720` | 浏览器视口高度 |
+| `VEILRENDER_MAX_CONCURRENT` | `3` | 最大并发浏览器上下文数 |
+
+## 许可证
+
+MIT

pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "veilrender"
+dynamic = ["version"]
+description = "Headless browser rendering API — self-hostable on HF Spaces, Docker, or bare metal"
+authors = [{ name = "Peng Ding" }]
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+dependencies = [
+    "cloakbrowser>=0.3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.11.0",
+    "ty>=0.0.1a0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.scripts]
+veilrender = "veilrender.app:main"
+
+[project.urls]
+Repository = "https://github.com/Oaklight/veilrender"
+Issues = "https://github.com/Oaklight/veilrender/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "veilrender.__version__" }
+
+[tool.setuptools.package-data]
+"veilrender" = ["py.typed"]
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "UP"]
+ignore = ["UP007", "E501"]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ty.src]
+exclude = ["src/veilrender/_vendor/**"]
+
+[tool.ty.rules]
+unresolved-import = "ignore"

src/veilrender/__init__.py

@@ -0,0 +1,3 @@
+"""VeilRender — headless browser rendering API."""
+
+__version__ = "0.1.0"

src/veilrender/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m veilrender``."""
+
+from veilrender.app import main
+
+if __name__ == "__main__":
+    main()

src/veilrender/_vendor/__init__.py

@@ -0,0 +1,2 @@
+# Vendored zerodep modules — do not edit manually.
+# Update via: make vendor

src/veilrender/_vendor/benchmark_compare.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""Three-way readability benchmark: zerodep vs readability-lxml vs Mozilla JS.
+
+Runs each implementation on Mozilla's test fixtures and prints a comparison
+table.  JS timing is measured internally by bench_mozilla.js (no subprocess
+overhead in the numbers).
+
+Usage:
+    python benchmark_compare.py              # all fixtures
+    python benchmark_compare.py 001 bbc-1    # specific fixtures
+    python benchmark_compare.py --rounds 20  # more rounds
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import timeit
+
+# ── Setup paths ──────────────────────────────────────────────────────────────
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+_TEST_PAGES_DIR = os.path.join(_THIS_DIR, "test-pages")
+_BENCH_JS = os.path.join(_THIS_DIR, "bench_mozilla.js")
+
+sys.path.insert(0, _THIS_DIR)
+
+
+# ── Discover fixtures ────────────────────────────────────────────────────────
+
+
+def discover_fixtures() -> list[str]:
+    """Return sorted list of available fixture names."""
+    if not os.path.isdir(_TEST_PAGES_DIR):
+        return []
+    return sorted(
+        d
+        for d in os.listdir(_TEST_PAGES_DIR)
+        if os.path.isdir(os.path.join(_TEST_PAGES_DIR, d))
+        and os.path.isfile(os.path.join(_TEST_PAGES_DIR, d, "source.html"))
+    )
+
+
+def load_source(name: str) -> str:
+    """Load source HTML for a fixture."""
+    path = os.path.join(_TEST_PAGES_DIR, name, "source.html")
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+# ── Python: zerodep readability ──────────────────────────────────────────────
+
+
+def bench_zerodep(html: str, rounds: int) -> dict:
+    """Benchmark our readability.extract() and return timing dict."""
+    from readability import extract
+
+    # Warm-up.
+    result = extract(html)
+
+    times = []
+    for _ in range(rounds):
+        t0 = timeit.default_timer()
+        extract(html)
+        t1 = timeit.default_timer()
+        times.append((t1 - t0) * 1000)  # ms
+
+    return {
+        "times_ms": times,
+        "min_ms": min(times),
+        "mean_ms": sum(times) / len(times),
+        "max_ms": max(times),
+        "title": result.title,
+        "length": result.length,
+    }
+
+
+# ── Python: readability-lxml ────────────────────────────────────────────────
+
+
+def _load_readability_lxml():
+    """Load readability-lxml's Document class, working around name clash."""
+    import importlib
+    import importlib.metadata
+
+    try:
+        importlib.metadata.version("readability-lxml")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+    saved_path = sys.path[:]
+    saved_modules = {
+        k: sys.modules.pop(k)
+        for k in list(sys.modules)
+        if k == "readability" or k.startswith("readability.")
+    }
+    try:
+        sys.path = [
+            p for p in sys.path if os.path.abspath(p) != os.path.abspath(_THIS_DIR)
+        ]
+        mod = importlib.import_module("readability")
+        return mod.Document
+    finally:
+        sys.path = saved_path
+        for k in list(sys.modules):
+            if k == "readability" or k.startswith("readability."):
+                del sys.modules[k]
+        sys.modules.update(saved_modules)
+
+
+_RefDocument = _load_readability_lxml()
+
+
+def bench_readability_lxml(html: str, rounds: int) -> dict | None:
+    """Benchmark readability-lxml and return timing dict, or None."""
+    if _RefDocument is None:
+        return None
+
+    # Warm-up.
+    doc = _RefDocument(html)
+    summary = doc.summary()
+
+    times = []
+    for _ in range(rounds):
+        t0 = timeit.default_timer()
+        doc = _RefDocument(html)
+        doc.summary()
+        t1 = timeit.default_timer()
+        times.append((t1 - t0) * 1000)
+
+    # Extract title from summary HTML (basic).
+    title = doc.short_title() if hasattr(doc, "short_title") else ""
+    length = len(summary) if summary else 0
+
+    return {
+        "times_ms": times,
+        "min_ms": min(times),
+        "mean_ms": sum(times) / len(times),
+        "max_ms": max(times),
+        "title": title,
+        "length": length,
+    }
+
+
+# ── JavaScript: Mozilla Readability.js ───────────────────────────────────────
+
+
+def bench_mozilla_js(fixture_name: str, rounds: int) -> dict | None:
+    """Benchmark Mozilla Readability.js via Node.js subprocess.
+
+    Timing is measured internally by bench_mozilla.js — no subprocess
+    overhead in the reported numbers.
+    """
+    if not shutil.which("node"):
+        return None
+    if not os.path.isfile(_BENCH_JS):
+        return None
+
+    source_path = os.path.join(_TEST_PAGES_DIR, fixture_name, "source.html")
+    try:
+        result = subprocess.run(
+            ["node", _BENCH_JS, source_path, str(rounds)],
+            capture_output=True,
+            text=True,
+            timeout=120,
+            cwd=_THIS_DIR,
+        )
+        if result.returncode != 0:
+            print(f"  [JS error: {result.stderr.strip()[:100]}]", file=sys.stderr)
+            return None
+        return json.loads(result.stdout)
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError):
+        return None
+
+
+# ── Output formatting ────────────────────────────────────────────────────────
+
+# ANSI colors (disabled if not a terminal).
+if sys.stdout.isatty():
+    _BOLD = "\033[1m"
+    _GREEN = "\033[32m"
+    _YELLOW = "\033[33m"
+    _CYAN = "\033[36m"
+    _RESET = "\033[0m"
+    _DIM = "\033[2m"
+else:
+    _BOLD = _GREEN = _YELLOW = _CYAN = _RESET = _DIM = ""
+
+
+def _fmt_ms(ms: float) -> str:
+    """Format milliseconds with appropriate unit."""
+    if ms < 1:
+        return f"{ms * 1000:.0f} µs"
+    if ms < 1000:
+        return f"{ms:.1f} ms"
+    return f"{ms / 1000:.2f} s"
+
+
+def _ratio_str(ms: float, baseline: float) -> str:
+    """Format a ratio relative to baseline."""
+    if baseline <= 0:
+        return ""
+    ratio = ms / baseline
+    if ratio < 1.05:
+        return f"{_GREEN}1.00x{_RESET}"
+    return f"{_YELLOW}{ratio:.2f}x{_RESET}"
+
+
+def print_results(
+    fixture_name: str,
+    html_size: int,
+    zd: dict,
+    lxml: dict | None,
+    js: dict | None,
+) -> None:
+    """Print a single fixture's results as a formatted row."""
+    baseline = zd["mean_ms"]
+
+    cols = [
+        f"  {_BOLD}{fixture_name:<28s}{_RESET}",
+        f"{_DIM}{html_size / 1024:>7.1f} KB{_RESET}",
+        f"{_CYAN}zerodep{_RESET}  {_fmt_ms(zd['mean_ms']):>10s}"
+        f" {_ratio_str(zd['mean_ms'], baseline)}",
+    ]
+
+    if lxml is not None:
+        cols.append(
+            f"{_CYAN}lxml{_RESET}     {_fmt_ms(lxml['mean_ms']):>10s}"
+            f" {_ratio_str(lxml['mean_ms'], baseline)}"
+        )
+    else:
+        cols.append(f"{_DIM}lxml     {'n/a':>10s}{_RESET}")
+
+    if js is not None:
+        cols.append(
+            f"{_CYAN}mozilla{_RESET}  {_fmt_ms(js['mean_ms']):>10s}"
+            f" {_ratio_str(js['mean_ms'], baseline)}"
+        )
+    else:
+        cols.append(f"{_DIM}mozilla  {'n/a':>10s}{_RESET}")
+
+    print("  ".join(cols))
+
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Three-way readability benchmark comparison."
+    )
+    parser.add_argument(
+        "fixtures",
+        nargs="*",
+        help="Fixture names to benchmark (default: all).",
+    )
+    parser.add_argument(
+        "--rounds",
+        type=int,
+        default=10,
+        help="Number of timing rounds per fixture (default: 10).",
+    )
+    args = parser.parse_args()
+
+    all_fixtures = discover_fixtures()
+    if not all_fixtures:
+        print("No test fixtures found in test-pages/", file=sys.stderr)
+        sys.exit(1)
+
+    fixtures = args.fixtures if args.fixtures else all_fixtures
+    # Validate fixture names.
+    for name in fixtures:
+        if name not in all_fixtures:
+            print(f"Unknown fixture: {name}", file=sys.stderr)
+            print(f"Available: {', '.join(all_fixtures)}", file=sys.stderr)
+            sys.exit(1)
+
+    rounds = args.rounds
+
+    # Header.
+    print()
+    print(f"{_BOLD}Readability Benchmark ({rounds} rounds per fixture){_RESET}")
+    has_node = shutil.which("node") is not None
+    has_lxml = _RefDocument is not None
+    status = []
+    status.append(f"zerodep: {_GREEN}yes{_RESET}")
+    lxml_status = _GREEN + "yes" + _RESET if has_lxml else _DIM + "no" + _RESET
+    status.append(f"readability-lxml: {lxml_status}")
+    status.append(
+        f"mozilla js: {_GREEN + 'yes' + _RESET if has_node else _DIM + 'no' + _RESET}"
+    )
+    print(f"  Implementations: {' | '.join(status)}")
+    print(f"  {_DIM}Times shown are mean. Ratios relative to zerodep.{_RESET}")
+    print()
+
+    # Column headers.
+    print(
+        f"  {'Fixture':<28s}  {'Size':>9s}  "
+        f"{'zerodep':>19s}  {'readability-lxml':>19s}  "
+        f"{'mozilla js':>19s}"
+    )
+    print("  " + "─" * 110)
+
+    for name in fixtures:
+        html = load_source(name)
+        html_size = len(html.encode("utf-8"))
+
+        # Benchmark all three.
+        zd = bench_zerodep(html, rounds)
+        lxml = bench_readability_lxml(html, rounds)
+        js = bench_mozilla_js(name, rounds)
+
+        print_results(name, html_size, zd, lxml, js)
+
+    print()
+
+
+if __name__ == "__main__":
+    main()

src/veilrender/_vendor/cache.py

@@ -0,0 +1,1023 @@
+# /// zerodep
+# version = "0.2.4"
+# deps = []
+# tier = "subsystem"
+# category = "storage"
+# note = "Install/update via `zerodep add cache`"
+# ///
+"""Zero-dependency caching with TTL, eviction policies, and async support.
+
+stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Provides: LRUCache, FIFOCache, LFUCache, TTLCache cache classes (MutableMapping),
+``cached`` decorator with sync/async auto-detection, and convenience decorators
+``lru_cache``, ``ttl_cache``, ``lfu_cache``, ``fifo_cache``.
+
+Does NOT implement: TLRUCache (per-item TTL function), MRUCache, RRCache,
+``cachedmethod``, ``condition`` parameter, multiple backends, serialization.
+
+Example::
+
+    from cache import lru_cache, ttl_cache, LRUCache, cached
+
+    # Convenience decorator (like functools.lru_cache but with more policies)
+    @lru_cache(maxsize=256)
+    def fibonacci(n):
+        return n if n < 2 else fibonacci(n - 1) + fibonacci(n - 2)
+
+    # TTL decorator
+    @ttl_cache(maxsize=100, ttl=60)
+    def fetch_config(key):
+        return load_from_db(key)
+
+    # Async support (auto-detected)
+    @lru_cache(maxsize=128)
+    async def fetch_data(url):
+        return await async_get(url)
+
+    # Direct cache class usage
+    cache = LRUCache(maxsize=1024)
+    cache["key"] = "value"
+
+    # Advanced: cached() with explicit lock
+    import threading
+    @cached(LRUCache(128), lock=threading.Lock(), info=True)
+    def thread_safe_compute(x):
+        return expensive(x)
+"""
+
+from __future__ import annotations
+
+import collections
+import collections.abc
+import functools
+import inspect
+import time
+from typing import Any, Callable
+
+# ── Key Functions ──────────────────────────────────────────────────────────
+
+
+class _HashedTuple(tuple):
+    """Tuple subclass that caches its hash value for fast repeated lookups."""
+
+    __hashvalue: int | None = None
+
+    def __hash__(self, hash=tuple.__hash__):  # type: ignore[override]
+        hashvalue = self.__hashvalue
+        if hashvalue is None:
+            self.__hashvalue = hashvalue = hash(self)
+        return hashvalue
+
+    def __add__(self, other, add=tuple.__add__):
+        return _HashedTuple(add(self, other))
+
+    def __radd__(self, other, add=tuple.__add__):
+        return _HashedTuple(add(other, self))
+
+
+_KWMARK = (_HashedTuple,)
+
+
+def hashkey(*args: Any, **kwargs: Any) -> _HashedTuple:
+    """Return a cache key for the given positional and keyword arguments.
+
+    This is the default key function for all cache decorators.
+    """
+    if kwargs:
+        return _HashedTuple(args + _KWMARK + tuple(sorted(kwargs.items())))
+    return _HashedTuple(args)
+
+
+def methodkey(_self: Any, *args: Any, **kwargs: Any) -> _HashedTuple:
+    """Like ``hashkey`` but ignores the first positional argument (``self``).
+
+    Use as the key function when caching instance methods.
+    """
+    return hashkey(*args, **kwargs)
+
+
+def typedkey(*args: Any, **kwargs: Any) -> _HashedTuple:
+    """Like ``hashkey`` but includes type information, so ``f(3)`` and
+    ``f(3.0)`` are cached separately.
+    """
+    if kwargs:
+        sorted_items = tuple(sorted(kwargs.items()))
+        return _HashedTuple(
+            args
+            + _KWMARK
+            + sorted_items
+            + tuple(type(v) for v in args)
+            + tuple(type(v) for _, v in sorted_items)
+        )
+    return _HashedTuple(args + tuple(type(v) for v in args))
+
+
+# ── Cache Info ─────────────────────────────────────────────────────────────
+
+CacheInfo = collections.namedtuple(
+    "CacheInfo", ["hits", "misses", "maxsize", "currsize"]
+)
+
+# ── Cache Base Class ───────────────────────────────────────────────────────
+
+
+class _DefaultSize:
+    """Lightweight size tracker that always returns 1 for any key."""
+
+    __slots__ = ()
+
+    def __getitem__(self, _: Any) -> int:
+        return 1
+
+    def __setitem__(self, _: Any, __: Any) -> None:
+        pass
+
+    def pop(self, _: Any, *args: Any) -> int:
+        return 1
+
+    def clear(self) -> None:
+        pass
+
+
+class Cache(collections.abc.MutableMapping):
+    """Mutable mapping to serve as a simple cache or cache base class.
+
+    Subclasses must override ``popitem`` to implement a specific eviction
+    policy.  The base class evicts arbitrary items (dict order).
+
+    Args:
+        maxsize: Maximum capacity (item count or weighted size).
+        getsizeof: Optional callable returning the size of a value.
+            Defaults to 1 per item.
+    """
+
+    __marker = object()
+
+    def __init__(
+        self,
+        maxsize: int | float,
+        getsizeof: Callable[[Any], int] | None = None,
+    ):
+        if maxsize < 0:
+            raise ValueError("maxsize must be non-negative")
+        self.__data: dict[Any, Any] = {}
+        self.__currsize: int | float = 0
+        self.__maxsize = maxsize
+        if getsizeof is not None:
+            self.__size: dict | _DefaultSize = {}
+            self.getsizeof = getsizeof  # type: ignore[assignment]
+        else:
+            self.__size = _DefaultSize()
+
+    def __repr__(self) -> str:
+        cls = self.__class__.__name__
+        return (
+            f"{cls}({self.__data!r}, "
+            f"maxsize={self.__maxsize}, currsize={self.__currsize})"
+        )
+
+    def __getitem__(self, key: Any) -> Any:
+        try:
+            return self.__data[key]
+        except KeyError:
+            return self.__missing__(key)
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        maxsize = self.__maxsize
+        size = self.getsizeof(value)
+        if size > maxsize:
+            raise ValueError("value too large")
+        if key in self.__data:
+            diffsize = size - self.__size[key]
+        else:
+            diffsize = size
+        while self.__currsize + diffsize > maxsize:
+            self.popitem()
+        if key in self.__data:
+            # Key might have been evicted during popitem loop
+            self.__currsize -= self.__size[key]
+        self.__data[key] = value
+        self.__size[key] = size
+        self.__currsize += size
+
+    def __delitem__(self, key: Any) -> None:
+        size = self.__size.pop(key)
+        del self.__data[key]
+        self.__currsize -= size
+
+    def __contains__(self, key: object) -> bool:
+        return key in self.__data
+
+    def __missing__(self, key: Any) -> Any:
+        raise KeyError(key)
+
+    def __iter__(self):
+        return iter(self.__data)
+
+    def __len__(self) -> int:
+        return len(self.__data)
+
+    @staticmethod
+    def getsizeof(value: Any) -> int:
+        """Return the size of *value*.  Defaults to 1."""
+        return 1
+
+    @property
+    def maxsize(self) -> int | float:
+        """Maximum cache capacity."""
+        return self.__maxsize
+
+    @property
+    def currsize(self) -> int | float:
+        """Current cache size (sum of item sizes)."""
+        return self.__currsize
+
+    def get(self, key: Any, default: Any = None) -> Any:
+        if key in self:
+            return self[key]
+        return default
+
+    def pop(self, key: Any, default: Any = __marker) -> Any:
+        if key in self:
+            value = self[key]
+            del self[key]
+            return value
+        if default is self.__marker:
+            raise KeyError(key)
+        return default
+
+    def setdefault(self, key: Any, default: Any = None) -> Any:
+        if key in self:
+            return self[key]
+        try:
+            self[key] = default
+        except ValueError:
+            pass
+        return default
+
+    def popitem(self) -> tuple[Any, Any]:
+        """Remove and return an arbitrary ``(key, value)`` pair.
+
+        Subclasses override this to implement eviction policies.
+        """
+        try:
+            key = next(iter(self.__data))
+        except StopIteration:
+            raise KeyError(f"{type(self).__name__} is empty") from None
+        return key, self.pop(key)
+
+    def clear(self) -> None:
+        self.__data.clear()
+        self.__size.clear()
+        self.__currsize = 0
+
+
+# ── FIFO Cache ─────────────────────────────────────────────────────────────
+
+
+class FIFOCache(Cache):
+    """First In First Out (FIFO) cache implementation.
+
+    Evicts the oldest inserted item when the cache is full.  Accessing an
+    item does **not** change its eviction priority.
+    """
+
+    def __init__(
+        self,
+        maxsize: int | float,
+        getsizeof: Callable[[Any], int] | None = None,
+    ):
+        super().__init__(maxsize, getsizeof)
+        self.__order: collections.OrderedDict[Any, None] = collections.OrderedDict()
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        if key in self:
+            del self.__order[key]
+        super().__setitem__(key, value)
+        self.__order[key] = None
+
+    def __delitem__(self, key: Any) -> None:
+        super().__delitem__(key)
+        del self.__order[key]
+
+    def popitem(self) -> tuple[Any, Any]:
+        """Remove and return the oldest inserted ``(key, value)`` pair."""
+        try:
+            key = next(iter(self.__order))
+        except StopIteration:
+            raise KeyError(f"{type(self).__name__} is empty") from None
+        return key, self.pop(key)
+
+    def clear(self) -> None:
+        super().clear()
+        self.__order.clear()
+
+
+# ── LRU Cache ──────────────────────────────────────────────────────────────
+
+
+class LRUCache(Cache):
+    """Least Recently Used (LRU) cache implementation.
+
+    Evicts the least recently accessed item when the cache is full.
+    Both reads and writes count as accesses.
+    """
+
+    def __init__(
+        self,
+        maxsize: int | float,
+        getsizeof: Callable[[Any], int] | None = None,
+    ):
+        super().__init__(maxsize, getsizeof)
+        self.__order: collections.OrderedDict[Any, None] = collections.OrderedDict()
+
+    def __getitem__(self, key: Any) -> Any:
+        # Bypass super().__getitem__ to avoid MRO dispatch overhead;
+        # call Cache.__getitem__ directly + inline move_to_end.
+        value = Cache.__getitem__(self, key)
+        self.__order.move_to_end(key)
+        return value
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        Cache.__setitem__(self, key, value)
+        try:
+            self.__order.move_to_end(key)
+        except KeyError:
+            self.__order[key] = None
+
+    def __delitem__(self, key: Any) -> None:
+        Cache.__delitem__(self, key)
+        del self.__order[key]
+
+    def popitem(self) -> tuple[Any, Any]:
+        """Remove and return the least recently used ``(key, value)`` pair."""
+        try:
+            key = next(iter(self.__order))
+        except StopIteration:
+            raise KeyError(f"{type(self).__name__} is empty") from None
+        return key, self.pop(key)
+
+    def clear(self) -> None:
+        Cache.clear(self)
+        self.__order.clear()
+
+
+# ── LFU Cache ──────────────────────────────────────────────────────────────
+
+
+class _LFUNode:
+    """Doubly-linked node for the LFU frequency list."""
+
+    __slots__ = ("count", "keys", "prev", "next")
+
+    def __init__(self, count: int = 0):
+        self.count = count
+        self.keys: set[Any] = set()
+        self.prev: _LFUNode = self
+        self.next: _LFUNode = self
+
+    def insert_after(self, node: _LFUNode) -> None:
+        """Insert *node* after this node."""
+        node.prev = self
+        node.next = self.next
+        self.next.prev = node
+        self.next = node
+
+    def unlink(self) -> None:
+        """Remove this node from the linked list."""
+        self.prev.next = self.next
+        self.next.prev = self.prev
+
+
+class LFUCache(Cache):
+    """Least Frequently Used (LFU) cache implementation.
+
+    Evicts the least frequently accessed item when the cache is full.
+    All operations are O(1).
+    """
+
+    def __init__(
+        self,
+        maxsize: int | float,
+        getsizeof: Callable[[Any], int] | None = None,
+    ):
+        super().__init__(maxsize, getsizeof)
+        self.__root = _LFUNode()  # sentinel
+        self.__links: dict[Any, _LFUNode] = {}
+
+    def __getitem__(self, key: Any) -> Any:
+        value = super().__getitem__(key)
+        self.__touch(key)
+        return value
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        existed = key in self
+        super().__setitem__(key, value)
+        if existed:
+            self.__touch(key)
+        else:
+            # New key starts at count=1
+            root = self.__root
+            first = root.next
+            if first is root or first.count != 1:
+                node = _LFUNode(count=1)
+                root.insert_after(node)
+            else:
+                node = first
+            node.keys.add(key)
+            self.__links[key] = node
+
+    def __delitem__(self, key: Any) -> None:
+        super().__delitem__(key)
+        node = self.__links.pop(key)
+        node.keys.discard(key)
+        if not node.keys:
+            node.unlink()
+
+    def __touch(self, key: Any) -> None:
+        """Increment frequency count for *key*."""
+        node = self.__links[key]
+        new_count = node.count + 1
+        nxt = node.next
+        if nxt is self.__root or nxt.count != new_count:
+            new_node = _LFUNode(count=new_count)
+            node.insert_after(new_node)
+        else:
+            new_node = nxt
+        new_node.keys.add(key)
+        node.keys.discard(key)
+        self.__links[key] = new_node
+        if not node.keys:
+            node.unlink()
+
+    def popitem(self) -> tuple[Any, Any]:
+        """Remove and return the least frequently used ``(key, value)`` pair."""
+        root = self.__root
+        node = root.next
+        if node is root:
+            raise KeyError(f"{type(self).__name__} is empty")
+        key = next(iter(node.keys))
+        # Bypass self.pop → self[key] → __touch to avoid wasteful
+        # frequency increment on a key that is about to be deleted.
+        value = Cache.__getitem__(self, key)
+        del self[key]
+        return key, value
+
+    def clear(self) -> None:
+        super().clear()
+        self.__links.clear()
+        self.__root.prev = self.__root
+        self.__root.next = self.__root
+
+
+# ── TTL Cache ─────────────────────��────────────────────────────────────────
+
+
+class _Timer:
+    """Wraps a timer function with nestable time-freezing.
+
+    Used by TTLCache to ensure time consistency within a single operation.
+    """
+
+    __slots__ = ("_timer", "_nesting", "_time")
+
+    def __init__(self, timer: Callable[[], float] = time.monotonic):
+        self._timer = timer
+        self._nesting = 0
+        self._time: float = 0.0
+
+    def __call__(self) -> float:
+        if self._nesting == 0:
+            return self._timer()
+        return self._time
+
+    def __enter__(self) -> float:
+        if self._nesting == 0:
+            self._time = self._timer()
+        self._nesting += 1
+        return self._time
+
+    def __exit__(self, *exc: Any) -> None:
+        self._nesting -= 1
+
+
+class _TTLLink:
+    """Doubly-linked node for TTLCache expiry ordering."""
+
+    __slots__ = ("key", "expires", "prev", "next")
+
+    def __init__(
+        self,
+        key: Any = None,
+        expires: float = 0.0,
+    ):
+        self.key = key
+        self.expires = expires
+        self.prev: _TTLLink = self
+        self.next: _TTLLink = self
+
+    def unlink(self) -> None:
+        self.prev.next = self.next
+        self.next.prev = self.prev
+
+
+class TTLCache(LRUCache):
+    """LRU cache with per-item time-to-live (TTL).
+
+    Items are evicted when they expire (checked lazily on access) or when
+    the cache is full (LRU order).
+
+    Args:
+        maxsize: Maximum cache capacity.
+        ttl: Time-to-live in seconds for each item.
+        timer: Callable returning the current time (default: ``time.monotonic``).
+        getsizeof: Optional callable returning the size of a value.
+    """
+
+    def __init__(
+        self,
+        maxsize: int | float,
+        ttl: float,
+        *,
+        timer: Callable[[], float] = time.monotonic,
+        getsizeof: Callable[[Any], int] | None = None,
+    ):
+        LRUCache.__init__(self, maxsize, getsizeof)
+        self.__ttl = ttl
+        self.__timer = _Timer(timer)
+        self.__root = _TTLLink()  # sentinel for expiry list
+        self.__links: dict[Any, _TTLLink] = {}
+
+    @property
+    def ttl(self) -> float:
+        """Time-to-live in seconds."""
+        return self.__ttl
+
+    @property
+    def timer(self) -> _Timer:
+        """The timer function."""
+        return self.__timer
+
+    def __contains__(self, key: object) -> bool:
+        link = self.__links.get(key)
+        if link is None:
+            return False
+        return self.__timer() < link.expires
+
+    def __getitem__(self, key: Any) -> Any:
+        link = self.__links.get(key)
+        if link is not None and self.__timer() >= link.expires:
+            del self[key]
+            return self.__missing__(key)
+        # Bypass LRUCache.__getitem__ → Cache.__getitem__ call chain;
+        # inline both to save one method-call and one dict lookup.
+        # Same direct-call pattern used by LFUCache.popitem.
+        value = Cache.__getitem__(self, key)
+        self._LRUCache__order.move_to_end(key)  # type: ignore[attr-defined]
+        return value
+
+    def __setitem__(self, key: Any, value: Any) -> None:
+        with self.__timer as now:
+            self.expire(now)
+            LRUCache.__setitem__(self, key, value)
+            # Update or create expiry link
+            link = self.__links.get(key)
+            if link is not None:
+                link.unlink()
+            else:
+                link = _TTLLink()
+                self.__links[key] = link
+            link.key = key
+            link.expires = now + self.__ttl
+            # Append to end of expiry list (newest)
+            tail = self.__root.prev
+            link.prev = tail
+            link.next = self.__root
+            tail.next = link
+            self.__root.prev = link
+
+    def __delitem__(self, key: Any) -> None:
+        LRUCache.__delitem__(self, key)
+        link = self.__links.pop(key)
+        link.unlink()
+
+    def __iter__(self):
+        now = self.__timer()
+        for key in super().__iter__():
+            link = self.__links.get(key)
+            if link is not None and now < link.expires:
+                yield key
+
+    def __len__(self) -> int:
+        now = self.__timer()
+        # Single dict lookup via .get() instead of ``key in`` + ``[key]``.
+        links_get = self.__links.get
+        return sum(
+            1
+            for key in super().__iter__()
+            if (link := links_get(key)) is not None and now < link.expires
+        )
+
+    @property
+    def currsize(self) -> int | float:
+        """Current size, excluding expired items."""
+        self.expire()
+        return super().currsize
+
+    def expire(self, time: float | None = None) -> list[tuple[Any, Any]]:
+        """Remove expired items and return them as a list of ``(key, value)`` pairs."""
+        if time is None:
+            time = self.__timer()
+        root = self.__root
+        expired: list[tuple[Any, Any]] = []
+        link = root.next
+        while link is not root and link.expires <= time:
+            nxt = link.next
+            key = link.key
+            try:
+                value = Cache.__getitem__(self, key)
+                expired.append((key, value))
+                del self[key]
+            except KeyError:
+                pass
+            link = nxt
+        return expired
+
+    def clear(self) -> None:
+        LRUCache.clear(self)
+        self.__links.clear()
+        self.__root.prev = self.__root
+        self.__root.next = self.__root
+
+
+# ── Decorators ─────────────────────────────────────────────────────────────
+
+_MISS = object()  # sentinel for cache lookup miss
+
+
+class _Stats:
+    """Mutable hit/miss counters shared by cache wrapper closures."""
+
+    __slots__ = ("hits", "misses")
+
+    def __init__(self) -> None:
+        self.hits = 0
+        self.misses = 0
+
+
+def _get_cache_maxsize(
+    cache: collections.abc.MutableMapping,
+) -> int | float | None:
+    """Return maxsize if *cache* is a ``Cache`` instance, else ``None``."""
+    return cache.maxsize if isinstance(cache, Cache) else None
+
+
+def _get_cache_currsize(cache: collections.abc.MutableMapping) -> int | float:
+    """Return current size of *cache*."""
+    return cache.currsize if isinstance(cache, Cache) else len(cache)
+
+
+def _attach_cache_info(
+    wrapper: Callable,
+    cache: collections.abc.MutableMapping,
+    lock: Any | None,
+    stats: _Stats,
+    maxsize: int | float | None,
+) -> None:
+    """Attach ``cache_info()`` and ``cache_clear()`` methods to *wrapper*."""
+
+    def cache_info() -> CacheInfo:
+        return CacheInfo(stats.hits, stats.misses, maxsize, _get_cache_currsize(cache))
+
+    def cache_clear() -> None:
+        with lock if lock else _no_lock():
+            cache.clear()
+        stats.hits = stats.misses = 0
+
+    wrapper.cache_info = cache_info  # type: ignore[attr-defined]
+    wrapper.cache_clear = cache_clear  # type: ignore[attr-defined]
+
+
+def _attach_noop_info(
+    wrapper: Callable,
+    stats: _Stats,
+) -> None:
+    """Attach ``cache_info()`` and ``cache_clear()`` for a no-op wrapper."""
+
+    def cache_info() -> CacheInfo:
+        return CacheInfo(stats.hits, stats.misses, None, 0)
+
+    def cache_clear() -> None:
+        stats.hits = stats.misses = 0
+
+    wrapper.cache_info = cache_info  # type: ignore[attr-defined]
+    wrapper.cache_clear = cache_clear  # type: ignore[attr-defined]
+
+
+def _make_sync_wrapper(
+    fn: Callable,
+    cache: collections.abc.MutableMapping | None,
+    key: Callable,
+    lock: Any | None,
+    info: bool,
+) -> Callable:
+    """Build a synchronous caching wrapper."""
+    stats = _Stats()
+
+    if cache is None:
+
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            stats.misses += 1
+            return fn(*args, **kwargs)
+
+        if info:
+            _attach_noop_info(wrapper, stats)
+        return wrapper
+
+    # Pre-cache method references to avoid attribute lookup per call.
+    cache_getitem = cache.__getitem__
+    cache_setitem = cache.__setitem__
+    cache_setdefault = cache.setdefault
+
+    if lock is not None:
+
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            k = key(*args, **kwargs)
+            with lock:
+                try:
+                    result = cache_getitem(k)
+                except KeyError:
+                    result = _MISS
+            if result is not _MISS:
+                stats.hits += 1
+                return result
+            stats.misses += 1
+            v = fn(*args, **kwargs)
+            # Inline thread-safe store (was _cache_store_default).
+            with lock:
+                try:
+                    return cache_setdefault(k, v)
+                except ValueError:
+                    return v
+
+    else:
+
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            k = key(*args, **kwargs)
+            try:
+                result = cache_getitem(k)
+            except KeyError:
+                stats.misses += 1
+                v = fn(*args, **kwargs)
+                try:
+                    cache_setitem(k, v)
+                except ValueError:
+                    pass
+                return v
+            stats.hits += 1
+            return result
+
+    if info:
+        _attach_cache_info(wrapper, cache, lock, stats, _get_cache_maxsize(cache))
+
+    return wrapper
+
+
+def _make_async_wrapper(
+    fn: Callable,
+    cache: collections.abc.MutableMapping | None,
+    key: Callable,
+    lock: Any | None,
+    info: bool,
+) -> Callable:
+    """Build an asynchronous caching wrapper."""
+    stats = _Stats()
+
+    if cache is None:
+
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            stats.misses += 1
+            return await fn(*args, **kwargs)
+
+        if info:
+            _attach_noop_info(wrapper, stats)
+        return wrapper
+
+    # Pre-cache method references to avoid attribute lookup per call.
+    cache_getitem = cache.__getitem__
+    cache_setitem = cache.__setitem__
+    cache_setdefault = cache.setdefault
+
+    if lock is not None:
+
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            k = key(*args, **kwargs)
+            async with lock:
+                try:
+                    result = cache_getitem(k)
+                except KeyError:
+                    result = _MISS
+            if result is not _MISS:
+                stats.hits += 1
+                return result
+            stats.misses += 1
+            v = await fn(*args, **kwargs)
+            # Inline thread-safe store (was _cache_store_default).
+            async with lock:
+                try:
+                    return cache_setdefault(k, v)
+                except ValueError:
+                    return v
+
+    else:
+
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            k = key(*args, **kwargs)
+            try:
+                result = cache_getitem(k)
+            except KeyError:
+                stats.misses += 1
+                v = await fn(*args, **kwargs)
+                try:
+                    cache_setitem(k, v)
+                except ValueError:
+                    pass
+                return v
+            stats.hits += 1
+            return result
+
+    if info:
+        _attach_cache_info(wrapper, cache, lock, stats, _get_cache_maxsize(cache))
+
+    return wrapper
+
+
+class _no_lock:
+    """Dummy context manager when no lock is provided."""
+
+    def __enter__(self) -> None:
+        pass
+
+    def __exit__(self, *exc: Any) -> None:
+        pass
+
+
+def cached(
+    cache: Cache | collections.abc.MutableMapping | None,
+    *,
+    key: Callable[..., Any] = hashkey,
+    lock: Any | None = None,
+    info: bool = False,
+) -> Callable:
+    """Decorator to wrap a function with a memoizing callable.
+
+    Args:
+        cache: A cache instance (any MutableMapping) or ``None`` to disable.
+        key: Key function (default ``hashkey``).
+        lock: A lock object (``threading.Lock`` for sync, ``asyncio.Lock``
+            for async).  The lock is released while the wrapped function
+            executes.
+        info: If ``True``, attach ``cache_info()`` and ``cache_clear()``
+            methods to the wrapper.
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        if inspect.iscoroutinefunction(fn):
+            wrapper = _make_async_wrapper(fn, cache, key, lock, info)
+        else:
+            wrapper = _make_sync_wrapper(fn, cache, key, lock, info)
+        wrapper.cache = cache  # type: ignore[attr-defined]
+        wrapper.cache_key = key  # type: ignore[attr-defined]
+        wrapper.cache_lock = lock  # type: ignore[attr-defined]
+        return functools.update_wrapper(wrapper, fn)
+
+    return decorator
+
+
+# ── Convenience Decorators ─────────────────────────────────────────────────
+
+
+def lru_cache(
+    fn: Callable[..., Any] | None = None,
+    *,
+    maxsize: int = 128,
+    key: Callable[..., Any] = hashkey,
+    lock: Any | None = None,
+    info: bool = True,
+) -> Callable[..., Any]:
+    """LRU cache decorator.  Auto-detects sync/async.
+
+    Unlike ``functools.lru_cache``, supports TTL (via ``ttl_cache``),
+    async functions, and explicit lock objects.
+
+    Args:
+        maxsize: Maximum number of cached results.
+        key: Key function (default ``hashkey``).
+        lock: Optional lock for thread/async safety.
+        info: Attach ``cache_info()``/``cache_clear()`` (default ``True``).
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        c = LRUCache(maxsize)
+        return cached(c, key=key, lock=lock, info=info)(fn)
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+def fifo_cache(
+    fn: Callable[..., Any] | None = None,
+    *,
+    maxsize: int = 128,
+    key: Callable[..., Any] = hashkey,
+    lock: Any | None = None,
+    info: bool = True,
+) -> Callable[..., Any]:
+    """FIFO cache decorator.  Auto-detects sync/async.
+
+    Evicts the oldest inserted item regardless of access pattern.
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        c = FIFOCache(maxsize)
+        return cached(c, key=key, lock=lock, info=info)(fn)
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+def lfu_cache(
+    fn: Callable[..., Any] | None = None,
+    *,
+    maxsize: int = 128,
+    key: Callable[..., Any] = hashkey,
+    lock: Any | None = None,
+    info: bool = True,
+) -> Callable[..., Any]:
+    """LFU cache decorator.  Auto-detects sync/async.
+
+    Evicts the least frequently accessed item.
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        c = LFUCache(maxsize)
+        return cached(c, key=key, lock=lock, info=info)(fn)
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+def ttl_cache(
+    fn: Callable[..., Any] | None = None,
+    *,
+    maxsize: int = 128,
+    ttl: float = 600,
+    timer: Callable[[], float] = time.monotonic,
+    key: Callable[..., Any] = hashkey,
+    lock: Any | None = None,
+    info: bool = True,
+) -> Callable[..., Any]:
+    """TTL cache decorator.  Auto-detects sync/async.
+
+    Items expire after *ttl* seconds (default 600 = 10 minutes).
+    Eviction follows LRU order when the cache is full.
+    """
+
+    def decorator(fn: Callable) -> Callable:
+        c = TTLCache(maxsize, ttl, timer=timer)
+        return cached(c, key=key, lock=lock, info=info)(fn)
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+# ── Public API ─────────────────────────────────────────────────────────────
+
+__all__ = [
+    # Cache classes
+    "Cache",
+    "FIFOCache",
+    "LFUCache",
+    "LRUCache",
+    "TTLCache",
+    # Decorators
+    "cached",
+    "fifo_cache",
+    "lfu_cache",
+    "lru_cache",
+    "ttl_cache",
+    # Key functions
+    "hashkey",
+    "methodkey",
+    "typedkey",
+    # Stats
+    "CacheInfo",
+]

src/veilrender/_vendor/config.py

@@ -0,0 +1,713 @@
+# /// zerodep
+# version = "0.3.0"
+# deps = ["dotenv", "yaml", "jsonc"]
+# tier = "subsystem"
+# category = "config"
+# note = "Install/update via `zerodep add config`"
+# ///
+
+"""Unified configuration loader — zero dependencies, stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Drop-in replacement for python-decouple / dynaconf core functionality.
+Loads settings from environment variables, .env files, and config files
+(JSON, JSONC, YAML, TOML, INI) with type coercion and prefix support.
+
+Example::
+
+    from config import config, setup
+
+    # Auto-discovers .env, reads env vars
+    setup(prefix="MYAPP_")
+    debug = config("DEBUG", default=False, cast=bool)
+    port  = config("PORT", default=8000, cast=int)
+    hosts = config("ALLOWED_HOSTS", cast=Csv())
+
+    # Or use Config directly
+    cfg = Config(config_path="settings.yaml", prefix="MYAPP_")
+    db_host = cfg("DATABASE__HOST", default="localhost")
+"""
+
+from __future__ import annotations
+
+import configparser
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+__all__ = [
+    # Sentinels
+    "MISSING",
+    # Exceptions
+    "ConfigError",
+    "UndefinedValueError",
+    # Type coercion helpers
+    "Csv",
+    "Choices",
+    # Main class
+    "Config",
+    # Module-level convenience
+    "setup",
+    "config",
+]
+
+
+def _ensure_sibling_path(name: str) -> str:
+    """Return the sibling module directory and prepend it to ``sys.path``."""
+    sibling_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", name)
+    if sibling_dir not in sys.path:
+        sys.path.insert(0, sibling_dir)
+    return sibling_dir
+
+
+# ── Sibling module loaders (lazy) ───────────────────────────────────────────
+
+
+def _load_dotenv_helpers() -> tuple[Callable[..., Any], Callable[..., Any]]:
+    """Load sibling ``dotenv`` helpers on demand."""
+    _ensure_sibling_path("dotenv")
+    sys.modules.pop("dotenv", None)
+    try:
+        from dotenv import dotenv_values, find_dotenv
+    except ImportError as exc:
+        raise ImportError(
+            ".env loading requires the sibling dotenv module. "
+            "Copy dotenv/dotenv.py into your project, "
+            "or set dotenv_path=None to disable."
+        ) from exc
+    return dotenv_values, find_dotenv
+
+
+def _load_yaml_loader() -> Callable[[str], Any]:
+    """Load the sibling ``yaml`` module's ``load`` function on demand."""
+    _ensure_sibling_path("yaml")
+    sys.modules.pop("yaml", None)
+    try:
+        from yaml import load as yaml_load
+    except ImportError as exc:
+        raise ImportError(
+            "YAML config files require the sibling yaml module. "
+            "Copy yaml/yaml.py into your project."
+        ) from exc
+    return yaml_load
+
+
+def _load_jsonc_loader() -> Callable[[str], Any] | None:
+    """Load the sibling ``jsonc`` module's ``loads`` function if available."""
+    _ensure_sibling_path("jsonc")
+    sys.modules.pop("jsonc", None)
+    try:
+        from jsonc import loads as jsonc_loads
+    except ImportError:
+        return None
+    return jsonc_loads
+
+
+# ── Stdlib tomllib (Python 3.11+) ───────────────────────────────────────────
+
+try:
+    import tomllib  # type: ignore[import-not-found]
+
+    _HAS_TOML = True
+except ModuleNotFoundError:
+    _HAS_TOML = False
+
+# ── Sentinels ───────────────────────────────────────────────────────────────
+
+
+class _Missing:
+    """Sentinel for missing configuration values."""
+
+    _instance: _Missing | None = None
+
+    def __new__(cls) -> _Missing:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+MISSING = _Missing()
+
+
+class _Auto:
+    """Sentinel indicating auto-discovery of .env files."""
+
+    _instance: _Auto | None = None
+
+    def __new__(cls) -> _Auto:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "AUTO"
+
+
+_AUTO = _Auto()
+
+# ── Sentinel for injection parameters ──────────────────────────────────────
+
+
+class _Unset:
+    """Sentinel indicating 'use default sibling auto-discovery'."""
+
+    _instance: _Unset | None = None
+
+    def __new__(cls) -> _Unset:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+_UNSET = _Unset()
+
+# ── Exceptions ──────────────────────────────────────────────────────────────
+
+
+class ConfigError(Exception):
+    """Base exception for all config operations."""
+
+
+class UndefinedValueError(ConfigError):
+    """Raised when a required configuration value is missing."""
+
+
+# ── Bool constants ──────────────────────────────────────────────────────────
+
+_TRUTHY = frozenset({"1", "true", "yes", "on", "t", "y"})
+_FALSY = frozenset({"0", "false", "no", "off", "f", "n", ""})
+
+# ── Type coercion helpers ───────────────────────────────────────────────────
+
+
+class Csv:
+    """Parse comma-separated values with optional per-item casting.
+
+    Example::
+
+        Csv()("a, b, c")           # ["a", "b", "c"]
+        Csv(cast=int)("1,2,3")     # [1, 2, 3]
+        Csv(delimiter=";")("a;b")  # ["a", "b"]
+
+    Args:
+        cast: Callable applied to each item after splitting.
+        delimiter: String to split on.
+        strip: Characters to strip from each item. Use ``" %s"`` to strip
+            whitespace around the format-string placeholder (default).
+        post_process: Callable applied to the final list (e.g. ``tuple``).
+    """
+
+    def __init__(
+        self,
+        cast: Callable[[str], Any] = str,
+        delimiter: str = ",",
+        strip: str = " %s",
+        post_process: Callable[[list[Any]], Any] = list,
+    ) -> None:
+        self.cast = cast
+        self.delimiter = delimiter
+        self.strip = strip
+        self.post_process = post_process
+
+    def __call__(self, value: str) -> Any:
+        if isinstance(value, (list, tuple)):
+            return self.post_process([self.cast(item) for item in value])
+        parts = str(value).split(self.delimiter)
+        result = []
+        for part in parts:
+            item = part.strip(self.strip.replace("%s", "")) if self.strip else part
+            if item or not self.strip:
+                result.append(self.cast(item))
+        return self.post_process(result)
+
+
+class Choices:
+    """Validate that a value belongs to a fixed set.
+
+    Example::
+
+        Choices(["dev", "staging", "prod"])("dev")  # "dev"
+        Choices([1, 2, 3], cast=int)("2")           # 2
+
+    Args:
+        choices: Allowed values (after casting).
+        cast: Callable applied before validation.
+    """
+
+    def __init__(
+        self,
+        choices: Sequence[Any],
+        cast: Callable[[str], Any] = str,
+    ) -> None:
+        self.choices = choices
+        self.cast = cast
+
+    def __call__(self, value: str) -> Any:
+        casted = self.cast(value)
+        if casted not in self.choices:
+            raise ValueError(
+                f"{casted!r} is not a valid choice. Allowed: {list(self.choices)}"
+            )
+        return casted
+
+
+# ── File loaders ────────────────────────────────────────────────────────────
+
+
+def _load_json_file(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Load a JSON file and return a dict."""
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"JSON config must be an object, got {type(data).__name__}")
+    return data
+
+
+def _load_jsonc_file(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Load a JSONC file, falling back to plain JSON if jsonc module is unavailable."""
+    with open(path, encoding="utf-8") as f:
+        text = f.read()
+    jsonc_loads = _load_jsonc_loader()
+    if jsonc_loads is not None:
+        data = jsonc_loads(text)
+    else:
+        data = json.loads(text)
+    if not isinstance(data, dict):
+        raise ValueError(f"JSONC config must be an object, got {type(data).__name__}")
+    return data
+
+
+def _load_yaml_file(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Load a YAML file using the sibling yaml module."""
+    yaml_load = _load_yaml_loader()
+    with open(path, encoding="utf-8") as f:
+        text = f.read()
+    data = yaml_load(text)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(f"YAML config must be a mapping, got {type(data).__name__}")
+    return data
+
+
+def _load_toml_file(path: str | os.PathLike[str]) -> dict[str, Any]:
+    """Load a TOML file using stdlib tomllib (Python 3.11+)."""
+    if not _HAS_TOML:
+        raise ImportError("TOML config files require Python 3.11+ (tomllib).")
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _load_ini_file(
+    path: str | os.PathLike[str], separator: str = "__"
+) -> dict[str, Any]:
+    """Load an INI/CFG file and flatten sections into separator-joined keys.
+
+    Example: ``[database]`` section with ``host = localhost`` becomes
+    ``database__host = localhost`` (using the default separator).
+    """
+    parser = configparser.ConfigParser()
+    parser.read(path, encoding="utf-8")
+    data: dict[str, Any] = {}
+    for section in parser.sections():
+        for key, value in parser.items(section):
+            flat_key = f"{section}{separator}{key}"
+            data[flat_key] = value
+    if parser.defaults():
+        for key, value in parser.defaults().items():
+            data[key] = value
+    return data
+
+
+_LOADERS: dict[str, Callable[..., dict[str, Any]]] = {
+    ".json": _load_json_file,
+    ".jsonc": _load_jsonc_file,
+    ".yaml": _load_yaml_file,
+    ".yml": _load_yaml_file,
+    ".toml": _load_toml_file,
+    ".ini": _load_ini_file,
+    ".cfg": _load_ini_file,
+}
+
+# ── Internal helpers ────────────────────────────────────────────────────────
+
+
+def _cast_bool(value: Any) -> bool:
+    """Convert a value to bool using common truthy/falsy strings."""
+    if isinstance(value, bool):
+        return value
+    s = str(value).lower().strip()
+    if s in _TRUTHY:
+        return True
+    if s in _FALSY:
+        return False
+    raise ValueError(
+        f"Cannot convert {value!r} to bool. Use one of: {sorted(_TRUTHY | _FALSY)}"
+    )
+
+
+def _cast_list(value: Any) -> list[Any]:
+    """Convert a value to list: try JSON array first, then comma-split."""
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    s = str(value).strip()
+    if s.startswith("["):
+        try:
+            result = json.loads(s)
+            if isinstance(result, list):
+                return result
+        except (json.JSONDecodeError, ValueError):
+            pass
+    return [item.strip() for item in s.split(",") if item.strip()]
+
+
+def _cast_tuple(value: Any) -> tuple[Any, ...]:
+    """Convert a value to tuple via _cast_list."""
+    return tuple(_cast_list(value))
+
+
+def _apply_cast(value: Any, cast: type | Callable[..., Any] | None) -> Any:
+    """Apply a type cast to a value."""
+    if cast is None:
+        return value
+    if cast is bool:
+        return _cast_bool(value)
+    if cast is list:
+        return _cast_list(value)
+    if cast is tuple:
+        return _cast_tuple(value)
+    return cast(value)
+
+
+def _deep_get(data: dict[str, Any], parts: list[str]) -> Any:
+    """Retrieve a nested value from a dict using a list of key parts.
+
+    Returns *MISSING* if any intermediate key is missing or not a dict.
+    """
+    current: Any = data
+    for part in parts:
+        if not isinstance(current, dict):
+            return MISSING
+        # Try exact key first, then case-insensitive
+        if part in current:
+            current = current[part]
+        else:
+            lower = part.lower()
+            found = False
+            for k in current:
+                if k.lower() == lower:
+                    current = current[k]
+                    found = True
+                    break
+            if not found:
+                return MISSING
+    return current
+
+
+def _flatten_dict(
+    data: dict[str, Any], separator: str = "__", prefix: str = ""
+) -> dict[str, Any]:
+    """Flatten a nested dict into separator-joined keys."""
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        full_key = f"{prefix}{separator}{key}" if prefix else key
+        if isinstance(value, dict):
+            result.update(_flatten_dict(value, separator, full_key))
+        else:
+            result[full_key] = value
+    return result
+
+
+# ── Main Config class ───────────────────────────────────────────────────────
+
+
+class Config:
+    """Unified configuration loader with multi-source support.
+
+    Sources are checked in priority order (highest first):
+
+    1. Environment variables (``os.environ``), optionally prefixed
+    2. ``.env`` file values (via sibling dotenv module)
+    3. Config file values (JSON, JSONC, YAML, TOML, INI)
+    4. Default value passed to ``get()``/``__call__()``
+
+    Args:
+        dotenv_path: Path to ``.env`` file. Use ``None`` to disable,
+            or omit (default ``_AUTO``) to auto-discover by searching
+            upward from the current directory.
+        config_path: Path to a config file. Format is detected from the
+            file extension.
+        prefix: Prefix for environment variable lookups. For example,
+            ``prefix="MYAPP_"`` means looking up ``"PORT"`` checks
+            ``os.environ["MYAPP_PORT"]``.
+        separator: Separator for nested key access. Default ``"__"``
+            means ``"DATABASE__HOST"`` resolves to ``data["DATABASE"]["HOST"]``
+            or ``data["database"]["host"]`` in config files.
+        loaders: Override the file-format loader registry. Defaults to
+            ``_UNSET`` (use built-in loaders with sibling auto-discovery
+            for yaml/jsonc). Pass a ``dict`` mapping extensions (e.g.
+            ``".yaml"``) to loader callables to replace the defaults.
+            Stdlib loaders (json, toml, ini) are always available unless
+            explicitly overridden.
+        dotenv_loader: Override the dotenv loading mechanism. Defaults to
+            ``_UNSET`` (auto-discover sibling ``dotenv`` module). Pass
+            ``None`` to disable .env loading entirely, or a callable that
+            returns ``(dotenv_values_fn, find_dotenv_fn)`` to inject a
+            custom implementation.
+
+    Example::
+
+        cfg = Config(config_path="settings.yaml", prefix="MYAPP_")
+        debug = cfg("DEBUG", default=False, cast=bool)
+        db_host = cfg("DATABASE__HOST", default="localhost")
+    """
+
+    def __init__(
+        self,
+        *,
+        dotenv_path: str | os.PathLike[str] | None | _Auto = _AUTO,
+        config_path: str | os.PathLike[str] | None = None,
+        prefix: str = "",
+        separator: str = "__",
+        loaders: dict[str, Callable[..., dict[str, Any]]] | None | _Unset = _UNSET,
+        dotenv_loader: Callable[[], tuple[Callable[..., Any], Callable[..., Any]]]
+        | None
+        | _Unset = _UNSET,
+    ) -> None:
+        self._prefix = prefix
+        self._separator = separator
+        self._dotenv_data: dict[str, str | None] = {}
+        self._config_data: dict[str, Any] = {}
+        self._loaders: dict[str, Callable[..., dict[str, Any]]]
+
+        # Resolve loader registry
+        if isinstance(loaders, _Unset):
+            self._loaders = _LOADERS
+        elif loaders is None:
+            self._loaders = {}
+        else:
+            self._loaders = loaders
+
+        # Load .env file
+        if dotenv_loader is None:
+            pass  # .env explicitly disabled
+        elif isinstance(dotenv_path, _Auto):
+            try:
+                if isinstance(dotenv_loader, _Unset):
+                    dotenv_values, find_dotenv = _load_dotenv_helpers()
+                else:
+                    dotenv_values, find_dotenv = dotenv_loader()
+            except ImportError:
+                pass
+            else:
+                found = find_dotenv(usecwd=True)
+                if found:
+                    self._dotenv_data = dotenv_values(found)
+        elif dotenv_path is not None:
+            if isinstance(dotenv_loader, _Unset):
+                dotenv_values, _find_dotenv = _load_dotenv_helpers()
+            else:
+                dotenv_values, _find_dotenv = dotenv_loader()
+            self._dotenv_data = dotenv_values(str(dotenv_path))
+
+        # Load config file
+        if config_path is not None:
+            self._load_config_file(config_path)
+
+    def _load_config_file(self, path: str | os.PathLike[str]) -> None:
+        """Load a config file based on its extension."""
+        p = Path(path)
+        ext = p.suffix.lower()
+        loader = self._loaders.get(ext)
+        if loader is None:
+            raise ValueError(
+                f"Unsupported config file format: {ext!r}. "
+                f"Supported: {', '.join(sorted(self._loaders))}"
+            )
+        if loader in (_load_ini_file,):
+            self._config_data = loader(p, separator=self._separator)
+        else:
+            self._config_data = loader(p)
+
+    def _lookup(self, key: str) -> Any:
+        """Look up a key across all sources in priority order.
+
+        Returns the value if found, or *MISSING* if not found anywhere.
+        """
+        # 1. Environment variables (with prefix)
+        env_key = f"{self._prefix}{key}" if self._prefix else key
+        env_val = os.environ.get(env_key)
+        if env_val is not None:
+            return env_val
+
+        # 2. .env file values (with prefix)
+        dotenv_val = self._dotenv_data.get(env_key)
+        if dotenv_val is not None:
+            return dotenv_val
+
+        # 3. Config file values (exact key first, then nested lookup)
+        if self._config_data:
+            # Exact key match (e.g. INI-flattened keys)
+            if key in self._config_data:
+                return self._config_data[key]
+            # Nested lookup via separator splitting
+            if self._separator in key:
+                parts = key.split(self._separator)
+                result = _deep_get(self._config_data, parts)
+                if result is not MISSING:
+                    return result
+
+        return MISSING
+
+    def get(
+        self,
+        key: str,
+        *,
+        default: Any = MISSING,
+        cast: type | Callable[..., Any] | None = None,
+    ) -> Any:
+        """Retrieve a configuration value.
+
+        Args:
+            key: Configuration key to look up.
+            default: Default value if key is not found. If not provided and
+                the key is missing, ``UndefinedValueError`` is raised.
+            cast: Type or callable to apply to the value. Built-in support
+                for ``bool``, ``int``, ``float``, ``list``, ``tuple``.
+                Also accepts ``Csv(...)`` and ``Choices(...)`` instances.
+
+        Returns:
+            The resolved and optionally cast configuration value.
+
+        Raises:
+            UndefinedValueError: If key is missing and no default is given.
+        """
+        value = self._lookup(key)
+
+        if value is MISSING:
+            if default is MISSING:
+                raise UndefinedValueError(
+                    f"{key!r} is not set and has no default value."
+                )
+            value = default
+
+        return _apply_cast(value, cast)
+
+    def __call__(
+        self,
+        key: str,
+        *,
+        default: Any = MISSING,
+        cast: type | Callable[..., Any] | None = None,
+    ) -> Any:
+        """Shorthand for ``get()``. See :meth:`get` for details."""
+        return self.get(key, default=default, cast=cast)
+
+    def has(self, key: str) -> bool:
+        """Check whether a key exists in any source."""
+        return self._lookup(key) is not MISSING
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return a merged view of all config sources (flattened).
+
+        Lower-priority sources are merged first, so higher-priority
+        sources overwrite them.
+        """
+        merged: dict[str, Any] = {}
+        # 3. Config file (lowest priority)
+        if self._config_data:
+            merged.update(_flatten_dict(self._config_data, self._separator))
+        # 2. .env file
+        for k, v in self._dotenv_data.items():
+            if v is not None:
+                merged[k] = v
+        # 1. Environment variables (only those matching prefix)
+        if self._prefix:
+            plen = len(self._prefix)
+            for k, v in os.environ.items():
+                if k.startswith(self._prefix):
+                    merged[k[plen:]] = v
+        else:
+            merged.update(os.environ)
+        return merged
+
+
+# ── Module-level convenience ────────────────────────────────────────────────
+
+_default_config: Config | None = None
+
+
+def setup(
+    *,
+    dotenv_path: str | os.PathLike[str] | None | _Auto = _AUTO,
+    config_path: str | os.PathLike[str] | None = None,
+    prefix: str = "",
+    separator: str = "__",
+) -> Config:
+    """Initialize the module-level :class:`Config` instance.
+
+    Call this once at application startup to configure sources and prefix.
+    Subsequent calls to :func:`config` will use this instance.
+
+    Args:
+        dotenv_path: Path to ``.env`` file, ``None`` to disable, or
+            ``_AUTO`` (default) to auto-discover.
+        config_path: Path to a config file (JSON/YAML/TOML/INI).
+        prefix: Prefix for environment variable lookups.
+        separator: Separator for nested key access.
+
+    Returns:
+        The newly created :class:`Config` instance.
+    """
+    global _default_config
+    _default_config = Config(
+        dotenv_path=dotenv_path,
+        config_path=config_path,
+        prefix=prefix,
+        separator=separator,
+    )
+    return _default_config
+
+
+def config(
+    key: str,
+    *,
+    default: Any = MISSING,
+    cast: type | Callable[..., Any] | None = None,
+) -> Any:
+    """Look up a configuration value using the module-level instance.
+
+    If :func:`setup` has not been called, a default :class:`Config` is
+    created automatically (auto-discovers ``.env``, no config file,
+    no prefix).
+
+    Args:
+        key: Configuration key.
+        default: Fallback value if missing.
+        cast: Type or callable to coerce the value.
+
+    Returns:
+        The resolved configuration value.
+
+    Raises:
+        UndefinedValueError: If key is missing and no default.
+    """
+    global _default_config
+    if _default_config is None:
+        _default_config = Config()
+    return _default_config(key, default=default, cast=cast)

src/veilrender/_vendor/dotenv.py

@@ -0,0 +1,514 @@
+# /// zerodep
+# version = "0.3.1"
+# deps = []
+# tier = "simple"
+# category = "config"
+# note = "Install/update via `zerodep add dotenv`"
+# ///
+
+""".env file parser and loader — zero dependencies, stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Drop-in replacement for python-dotenv core functionality.
+
+Example::
+
+    load_dotenv()                       # load .env into os.environ
+    values = dotenv_values(".env")       # parse without modifying environ
+    path = find_dotenv()                 # search up for .env file
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+import re
+import sys
+from pathlib import Path
+from typing import IO, Iterator, Mapping
+
+__all__ = [
+    "find_dotenv",
+    "get_key",
+    "set_key",
+    "unset_key",
+    "dotenv_values",
+    "load_dotenv",
+]
+
+# ── Constants / Regex ──────────────────────────────────────────────────────────
+
+_ESCAPE_MAP = {
+    "\\": "\\",
+    "'": "'",
+    '"': '"',
+    "n": "\n",
+    "r": "\r",
+    "t": "\t",
+    "$": "$",
+    " ": " ",
+}
+
+# Matches a single .env binding line.  Groups:
+#   key   – variable name
+#   sq    – single-quoted value content
+#   dq    – double-quoted value content (may span multiple lines)
+#   uq    – unquoted value content
+_BINDING_RE = re.compile(
+    r"""
+    \A\s*                              # leading whitespace
+    (?:export\s+)?                     # optional export prefix
+    (?P<key>[A-Za-z_]\w*)              # key (must start with letter or _)
+    (?:                                # optional =value part
+      \s*=\s*                          # equals sign
+      (?:
+        '(?P<sq>[^']*)'                # single-quoted (no escapes)
+      | "(?P<dq>(?:[^"\\]|\\.)*)"      # double-quoted (with escapes)
+      | (?P<uq>[^\#\r\n]*)            # unquoted (up to # or EOL)
+      )
+    )?                                 # entire =value is optional
+    \s*                                # trailing whitespace
+    (?:\#.*)?                          # optional inline comment
+    \s*\Z                              # end
+    """,
+    re.VERBOSE,
+)
+
+_INTERPOLATE_RE = re.compile(
+    r"""
+    (?<!\\)                            # not preceded by backslash
+    \$                                 # dollar sign
+    (?:
+      \{(?P<brace>[^}]*)\}            # ${VAR} or ${VAR:-default}
+    | (?P<name>[A-Za-z_]\w*)           # $VAR
+    )
+    """,
+    re.VERBOSE,
+)
+
+
+# ── Internal helpers ───────────────────────────────────────────────────────────
+
+
+def _unescape_double_quoted(s: str) -> str:
+    """Process escape sequences in a double-quoted value."""
+
+    def _replace(m: re.Match[str]) -> str:
+        ch = m.group(1)
+        return _ESCAPE_MAP.get(ch, "\\" + ch)
+
+    return re.sub(r"\\(.)", _replace, s)
+
+
+def _interpolate(
+    value: str,
+    env: dict[str, str | None],
+    os_environ: Mapping[str, str],
+) -> str:
+    """Expand $VAR and ${VAR} references in *value*.
+
+    Resolution order: file-local *env*, then *os_environ*, then empty string.
+    Supports ${VAR:-default} syntax.
+    """
+
+    def _replace(m: re.Match[str]) -> str:
+        brace = m.group("brace")
+        if brace is not None:
+            # Handle ${VAR:-default}
+            if ":-" in brace:
+                name, default = brace.split(":-", 1)
+                name = name.strip()
+                val = env.get(name) if name in env else os_environ.get(name)
+                return val if val is not None else default
+            name = brace.strip()
+        else:
+            name = m.group("name")
+        val = env.get(name) if name in env else os_environ.get(name)
+        return val if val is not None else ""
+
+    return _INTERPOLATE_RE.sub(_replace, value)
+
+
+def _find_unescaped_quote(text: str) -> int:
+    """Return position of the first unescaped double-quote in *text*, or -1."""
+    pos = 0
+    while pos < len(text):
+        if text[pos] == "\\" and pos + 1 < len(text):
+            pos += 2
+            continue
+        if text[pos] == '"':
+            return pos
+        pos += 1
+    return -1
+
+
+def _collect_multiline_value(
+    lines: list[str], start_idx: int, first_fragment: str
+) -> tuple[str, int]:
+    """Accumulate continuation lines for a multiline double-quoted value.
+
+    Args:
+        lines: All lines of the .env content.
+        start_idx: Index of the first continuation line to inspect.
+        first_fragment: Text after the opening ``"`` on the first line.
+
+    Returns:
+        Tuple of (raw concatenated value, next line index to process).
+    """
+    parts = [first_fragment]
+    i = start_idx
+    while i < len(lines):
+        next_line = lines[i]
+        i += 1
+        close_pos = _find_unescaped_quote(next_line)
+        if close_pos >= 0:
+            parts.append(next_line[:close_pos])
+            break
+        parts.append(next_line)
+    return "".join(parts), i
+
+
+_MULTILINE_OPEN_RE = re.compile(
+    r'\A\s*(?:export\s+)?([A-Za-z_]\w*)\s*=\s*"',
+)
+
+
+def _extract_value_from_match(m: re.Match[str]) -> str | None:
+    """Extract the value from a single-line binding regex match.
+
+    Returns the raw value (unescaped for double-quoted, literal for
+    single-quoted, stripped for unquoted, or None when no ``=`` present).
+    """
+    if m.group("sq") is not None:
+        return m.group("sq")
+    if m.group("dq") is not None:
+        return _unescape_double_quoted(m.group("dq"))
+    if m.group("uq") is not None:
+        return m.group("uq").rstrip()
+    return None
+
+
+def _parse_stream(
+    stream: IO[str],
+    interpolate: bool = True,
+    override: bool = False,
+    os_environ: Mapping[str, str] | None = None,
+) -> Iterator[tuple[str, str | None]]:
+    """Parse an .env stream, yielding (key, value) tuples."""
+    if os_environ is None:
+        os_environ = os.environ
+
+    env: dict[str, str | None] = {}
+    content = stream.read()
+
+    # Strip UTF-8 BOM
+    if content.startswith("\ufeff"):
+        content = content[1:]
+
+    lines = content.splitlines(keepends=True)
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+        i += 1
+
+        # Skip blank lines and comment-only lines
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        # Check for multiline double-quoted values
+        ml_match = _MULTILINE_OPEN_RE.match(line)
+        if ml_match:
+            after_eq_quote = line[ml_match.end() :]
+            if _find_unescaped_quote(after_eq_quote) < 0:
+                # Multiline: accumulate lines until closing "
+                key = ml_match.group(1)
+                raw_value, i = _collect_multiline_value(lines, i, after_eq_quote)
+                value = _unescape_double_quoted(raw_value)
+                if interpolate:
+                    value = _interpolate(value, env, os_environ)
+                env[key] = value
+                yield key, value
+                continue
+
+        # Single-line binding
+        m = _BINDING_RE.match(stripped)
+        if m is None:
+            continue
+
+        key = m.group("key")
+        value: str | None = _extract_value_from_match(m)
+
+        if value is not None and interpolate:
+            value = _interpolate(value, env, os_environ)
+
+        env[key] = value
+        yield key, value
+
+
+# ── File search ────────────────────────────────────────────────────────────────
+
+
+def find_dotenv(
+    filename: str = ".env",
+    raise_error_if_not_found: bool = False,
+    usecwd: bool = False,
+) -> str:
+    """Walk up from the calling file's directory (or cwd) to find *filename*.
+
+    Args:
+        filename: Name of the file to search for.
+        raise_error_if_not_found: Raise IOError if the file is not found.
+        usecwd: Start from the current working directory instead of the
+            calling file's directory.
+
+    Returns:
+        Absolute path to the found file, or empty string if not found.
+    """
+    if usecwd:
+        start = Path.cwd()
+    else:
+        frame = inspect.currentframe()
+        caller = frame.f_back if frame is not None else None
+        if caller is not None and caller.f_globals.get("__file__"):
+            start = Path(caller.f_globals["__file__"]).resolve().parent
+        else:
+            start = Path.cwd()
+
+    current = start
+    while True:
+        candidate = current / filename
+        if candidate.is_file():
+            return str(candidate)
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+
+    if raise_error_if_not_found:
+        raise IOError(f"File {filename!r} not found starting from {start}")
+    return ""
+
+
+# ── File I/O (set / unset) ────────────────────────────────────────────────────
+
+
+def get_key(
+    dotenv_path: str | os.PathLike[str],
+    key_to_get: str,
+    encoding: str = "utf-8",
+) -> str | None:
+    """Get a single value from a .env file.
+
+    Args:
+        dotenv_path: Path to the .env file.
+        key_to_get: The key to retrieve.
+        encoding: File encoding.
+
+    Returns:
+        The value for the key, or None if not found.
+    """
+    values = dotenv_values(dotenv_path, encoding=encoding)
+    return values.get(key_to_get)
+
+
+def set_key(
+    dotenv_path: str | os.PathLike[str],
+    key_to_set: str,
+    value_to_set: str,
+    quote_mode: str = "always",
+    export: bool = False,
+    encoding: str = "utf-8",
+) -> tuple[bool, str, str]:
+    """Set a key=value pair in a .env file, creating it if needed.
+
+    Args:
+        dotenv_path: Path to the .env file.
+        key_to_set: The key to set.
+        value_to_set: The value to set.
+        quote_mode: Quoting strategy: "always", "auto", or "never".
+        export: Whether to prefix with ``export``.
+        encoding: File encoding.
+
+    Returns:
+        Tuple of (success, key, value).
+    """
+    path = Path(dotenv_path)
+
+    if quote_mode == "always":
+        value_out = f'"{value_to_set}"'
+    elif quote_mode == "never":
+        value_out = value_to_set
+    else:
+        # auto: quote if value contains spaces or special chars
+        if re.search(r"[\s#\"']", value_to_set):
+            value_out = f'"{value_to_set}"'
+        else:
+            value_out = value_to_set
+
+    export_prefix = "export " if export else ""
+    new_line = f"{export_prefix}{key_to_set}={value_out}\n"
+
+    if path.is_file():
+        lines = path.read_text(encoding=encoding).splitlines(keepends=True)
+        replaced = False
+        for idx, line in enumerate(lines):
+            m = re.match(
+                r"\A\s*(?:export\s+)?(" + re.escape(key_to_set) + r")\s*=",
+                line,
+            )
+            if m:
+                lines[idx] = new_line
+                replaced = True
+                break
+        if not replaced:
+            if lines and not lines[-1].endswith("\n"):
+                lines[-1] += "\n"
+            lines.append(new_line)
+        path.write_text("".join(lines), encoding=encoding)
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(new_line, encoding=encoding)
+
+    return True, key_to_set, value_to_set
+
+
+def unset_key(
+    dotenv_path: str | os.PathLike[str],
+    key_to_unset: str,
+    quote_mode: str = "always",
+    encoding: str = "utf-8",
+) -> tuple[bool, str]:
+    """Remove a key from a .env file.
+
+    Args:
+        dotenv_path: Path to the .env file.
+        key_to_unset: The key to remove.
+        quote_mode: Unused, kept for API compatibility.
+        encoding: File encoding.
+
+    Returns:
+        Tuple of (success, key).
+    """
+    path = Path(dotenv_path)
+    if not path.is_file():
+        return True, key_to_unset
+
+    lines = path.read_text(encoding=encoding).splitlines(keepends=True)
+    new_lines = []
+    for line in lines:
+        m = re.match(
+            r"\A\s*(?:export\s+)?(" + re.escape(key_to_unset) + r")\s*=",
+            line,
+        )
+        if m:
+            continue
+        new_lines.append(line)
+
+    path.write_text("".join(new_lines), encoding=encoding)
+    return True, key_to_unset
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+
+def _resolve_dotenv_path(
+    dotenv_path: str | os.PathLike[str] | None,
+    verbose: bool,
+) -> Path | None:
+    """Resolve *dotenv_path* to an existing file, or return None.
+
+    When *verbose* is True and the file does not exist, a warning is printed.
+    """
+    if dotenv_path is None:
+        dotenv_path = find_dotenv(usecwd=True)
+
+    path = Path(dotenv_path)
+    if path.is_file():
+        return path
+
+    if verbose:
+        print(  # noqa: T201
+            f"Python-dotenv could not find configuration file {path}.",
+            file=sys.stderr,
+        )
+    return None
+
+
+def _apply_to_environ(
+    pairs: Iterator[tuple[str, str | None]],
+    override: bool,
+) -> None:
+    """Write parsed (key, value) pairs into ``os.environ``."""
+    for key, value in pairs:
+        if value is not None and (override or key not in os.environ):
+            os.environ[key] = value
+
+
+def dotenv_values(
+    dotenv_path: str | os.PathLike[str] | None = None,
+    stream: IO[str] | None = None,
+    verbose: bool = False,
+    interpolate: bool = True,
+    override: bool = False,
+    encoding: str = "utf-8",
+) -> dict[str, str | None]:
+    """Parse a .env file and return a dict without modifying ``os.environ``.
+
+    Args:
+        dotenv_path: Path to the .env file. If None, uses ``find_dotenv()``.
+        stream: A text stream to read from (overrides *dotenv_path*).
+        verbose: Print a warning when the file is missing.
+        interpolate: Expand ``$VAR`` and ``${VAR}`` references.
+        override: Unused for dotenv_values (kept for API compatibility).
+        encoding: File encoding.
+
+    Returns:
+        Dictionary mapping variable names to their values.
+    """
+    if stream is not None:
+        return dict(_parse_stream(stream, interpolate=interpolate))
+
+    path = _resolve_dotenv_path(dotenv_path, verbose)
+    if path is None:
+        return {}
+
+    with open(path, encoding=encoding) as f:
+        return dict(_parse_stream(f, interpolate=interpolate))
+
+
+def load_dotenv(
+    dotenv_path: str | os.PathLike[str] | None = None,
+    stream: IO[str] | None = None,
+    verbose: bool = False,
+    interpolate: bool = True,
+    override: bool = False,
+    encoding: str = "utf-8",
+) -> bool:
+    """Read a .env file and set ``os.environ``.
+
+    Args:
+        dotenv_path: Path to the .env file. If None, uses ``find_dotenv()``.
+        stream: A text stream to read from (overrides *dotenv_path*).
+        verbose: Print a warning when the file is missing.
+        interpolate: Expand ``$VAR`` and ``${VAR}`` references.
+        override: If True, overwrite existing environment variables.
+        encoding: File encoding.
+
+    Returns:
+        True if a file was found and loaded.
+    """
+    if stream is not None:
+        _apply_to_environ(_parse_stream(stream, interpolate=interpolate), override)
+        return True
+
+    path = _resolve_dotenv_path(dotenv_path, verbose)
+    if path is None:
+        return False
+
+    with open(path, encoding=encoding) as f:
+        _apply_to_environ(_parse_stream(f, interpolate=interpolate), override)
+    return True

src/veilrender/_vendor/httpserver.py

@@ -0,0 +1,1007 @@
+# /// zerodep
+# version = "0.1.0"
+# deps = []
+# tier = "subsystem"
+# category = "network"
+# note = "Install/update via `zerodep add httpserver`"
+# ///
+
+"""Zero-dependency async HTTP server with decorator-based routing.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Async HTTP/1.1 server built on ``asyncio.start_server()``.  Supports
+decorator-based routing, JSON request/response, static file serving,
+streaming responses (SSE), and graceful shutdown.
+
+Usage::
+
+    from httpserver import App, JSONResponse
+
+    app = App()
+
+    @app.route("/status")
+    async def status(request):
+        return JSONResponse({"state": "idle"})
+
+    @app.route("/echo", methods=["POST"])
+    def echo(request):
+        return JSONResponse(request.json())
+
+    app.run(host="127.0.0.1", port=8000)
+"""
+
+# ── Imports ──────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import inspect
+import json as _json
+import logging
+import mimetypes
+import os
+import re
+import signal
+import sys
+from collections.abc import AsyncIterator, Callable
+from email.utils import formatdate
+from pathlib import Path
+from typing import Any
+from urllib.parse import parse_qs, unquote, urlparse
+
+__all__ = [
+    # Application
+    "App",
+    # Request / Response
+    "Request",
+    "Response",
+    "JSONResponse",
+    "StreamingResponse",
+    "FileResponse",
+    # Exceptions
+    "HTTPException",
+    # Utilities
+    "abort",
+]
+
+logger = logging.getLogger(__name__)
+
+# ── Constants ────────────────────────────────────────────────────────────────
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+DEFAULT_MAX_BODY_SIZE = 1_048_576  # 1 MB
+DEFAULT_READ_TIMEOUT = 30.0  # seconds
+
+_STATUS_REASONS: dict[int, str] = {
+    100: "Continue",
+    101: "Switching Protocols",
+    200: "OK",
+    201: "Created",
+    202: "Accepted",
+    204: "No Content",
+    301: "Moved Permanently",
+    302: "Found",
+    303: "See Other",
+    304: "Not Modified",
+    307: "Temporary Redirect",
+    308: "Permanent Redirect",
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    406: "Not Acceptable",
+    408: "Request Timeout",
+    409: "Conflict",
+    413: "Content Too Large",
+    415: "Unsupported Media Type",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout",
+}
+
+# Type converters for path parameters
+_PARAM_CONVERTERS: dict[str, tuple[str, Callable[[str], Any]]] = {
+    "str": (r"([^/]+)", str),
+    "int": (r"(-?\d+)", int),
+    "float": (r"(-?[0-9]+(?:\.[0-9]+)?)", float),
+    "path": (r"(.+)", str),
+}
+
+# Regex to find <type:name> or <name> segments in route patterns
+_PARAM_RE = re.compile(r"<(?:(\w+):)?(\w+)>")
+
+_SENTINEL = object()
+
+
+# ── Exceptions ───────────────────────────────────────────────────────────────
+
+
+class HTTPException(Exception):
+    """HTTP error that maps to a specific status code.
+
+    Raise directly or via :func:`abort` to short-circuit request handling.
+
+    Args:
+        status_code: HTTP status code (e.g. 404, 500).
+        message: Optional human-readable error message.
+    """
+
+    __slots__ = ("status_code", "message")
+
+    def __init__(self, status_code: int, message: str | None = None):
+        self.status_code = status_code
+        self.message = message or _STATUS_REASONS.get(status_code, "Error")
+        super().__init__(self.message)
+
+
+class _BadRequest(Exception):
+    """Internal: malformed HTTP request from client."""
+
+
+def abort(status_code: int, message: str | None = None) -> None:
+    """Raise an :class:`HTTPException` with the given status code.
+
+    Args:
+        status_code: HTTP status code.
+        message: Optional error message.
+    """
+    raise HTTPException(status_code, message)
+
+
+# ── Request ──────────────────────────────────────────────────────────────────
+
+
+class Request:
+    """Parsed HTTP request.
+
+    Attributes:
+        method: Uppercase HTTP method (GET, POST, ...).
+        path: URL path, percent-decoded.
+        query_string: Raw query string (without leading ``?``).
+        query_params: Parsed query string as ``{key: [values]}``.
+        headers: Case-insensitive header dict (keys stored lowercase).
+        body: Raw request body bytes.
+        path_params: Parameters extracted from the route pattern.
+        client_addr: Client ``(host, port)`` tuple.
+        app: Reference to the :class:`App` instance handling this request.
+    """
+
+    __slots__ = (
+        "method",
+        "path",
+        "query_string",
+        "query_params",
+        "headers",
+        "body",
+        "path_params",
+        "client_addr",
+        "app",
+        "_json",
+    )
+
+    def __init__(
+        self,
+        method: str,
+        path: str,
+        query_string: str,
+        headers: dict[str, str],
+        body: bytes,
+        client_addr: tuple[str, int],
+        app: App | None = None,
+    ):
+        self.method = method
+        self.path = path
+        self.query_string = query_string
+        self.query_params: dict[str, list[str]] = parse_qs(query_string)
+        self.headers = headers
+        self.body = body
+        self.path_params: dict[str, Any] = {}
+        self.client_addr = client_addr
+        self.app = app
+        self._json: Any = _SENTINEL
+
+    def json(self) -> Any:
+        """Parse body as JSON (cached)."""
+        if self._json is _SENTINEL:
+            self._json = _json.loads(self.body)
+        return self._json
+
+    def text(self) -> str:
+        """Decode body as UTF-8."""
+        return self.body.decode("utf-8")
+
+    def form(self) -> dict[str, list[str]]:
+        """Parse URL-encoded form body."""
+        return parse_qs(self.body.decode("utf-8"))
+
+
+# ── Response Classes ─────────────────────────────────────────────────────────
+
+
+class Response:
+    """HTTP response with a fixed body.
+
+    Args:
+        body: Response body (bytes or str).
+        status_code: HTTP status code.
+        headers: Extra response headers.
+        content_type: Shorthand for ``Content-Type`` header.
+    """
+
+    __slots__ = ("status_code", "headers", "body")
+
+    def __init__(
+        self,
+        body: bytes | str = b"",
+        status_code: int = 200,
+        headers: dict[str, str] | None = None,
+        content_type: str | None = None,
+    ):
+        self.status_code = status_code
+        self.headers: dict[str, str] = headers.copy() if headers else {}
+        if isinstance(body, str):
+            self.body = body.encode("utf-8")
+        else:
+            self.body = body
+        if content_type is not None:
+            self.headers["Content-Type"] = content_type
+
+    async def _write(self, writer: asyncio.StreamWriter) -> None:
+        """Serialize and write the full HTTP response."""
+        reason = _STATUS_REASONS.get(self.status_code, "Unknown")
+        self.headers.setdefault("Content-Length", str(len(self.body)))
+        self.headers.setdefault("Content-Type", "text/plain; charset=utf-8")
+        self.headers.setdefault("Date", _http_date())
+        self.headers.setdefault("Connection", "close")
+
+        buf = bytearray()
+        buf.extend(f"HTTP/1.1 {self.status_code} {reason}\r\n".encode("latin-1"))
+        for k, v in self.headers.items():
+            buf.extend(f"{k}: {v}\r\n".encode("latin-1"))
+        buf.extend(b"\r\n")
+        buf.extend(self.body)
+        writer.write(bytes(buf))
+        await writer.drain()
+
+
+class JSONResponse(Response):
+    """Response serialized as JSON.
+
+    Args:
+        data: Python object to serialize.
+        status_code: HTTP status code.
+        headers: Extra response headers.
+    """
+
+    def __init__(
+        self,
+        data: Any,
+        status_code: int = 200,
+        headers: dict[str, str] | None = None,
+    ):
+        body = _json.dumps(data, ensure_ascii=False).encode("utf-8")
+        super().__init__(
+            body=body,
+            status_code=status_code,
+            headers=headers,
+            content_type="application/json; charset=utf-8",
+        )
+
+
+class StreamingResponse:
+    """HTTP response streamed from an async generator.
+
+    Writes chunks using ``Transfer-Encoding: chunked`` unless
+    ``content_type`` is ``text/event-stream`` (SSE), in which case raw
+    bytes are flushed directly for maximum compatibility with SSE clients.
+
+    Args:
+        generator: Async iterator yielding ``bytes`` or ``str`` chunks.
+        status_code: HTTP status code.
+        headers: Extra response headers.
+        content_type: MIME type (default ``application/octet-stream``).
+    """
+
+    __slots__ = ("_generator", "status_code", "headers", "content_type")
+
+    def __init__(
+        self,
+        generator: AsyncIterator[bytes | str],
+        status_code: int = 200,
+        headers: dict[str, str] | None = None,
+        content_type: str = "application/octet-stream",
+    ):
+        self._generator = generator
+        self.status_code = status_code
+        self.headers: dict[str, str] = headers.copy() if headers else {}
+        self.content_type = content_type
+
+    async def _write(self, writer: asyncio.StreamWriter) -> None:
+        """Write status line, headers, then stream the body."""
+        reason = _STATUS_REASONS.get(self.status_code, "Unknown")
+        is_sse = self.content_type.startswith("text/event-stream")
+
+        self.headers["Content-Type"] = self.content_type
+        if not is_sse:
+            self.headers.setdefault("Transfer-Encoding", "chunked")
+        else:
+            self.headers.setdefault("Cache-Control", "no-cache")
+        self.headers.setdefault("Date", _http_date())
+        self.headers.setdefault("Connection", "close")
+
+        buf = bytearray()
+        buf.extend(f"HTTP/1.1 {self.status_code} {reason}\r\n".encode("latin-1"))
+        for k, v in self.headers.items():
+            buf.extend(f"{k}: {v}\r\n".encode("latin-1"))
+        buf.extend(b"\r\n")
+        writer.write(bytes(buf))
+        await writer.drain()
+
+        try:
+            async for chunk in self._generator:
+                if isinstance(chunk, str):
+                    chunk = chunk.encode("utf-8")
+                if is_sse:
+                    writer.write(chunk)
+                else:
+                    writer.write(f"{len(chunk):x}\r\n".encode("latin-1"))
+                    writer.write(chunk)
+                    writer.write(b"\r\n")
+                await writer.drain()
+            if not is_sse:
+                writer.write(b"0\r\n\r\n")
+                await writer.drain()
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
+            logger.debug("Client disconnected during streaming")
+        finally:
+            aclose = getattr(self._generator, "aclose", None)
+            if aclose is not None:
+                await aclose()
+
+
+class FileResponse(Response):
+    """Response serving a file from disk.
+
+    Args:
+        path: Path to the file.
+        content_type: MIME type (auto-detected from extension if ``None``).
+        status_code: HTTP status code.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        content_type: str | None = None,
+        status_code: int = 200,
+    ):
+        file_path = Path(path)
+        body = file_path.read_bytes()
+        if content_type is None:
+            guessed, _ = mimetypes.guess_type(str(file_path))
+            content_type = guessed or "application/octet-stream"
+        headers = {
+            "Last-Modified": _http_date(os.path.getmtime(file_path)),
+        }
+        super().__init__(
+            body=body,
+            status_code=status_code,
+            headers=headers,
+            content_type=content_type,
+        )
+
+
+# ── Routing ──────────────────────────────────────────────────────────────────
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class _Route:
+    """Internal route entry."""
+
+    methods: list[str]  # uppercase, e.g. ["GET", "POST"], or ["*"]
+    pattern: re.Pattern[str]
+    handler: Callable[..., Any]
+    is_async: bool
+    param_names: list[str]
+    param_converters: list[Callable[[str], Any]]
+
+
+def _compile_route(
+    path: str,
+) -> tuple[re.Pattern[str], list[str], list[Callable[[str], Any]]]:
+    """Compile a path pattern into a regex and parameter metadata.
+
+    Supports ``<name>``, ``<int:name>``, ``<float:name>``, ``<path:name>``.
+
+    Args:
+        path: URL path pattern (e.g. ``/users/<int:id>``).
+
+    Returns:
+        Tuple of (compiled regex, param names, param converters).
+    """
+    param_names: list[str] = []
+    param_converters: list[Callable[[str], Any]] = []
+    regex_parts: list[str] = []
+    last_end = 0
+
+    for m in _PARAM_RE.finditer(path):
+        regex_parts.append(re.escape(path[last_end : m.start()]))
+        type_name = m.group(1) or "str"
+        name = m.group(2)
+        if type_name not in _PARAM_CONVERTERS:
+            raise ValueError(f"Unknown path parameter type: {type_name!r}")
+        regex_fragment, converter = _PARAM_CONVERTERS[type_name]
+        regex_parts.append(regex_fragment)
+        param_names.append(name)
+        param_converters.append(converter)
+        last_end = m.end()
+
+    regex_parts.append(re.escape(path[last_end:]))
+    full_regex = "^" + "".join(regex_parts) + "$"
+    return re.compile(full_regex), param_names, param_converters
+
+
+# ── HTTP Parsing ─────────────────────────────────────────────────────────────
+
+
+async def _read_request(
+    reader: asyncio.StreamReader,
+    timeout: float,
+    max_body_size: int,
+) -> tuple[str, str, str, dict[str, str], bytes]:
+    """Read and parse an HTTP request from a stream.
+
+    Returns:
+        Tuple of (method, path, query_string, headers, body).
+
+    Raises:
+        _BadRequest: If the request is malformed.
+        asyncio.TimeoutError: If reading times out.
+    """
+    # -- Request line --
+    raw_line = await asyncio.wait_for(reader.readline(), timeout=timeout)
+    if not raw_line:
+        raise _BadRequest("Empty request")
+    request_line = raw_line.decode("latin-1").rstrip("\r\n")
+    parts = request_line.split(" ", 2)
+    if len(parts) != 3:
+        raise _BadRequest(f"Malformed request line: {request_line!r}")
+    method, raw_url, _version = parts
+
+    # -- URL --
+    parsed = urlparse(raw_url)
+    path = unquote(parsed.path)
+    query_string = parsed.query
+
+    # -- Headers --
+    headers: dict[str, str] = {}
+    while True:
+        line = await asyncio.wait_for(reader.readline(), timeout=timeout)
+        decoded = line.decode("latin-1").rstrip("\r\n")
+        if not decoded:
+            break
+        if ":" in decoded:
+            k, v = decoded.split(":", 1)
+            headers[k.strip().lower()] = v.strip()
+
+    # -- Body --
+    body = b""
+    cl = headers.get("content-length")
+    if cl is not None:
+        length = int(cl)
+        if length > max_body_size:
+            raise HTTPException(413, f"Request body too large ({length} bytes)")
+        if length > 0:
+            body = await asyncio.wait_for(reader.readexactly(length), timeout=timeout)
+    elif headers.get("transfer-encoding", "").lower() == "chunked":
+        body = await _read_chunked_body(reader, timeout, max_body_size)
+
+    return method.upper(), path, query_string, headers, body
+
+
+async def _read_chunked_body(
+    reader: asyncio.StreamReader,
+    timeout: float,
+    max_body_size: int,
+) -> bytes:
+    """Read a chunked transfer-encoded body."""
+    parts: list[bytes] = []
+    total = 0
+    while True:
+        size_line = await asyncio.wait_for(reader.readline(), timeout=timeout)
+        size_str = size_line.decode("latin-1").split(";")[0].strip()
+        if not size_str:
+            break
+        chunk_size = int(size_str, 16)
+        if chunk_size == 0:
+            await asyncio.wait_for(reader.readline(), timeout=timeout)
+            break
+        total += chunk_size
+        if total > max_body_size:
+            raise HTTPException(413, "Request body too large")
+        data = await asyncio.wait_for(reader.readexactly(chunk_size), timeout=timeout)
+        await asyncio.wait_for(reader.readline(), timeout=timeout)
+        parts.append(data)
+    return b"".join(parts)
+
+
+# ── Utilities ────────────────────────────────────────────────────────────────
+
+
+def _http_date(timestamp: float | None = None) -> str:
+    """Format a timestamp as an HTTP-date (RFC 7231)."""
+    return formatdate(timeval=timestamp, localtime=False, usegmt=True)
+
+
+def _coerce_response(result: Any) -> Response | StreamingResponse:
+    """Convert a handler return value into a Response object."""
+    if isinstance(result, (Response, StreamingResponse)):
+        return result
+
+    if result is None:
+        return Response(status_code=204)
+
+    if isinstance(result, dict):
+        return JSONResponse(result)
+
+    if isinstance(result, tuple):
+        if len(result) == 2:
+            body, status = result
+            resp = _coerce_response(body)
+            resp.status_code = status
+            return resp
+        if len(result) == 3:
+            body, status, extra_headers = result
+            resp = _coerce_response(body)
+            resp.status_code = status
+            resp.headers.update(extra_headers)
+            return resp
+        raise ValueError(f"Unsupported tuple length: {len(result)}")
+
+    if isinstance(result, bytes):
+        return Response(body=result, content_type="application/octet-stream")
+
+    if isinstance(result, str):
+        return Response(body=result, content_type="text/plain; charset=utf-8")
+
+    raise TypeError(
+        f"Cannot coerce handler return type {type(result).__name__} to Response"
+    )
+
+
+# ── Static File Resolution ───────────────────────────────────────────────────
+
+
+def _resolve_static_file(
+    request_path: str,
+    url_prefix: str,
+    directory: str,
+) -> FileResponse | None:
+    """Try to resolve a static file request.
+
+    Returns a FileResponse if the file exists and the path is safe,
+    otherwise None.
+    """
+    if not request_path.startswith(url_prefix):
+        return None
+
+    relative = request_path[len(url_prefix) :].lstrip("/")
+    if not relative:
+        return None
+
+    base = Path(directory).resolve()
+    target = (base / relative).resolve()
+
+    # Prevent directory traversal
+    if not str(target).startswith(str(base)):
+        return None
+
+    if not target.is_file():
+        return None
+
+    return FileResponse(target)
+
+
+# ── App ──────────────────────────────────────────────────────────────────────
+
+
+class App:
+    """Async HTTP server application.
+
+    Args:
+        max_body_size: Maximum request body size in bytes.
+        read_timeout: Timeout for reading a single request (seconds).
+
+    Example::
+
+        app = App()
+
+        @app.get("/hello")
+        async def hello(request):
+            return {"message": "Hello, world!"}
+
+        app.run()
+    """
+
+    def __init__(
+        self,
+        *,
+        max_body_size: int = DEFAULT_MAX_BODY_SIZE,
+        read_timeout: float = DEFAULT_READ_TIMEOUT,
+    ):
+        self._routes: list[_Route] = []
+        self._static_routes: list[tuple[str, str]] = []
+        self._before_request_handlers: list[Callable[..., Any]] = []
+        self._after_request_handlers: list[Callable[..., Any]] = []
+        self._error_handlers: dict[int | type, Callable[..., Any]] = {}
+        self._server: asyncio.Server | None = None
+        self._shutdown_event: asyncio.Event | None = None
+        self.max_body_size = max_body_size
+        self.read_timeout = read_timeout
+        self.port: int | None = None
+        self.host: str | None = None
+
+    # ── Route Registration ───────────────────────────────────────────────
+
+    def route(
+        self, url_pattern: str, methods: list[str] | None = None
+    ) -> Callable[..., Any]:
+        """Register a route handler.
+
+        Args:
+            url_pattern: URL pattern with optional parameters.
+            methods: HTTP methods to handle (e.g. ``["GET", "POST"]``).
+                Defaults to ``["GET"]``.
+
+        Example::
+
+            @app.route("/users/<int:id>", methods=["GET", "POST"])
+            async def user(request, id):
+                return {"id": id}
+        """
+        if methods is None:
+            methods = ["GET"]
+
+        def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
+            pattern, param_names, converters = _compile_route(url_pattern)
+            is_async = inspect.iscoroutinefunction(handler)
+            self._routes.append(
+                _Route(
+                    methods=[m.upper() for m in methods],
+                    pattern=pattern,
+                    handler=handler,
+                    is_async=is_async,
+                    param_names=param_names,
+                    param_converters=converters,
+                )
+            )
+            return handler
+
+        return decorator
+
+    def get(self, path: str) -> Callable[..., Any]:
+        """Shorthand for ``@app.route(path, methods=["GET"])``."""
+        return self.route(path, methods=["GET"])
+
+    def post(self, path: str) -> Callable[..., Any]:
+        """Shorthand for ``@app.route(path, methods=["POST"])``."""
+        return self.route(path, methods=["POST"])
+
+    def put(self, path: str) -> Callable[..., Any]:
+        """Shorthand for ``@app.route(path, methods=["PUT"])``."""
+        return self.route(path, methods=["PUT"])
+
+    def delete(self, path: str) -> Callable[..., Any]:
+        """Shorthand for ``@app.route(path, methods=["DELETE"])``."""
+        return self.route(path, methods=["DELETE"])
+
+    def patch(self, path: str) -> Callable[..., Any]:
+        """Shorthand for ``@app.route(path, methods=["PATCH"])``."""
+        return self.route(path, methods=["PATCH"])
+
+    def static(self, url_prefix: str, directory: str) -> None:
+        """Register a directory for static file serving.
+
+        Args:
+            url_prefix: URL prefix (e.g. ``"/static"``).
+            directory: Filesystem path to the directory.
+
+        Example::
+
+            app.static("/assets", "./public")
+        """
+        url_prefix = url_prefix.rstrip("/")
+        abs_dir = os.path.abspath(directory)
+        self._static_routes.append((url_prefix, abs_dir))
+
+    # ── Middleware ────────────────────────────────────────────────────────
+
+    def before_request(self, handler: Callable[..., Any]) -> Callable[..., Any]:
+        """Register a before-request hook.
+
+        The hook receives ``(request)`` and may return a ``Response`` to
+        short-circuit the route handler.
+        """
+        self._before_request_handlers.append(handler)
+        return handler
+
+    def after_request(self, handler: Callable[..., Any]) -> Callable[..., Any]:
+        """Register an after-request hook.
+
+        The hook receives ``(request, response)`` and may return a new
+        or modified ``Response``.
+        """
+        self._after_request_handlers.append(handler)
+        return handler
+
+    def errorhandler(self, code_or_exc: int | type) -> Callable[..., Any]:
+        """Register an error handler.
+
+        Args:
+            code_or_exc: HTTP status code (int) or exception class.
+
+        The handler receives ``(request, exception)`` and must return a
+        ``Response``.
+        """
+
+        def decorator(handler: Callable[..., Any]) -> Callable[..., Any]:
+            self._error_handlers[code_or_exc] = handler
+            return handler
+
+        return decorator
+
+    # ── Request Dispatch ─────────────────────────────────────────────────
+
+    def _match_route(
+        self, request: Request
+    ) -> tuple[_Route | None, re.Match[str] | None, bool]:
+        """Find the first route matching the request path and method.
+
+        Returns:
+            (matched_route, regex_match, path_existed).  *path_existed* is
+            True when a route matched the path but not the HTTP method.
+        """
+        path_existed = False
+        for route in self._routes:
+            m = route.pattern.match(request.path)
+            if m is None:
+                continue
+            path_existed = True
+            if "*" not in route.methods and request.method not in route.methods:
+                continue
+            return route, m, True
+        return None, None, path_existed
+
+    async def _invoke_route(
+        self, route: _Route, match: re.Match[str], request: Request
+    ) -> Response | StreamingResponse:
+        """Extract path params, call the handler, return a response."""
+        for name, converter, value in zip(
+            route.param_names, route.param_converters, match.groups()
+        ):
+            request.path_params[name] = converter(value)
+
+        try:
+            result = await _invoke(route.handler, request, **request.path_params)
+            return _coerce_response(result)
+        except HTTPException as exc:
+            return await self._handle_error(request, exc)
+        except Exception as exc:
+            logger.exception(
+                "Unhandled exception in handler %s",
+                getattr(route.handler, "__name__", repr(route.handler)),
+            )
+            return await self._handle_error(request, exc)
+
+    async def _run_after_hooks(
+        self, request: Request, response: Response | StreamingResponse
+    ) -> Response | StreamingResponse:
+        """Run after-request hooks, allowing them to replace the response."""
+        for hook in self._after_request_handlers:
+            hook_result = await _invoke(hook, request, response)
+            if hook_result is not None:
+                response = _coerce_response(hook_result)
+        return response
+
+    async def _dispatch(self, request: Request) -> Response | StreamingResponse:
+        """Match a request to a route and invoke the handler."""
+        # -- before_request hooks --
+        for hook in self._before_request_handlers:
+            result = await _invoke(hook, request)
+            if result is not None:
+                return _coerce_response(result)
+
+        # -- Static file check --
+        for prefix, directory in self._static_routes:
+            file_resp = _resolve_static_file(request.path, prefix, directory)
+            if file_resp is not None:
+                return file_resp
+
+        # -- Route matching --
+        route, match, path_existed = self._match_route(request)
+
+        if route is not None and match is not None:
+            response = await self._invoke_route(route, match, request)
+            return await self._run_after_hooks(request, response)
+
+        # -- No route matched --
+        if path_existed:
+            allowed = sorted(
+                {
+                    m
+                    for r in self._routes
+                    if r.pattern.match(request.path)
+                    for m in r.methods
+                    if m != "*"
+                }
+            )
+            exc = HTTPException(405, "Method Not Allowed")
+            response = await self._handle_error(request, exc)
+            if isinstance(response, Response):
+                response.headers["Allow"] = ", ".join(allowed)
+            return response
+
+        exc = HTTPException(404, "Not Found")
+        return await self._handle_error(request, exc)
+
+    async def _handle_error(
+        self, request: Request, exc: Exception
+    ) -> Response | StreamingResponse:
+        """Resolve an error into a response, consulting registered handlers."""
+        if isinstance(exc, HTTPException):
+            handler = self._error_handlers.get(exc.status_code)
+            if handler is not None:
+                result = await _invoke(handler, request, exc)
+                return _coerce_response(result)
+
+        for exc_cls, handler in self._error_handlers.items():
+            if isinstance(exc_cls, type) and isinstance(exc, exc_cls):
+                result = await _invoke(handler, request, exc)
+                return _coerce_response(result)
+
+        if isinstance(exc, HTTPException):
+            return JSONResponse(
+                {"error": exc.message},
+                status_code=exc.status_code,
+            )
+        return JSONResponse(
+            {"error": "Internal Server Error"},
+            status_code=500,
+        )
+
+    # ── Connection Handling ─────────��─────────────────────────────────────
+
+    async def _handle_connection(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+    ) -> None:
+        """Handle a single client connection."""
+        peer = writer.get_extra_info("peername")
+        client_addr = (peer[0], peer[1]) if peer else ("unknown", 0)
+
+        try:
+            method, path, qs, headers, body = await _read_request(
+                reader, self.read_timeout, self.max_body_size
+            )
+        except _BadRequest as exc:
+            logger.debug("Bad request from %s: %s", client_addr, exc)
+            response = Response(
+                body=str(exc),
+                status_code=400,
+                content_type="text/plain; charset=utf-8",
+            )
+            try:
+                await response._write(writer)
+            except (BrokenPipeError, ConnectionResetError):
+                pass
+            writer.close()
+            return
+        except HTTPException as exc:
+            response = JSONResponse({"error": exc.message}, status_code=exc.status_code)
+            try:
+                await response._write(writer)
+            except (BrokenPipeError, ConnectionResetError):
+                pass
+            writer.close()
+            return
+        except (asyncio.TimeoutError, asyncio.IncompleteReadError):
+            writer.close()
+            return
+        except Exception:
+            writer.close()
+            return
+
+        request = Request(
+            method=method,
+            path=path,
+            query_string=qs,
+            headers=headers,
+            body=body,
+            client_addr=client_addr,
+            app=self,
+        )
+
+        logger.debug("%s %s from %s", method, path, client_addr)
+
+        try:
+            response = await self._dispatch(request)
+            await response._write(writer)
+        except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
+            logger.debug("Connection reset by %s during response", client_addr)
+        except Exception:
+            logger.exception("Error writing response to %s", client_addr)
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    # ── Server Lifecycle ─────────────────────────────────────────────────
+
+    def run(
+        self,
+        host: str = DEFAULT_HOST,
+        port: int = DEFAULT_PORT,
+    ) -> None:
+        """Start the server (blocking).
+
+        Args:
+            host: Bind address.
+            port: Bind port. Use ``0`` for OS-assigned port.
+        """
+        try:
+            asyncio.run(self._serve(host, port))
+        except KeyboardInterrupt:
+            pass
+
+    async def _serve(self, host: str, port: int) -> None:
+        """Internal async server loop."""
+        self._shutdown_event = asyncio.Event()
+
+        server = await asyncio.start_server(
+            self._handle_connection,
+            host,
+            port,
+        )
+
+        self._server = server
+        addrs = server.sockets[0].getsockname() if server.sockets else (host, port)
+        self.host = addrs[0]
+        self.port = addrs[1]
+        logger.info("Serving on %s:%d", self.host, self.port)
+
+        loop = asyncio.get_running_loop()
+        if sys.platform != "win32":
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, self._shutdown_event.set)
+
+        async with server:
+            await self._shutdown_event.wait()
+            logger.info("Shutting down server")
+
+    def shutdown(self) -> None:
+        """Request a graceful server shutdown.
+
+        Safe to call from a request handler.
+        """
+        if self._shutdown_event is not None:
+            self._shutdown_event.set()
+
+
+# ── Handler Invocation ───────────────────────────────────────────────────────
+
+
+async def _invoke(handler: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+    """Invoke a handler, wrapping sync functions with ``asyncio.to_thread``."""
+    if inspect.iscoroutinefunction(handler):
+        return await handler(*args, **kwargs)
+    return await asyncio.to_thread(handler, *args, **kwargs)

src/veilrender/_vendor/jsonc.py

@@ -0,0 +1,352 @@
+# /// zerodep
+# version = "0.3.0"
+# deps = []
+# tier = "simple"
+# category = "serialization"
+# note = "Install/update via `zerodep add jsonc`"
+# ///
+
+"""JSONC (JSON with Comments) parser — zero dependencies, stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Drop-in replacement for commentjson / stdlib json with JSONC support.
+
+Supports:
+    - Single-line comments: ``//`` and ``#``
+    - Block comments: ``/* ... */``
+    - Trailing commas in objects and arrays
+    - All standard JSON types
+
+Example::
+
+    loads('{"a": 1, // comment\n"b": 2}')
+    # {'a': 1, 'b': 2}
+    load(open("config.jsonc"))
+    # {...}
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import IO, Any
+
+__all__ = [
+    "JSONCDecodeError",
+    "loads",
+    "load",
+    "dumps",
+    "dump",
+]
+
+# ── Comment stripping ─────────────────────────────────────────────────────────
+
+# Matches (in priority order):
+#   1. Double-quoted strings (group 1) — preserved as-is
+#   2. Single-line // comments — removed
+#   3. Single-line # comments — removed
+#   4. Block /* ... */ comments — removed
+_COMMENT_RE = re.compile(
+    r"""
+    ( "(?:[^"\\]|\\.)*" )   # group 1: double-quoted string (keep)
+    | //[^\n]*              # single-line // comment
+    | \#[^\n]*              # single-line # comment
+    | /\*[\s\S]*?\*/        # block /* */ comment
+    """,
+    re.VERBOSE | re.MULTILINE,
+)
+
+# Trailing comma before closing ] or }
+_TRAILING_COMMA_RE = re.compile(
+    r"""
+    ( "(?:[^"\\]|\\.)*" )   # group 1: double-quoted string (keep)
+    | ,\s*(?=[}\]])         # comma followed by optional whitespace then } or ]
+    """,
+    re.VERBOSE,
+)
+
+
+def _strip_comments(text: str) -> str:
+    """Remove ``//``, ``#``, and ``/* */`` comments, preserving strings."""
+
+    def _replace(m: re.Match[str]) -> str:
+        if m.group(1) is not None:
+            return m.group(1)
+        return ""
+
+    return _COMMENT_RE.sub(_replace, text)
+
+
+def _strip_trailing_commas(text: str) -> str:
+    """Remove trailing commas before ``}`` and ``]``, preserving strings."""
+
+    def _replace(m: re.Match[str]) -> str:
+        if m.group(1) is not None:
+            return m.group(1)
+        return ""
+
+    return _TRAILING_COMMA_RE.sub(_replace, text)
+
+
+def _preprocess(text: str) -> str:
+    """Strip comments and trailing commas from JSONC text."""
+    text = _strip_comments(text)
+    text = _strip_trailing_commas(text)
+    return text
+
+
+# ── Line-number error mapping ────────────────────────────────────────────────
+
+
+def _remap_error_position(
+    original: str, cleaned: str, clean_pos: int
+) -> tuple[int, int]:
+    """Map a character offset in *cleaned* text back to *original* line/col.
+
+    Returns (line, column), both 1-based.
+    """
+    # Build a mapping from cleaned-offset → original-offset by replaying the
+    # comment-stripping regex.  Each matched region in the original either maps
+    # 1:1 (strings) or collapses to zero length (comments).
+    orig_idx = 0
+    clean_idx = 0
+    mapping: list[tuple[int, int, int]] = []  # (clean_start, clean_end, orig_start)
+
+    for m in _COMMENT_RE.finditer(original):
+        # Characters before this match map 1:1
+        pre_len = m.start() - orig_idx
+        if pre_len > 0:
+            mapping.append((clean_idx, clean_idx + pre_len, orig_idx))
+            clean_idx += pre_len
+        orig_idx = m.start()
+
+        if m.group(1) is not None:
+            # Preserved string — maps 1:1
+            span_len = m.end() - m.start()
+            mapping.append((clean_idx, clean_idx + span_len, orig_idx))
+            clean_idx += span_len
+        # else: comment — removed, clean_idx doesn't advance
+
+        orig_idx = m.end()
+
+    # Tail after last match
+    tail_len = len(original) - orig_idx
+    if tail_len > 0:
+        mapping.append((clean_idx, clean_idx + tail_len, orig_idx))
+
+    # Look up clean_pos in the mapping
+    orig_offset = clean_pos  # fallback
+    for cs, ce, os_ in mapping:
+        if cs <= clean_pos < ce:
+            orig_offset = os_ + (clean_pos - cs)
+            break
+        if clean_pos < cs:
+            orig_offset = os_
+            break
+
+    # Convert original offset to line/col
+    line = original[:orig_offset].count("\n") + 1
+    last_nl = original.rfind("\n", 0, orig_offset)
+    col = orig_offset - last_nl  # 1-based
+    return line, col
+
+
+class JSONCDecodeError(json.JSONDecodeError):
+    """Error raised when JSONC parsing fails.
+
+    Provides line and column numbers relative to the original JSONC source
+    (before comment/trailing-comma stripping).
+    """
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def loads(
+    text: str,
+    *,
+    cls: type[json.JSONDecoder] | None = None,
+    object_hook: Any = None,
+    parse_float: Any = None,
+    parse_int: Any = None,
+    parse_constant: Any = None,
+    object_pairs_hook: Any = None,
+    **kwargs: Any,
+) -> Any:
+    """Deserialize a JSONC string to a Python object.
+
+    Strips ``//``, ``#``, and ``/* */`` comments and trailing commas before
+    delegating to :func:`json.loads`.
+
+    Args:
+        text: JSONC source string.
+        cls: Custom JSON decoder class.
+        object_hook: Called with the result of any object literal decoded.
+        parse_float: Called with every JSON float string decoded.
+        parse_int: Called with every JSON int string decoded.
+        parse_constant: Called with ``-Infinity``, ``Infinity``, ``NaN``.
+        object_pairs_hook: Called with an ordered list of pairs.
+        **kwargs: Additional keyword arguments passed to :func:`json.loads`.
+
+    Returns:
+        Deserialized Python object.
+
+    Raises:
+        JSONCDecodeError: If the text is not valid JSONC.
+    """
+    cleaned = _preprocess(text)
+    try:
+        return json.loads(
+            cleaned,
+            cls=cls,
+            object_hook=object_hook,
+            parse_float=parse_float,
+            parse_int=parse_int,
+            parse_constant=parse_constant,
+            object_pairs_hook=object_pairs_hook,
+            **kwargs,
+        )
+    except json.JSONDecodeError as exc:
+        line, col = _remap_error_position(text, cleaned, exc.pos)
+        raise JSONCDecodeError(exc.msg, text, exc.pos) from None
+
+
+def load(
+    fp: IO[str],
+    *,
+    cls: type[json.JSONDecoder] | None = None,
+    object_hook: Any = None,
+    parse_float: Any = None,
+    parse_int: Any = None,
+    parse_constant: Any = None,
+    object_pairs_hook: Any = None,
+    **kwargs: Any,
+) -> Any:
+    """Deserialize a JSONC file to a Python object.
+
+    Args:
+        fp: A text file-like object containing JSONC.
+        cls: Custom JSON decoder class.
+        object_hook: Called with the result of any object literal decoded.
+        parse_float: Called with every JSON float string decoded.
+        parse_int: Called with every JSON int string decoded.
+        parse_constant: Called with ``-Infinity``, ``Infinity``, ``NaN``.
+        object_pairs_hook: Called with an ordered list of pairs.
+        **kwargs: Additional keyword arguments passed to :func:`json.loads`.
+
+    Returns:
+        Deserialized Python object.
+
+    Raises:
+        JSONCDecodeError: If the content is not valid JSONC.
+    """
+    return loads(
+        fp.read(),
+        cls=cls,
+        object_hook=object_hook,
+        parse_float=parse_float,
+        parse_int=parse_int,
+        parse_constant=parse_constant,
+        object_pairs_hook=object_pairs_hook,
+        **kwargs,
+    )
+
+
+def dumps(
+    obj: Any,
+    *,
+    skipkeys: bool = False,
+    ensure_ascii: bool = True,
+    check_circular: bool = True,
+    allow_nan: bool = True,
+    cls: type[json.JSONEncoder] | None = None,
+    indent: int | str | None = None,
+    separators: tuple[str, str] | None = None,
+    default: Any = None,
+    sort_keys: bool = False,
+    **kwargs: Any,
+) -> str:
+    """Serialize a Python object to a JSON string.
+
+    This is a pass-through to :func:`json.dumps` for API compatibility.
+
+    Args:
+        obj: Python object to serialize.
+        skipkeys: Skip keys that are not basic types.
+        ensure_ascii: Escape non-ASCII characters.
+        check_circular: Check for circular references.
+        allow_nan: Allow ``NaN``, ``Infinity``, ``-Infinity``.
+        cls: Custom JSON encoder class.
+        indent: Indentation level for pretty-printing.
+        separators: Item and key separators.
+        default: Called for objects that are not serializable.
+        sort_keys: Sort dictionary keys.
+        **kwargs: Additional keyword arguments passed to :func:`json.dumps`.
+
+    Returns:
+        JSON string.
+    """
+    return json.dumps(
+        obj,
+        skipkeys=skipkeys,
+        ensure_ascii=ensure_ascii,
+        check_circular=check_circular,
+        allow_nan=allow_nan,
+        cls=cls,
+        indent=indent,
+        separators=separators,
+        default=default,
+        sort_keys=sort_keys,
+        **kwargs,
+    )
+
+
+def dump(
+    obj: Any,
+    fp: IO[str],
+    *,
+    skipkeys: bool = False,
+    ensure_ascii: bool = True,
+    check_circular: bool = True,
+    allow_nan: bool = True,
+    cls: type[json.JSONEncoder] | None = None,
+    indent: int | str | None = None,
+    separators: tuple[str, str] | None = None,
+    default: Any = None,
+    sort_keys: bool = False,
+    **kwargs: Any,
+) -> None:
+    """Serialize a Python object to a JSON file.
+
+    This is a pass-through to :func:`json.dump` for API compatibility.
+
+    Args:
+        obj: Python object to serialize.
+        fp: A text file-like object to write to.
+        skipkeys: Skip keys that are not basic types.
+        ensure_ascii: Escape non-ASCII characters.
+        check_circular: Check for circular references.
+        allow_nan: Allow ``NaN``, ``Infinity``, ``-Infinity``.
+        cls: Custom JSON encoder class.
+        indent: Indentation level for pretty-printing.
+        separators: Item and key separators.
+        default: Called for objects that are not serializable.
+        sort_keys: Sort dictionary keys.
+        **kwargs: Additional keyword arguments passed to :func:`json.dump`.
+    """
+    json.dump(
+        obj,
+        fp,
+        skipkeys=skipkeys,
+        ensure_ascii=ensure_ascii,
+        check_circular=check_circular,
+        allow_nan=allow_nan,
+        cls=cls,
+        indent=indent,
+        separators=separators,
+        default=default,
+        sort_keys=sort_keys,
+        **kwargs,
+    )

src/veilrender/_vendor/markdown.py

@@ -0,0 +1,904 @@
+# /// zerodep
+# version = "0.4.1"
+# deps = []
+# tier = "medium"
+# category = "text"
+# note = "Install/update via `zerodep add markdown`"
+# ///
+
+"""Markdown to HTML renderer — zero dependencies, stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Drop-in replacement for mistune's ``mistune.html()`` for common Markdown.
+
+Supports:
+    - ATX and Setext headings
+    - Paragraphs, thematic breaks, hard line breaks
+    - Emphasis (bold, italic, bold-italic)
+    - Inline code and fenced/indented code blocks
+    - Links (inline, reference, autolink) and images
+    - Ordered and unordered lists with nesting
+    - Block quotes with nesting
+    - GFM tables with column alignment
+    - GFM strikethrough (~~text~~)
+    - GFM task lists (- [ ] / - [x])
+    - GFM extended autolinks (bare URLs)
+    - Backslash escapes
+
+Does NOT implement:
+    - Raw HTML passthrough (escaped for safety)
+    - Footnotes, definition lists, math/LaTeX
+
+Example::
+
+    from markdown import render
+    render("# Hello\\n\\nThis is **bold**.")
+    # '<h1>Hello</h1>\\n<p>This is <strong>bold</strong>.</p>\\n'
+"""
+
+from __future__ import annotations
+
+import html
+import re
+
+__all__ = [
+    "render",
+]
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+_ESCAPED_CHARS = r"\\!\"#$%&'()*+,\-./:;<=>?@\[\\\]^_`{|}~"
+
+_HARMFUL_PROTOCOLS = ("javascript:", "vbscript:", "file:", "data:")
+_SAFE_DATA_PREFIXES = (
+    "data:image/gif;",
+    "data:image/png;",
+    "data:image/jpeg;",
+    "data:image/webp;",
+)
+
+# ── Block-level patterns ─────────────────────────────────────────────────────
+
+_ATX_HEADING_RE = re.compile(r"^(#{1,6})(?:\s+|$)(.*?)(?:\s+#+\s*)?$")
+_SETEXT_HEADING_RE = re.compile(r"^(=+|-+)\s*$")
+_FENCED_CODE_RE = re.compile(r"^( {0,3})(`{3,}|~{3,})\s*(\S*)\s*$")
+_THEMATIC_BREAK_RE = re.compile(
+    r"^ {0,3}(?:(?:-[ \t]*){3,}|(?:\*[ \t]*){3,}|(?:_[ \t]*){3,})\s*$"
+)
+_BLOCK_QUOTE_RE = re.compile(r"^ {0,3}>[ \t]?(.*)")
+_UL_ITEM_RE = re.compile(r"^( *)([-*+]) (.*)")
+_OL_ITEM_RE = re.compile(r"^( *)(\d{1,9})([.)]) (.*)")
+_INDENT_CODE_RE = re.compile(r"^(?: {4}|\t)(.*)")
+_REF_LINK_RE = re.compile(
+    r"""^ {0,3}\[([^\]]+)\]:\s+<?(\S+?)>?(?:\s+["'(](.+?)["')])?\s*$"""
+)
+_TABLE_DELIM_RE = re.compile(
+    r"^ {0,3}\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?\s*$"
+)
+_BLANK_RE = re.compile(r"^\s*$")
+
+# ── Inline patterns ──────────────────────────────────────────────────────────
+
+_BACKSLASH_ESCAPE_RE = re.compile(r"\\([" + _ESCAPED_CHARS + r"])")
+_CODE_SPAN_RE = re.compile(r"(?<!`)(`+)(?!`)([\s\S]*?[^`])(\1)(?!`)")
+_AUTOLINK_RE = re.compile(r"<([a-zA-Z][a-zA-Z0-9.+-]{1,31}:[^<>\s]*)>")
+_AUTOEMAIL_RE = re.compile(
+    r"<([a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9]"
+    r"(?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?"
+    r"(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*)>"
+)
+_IMAGE_RE = re.compile(
+    r"!\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]"
+    r"""\(\s*(\S+?)(?:\s+["'](.+?)["'])?\s*\)"""
+)
+_LINK_RE = re.compile(
+    r"\[([^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*)\]"
+    r"""\(\s*(\S+?)(?:\s+["'](.+?)["'])?\s*\)"""
+)
+_REF_LINK_USE_RE = re.compile(r"\[([^\[\]]+)\]\[([^\[\]]*)\]")
+_REF_LINK_SHORT_RE = re.compile(r"\[([^\[\]]+)\](?!\()")
+_STRONG_EM_RE = re.compile(r"\*{3}(.+?)\*{3}|_{3}(.+?)_{3}")
+_STRONG_RE = re.compile(r"\*{2}(.+?)\*{2}|_{2}(.+?)_{2}")
+_EM_RE = re.compile(r"(?<!\w)\*(.+?)\*(?!\w)|(?<!\w)_(.+?)_(?!\w)")
+_STRIKETHROUGH_RE = re.compile(r"~~(.+?)~~")
+_BARE_URL_RE = re.compile(r"(https?://[^\s<>\[\]]*[^\s<>\[\].,;:!?'\")}\]])")
+_HARD_BREAK_RE = re.compile(r"(?:\\| {2,})\n")
+
+# Task list marker: [ ], [x], or [X] at start of list item content
+_TASK_LIST_RE = re.compile(r"^\[([ xX])\]\s+")
+
+# ── Placeholder system ───────────────────────────────────────────────────────
+
+_PH_PREFIX = "\x00PH"
+_PH_SUFFIX = "\x00"
+
+
+class _Placeholders:
+    """Manages placeholder substitution to protect parsed regions."""
+
+    __slots__ = ("_store", "_counter")
+
+    def __init__(self) -> None:
+        self._store: list[str] = []
+        self._counter = 0
+
+    def put(self, value: str) -> str:
+        idx = self._counter
+        self._counter += 1
+        self._store.append(value)
+        return f"{_PH_PREFIX}{idx}{_PH_SUFFIX}"
+
+    def restore(self, text: str) -> str:
+        for i in range(len(self._store) - 1, -1, -1):
+            text = text.replace(f"{_PH_PREFIX}{i}{_PH_SUFFIX}", self._store[i])
+        return text
+
+
+# ── URL safety ────────��───────────────────────────────────────────────────────
+
+
+def _safe_url(url: str) -> str:
+    """Sanitize a URL, blocking dangerous protocols."""
+    lower = url.strip().lower()
+    if lower.startswith(_HARMFUL_PROTOCOLS) and not lower.startswith(
+        _SAFE_DATA_PREFIXES
+    ):
+        return "#harmful-link"
+    return html.escape(url, quote=True)
+
+
+# ── Inline helper functions ──────────────────────────────────────────────────
+
+
+def _apply_bare_urls(text: str, ph: _Placeholders) -> str:
+    """Replace bare http/https URLs with link placeholders."""
+
+    def _bare_url_repl(m: re.Match[str]) -> str:
+        url = m.group(1)
+        return ph.put('<a href="' + _safe_url(url) + '">' + html.escape(url) + "</a>")
+
+    return _BARE_URL_RE.sub(_bare_url_repl, text)
+
+
+def _apply_emphasis(
+    text: str,
+    ph: _Placeholders,
+    ref_links: dict[str, tuple[str, str | None]],
+) -> str:
+    """Apply bold-italic, bold, italic, and strikethrough replacements."""
+
+    # Bold-italic ***text***
+    def _strong_em_repl(m: re.Match[str]) -> str:
+        content = m.group(1) or m.group(2)
+        return ph.put(
+            "<em><strong>" + _parse_inline(content, ref_links) + "</strong></em>"
+        )
+
+    text = _STRONG_EM_RE.sub(_strong_em_repl, text)
+
+    # Bold **text**
+    def _strong_repl(m: re.Match[str]) -> str:
+        content = m.group(1) or m.group(2)
+        return ph.put("<strong>" + _parse_inline(content, ref_links) + "</strong>")
+
+    text = _STRONG_RE.sub(_strong_repl, text)
+
+    # Italic *text*
+    def _em_repl(m: re.Match[str]) -> str:
+        content = m.group(1) or m.group(2)
+        return ph.put("<em>" + _parse_inline(content, ref_links) + "</em>")
+
+    text = _EM_RE.sub(_em_repl, text)
+
+    # Strikethrough ~~text~~
+    def _strike_repl(m: re.Match[str]) -> str:
+        content = m.group(1)
+        return ph.put("<del>" + _parse_inline(content, ref_links) + "</del>")
+
+    text = _STRIKETHROUGH_RE.sub(_strike_repl, text)
+    return text
+
+
+# ── Inline parser ─────────────────────────────────────────────────────────────
+
+
+def _parse_inline(
+    text: str,
+    ref_links: dict[str, tuple[str, str | None]],
+) -> str:
+    """Parse inline Markdown elements and return HTML."""
+    ph = _Placeholders()
+
+    # 1. Backslash escapes → placeholder
+    def _escape_repl(m: re.Match[str]) -> str:
+        return ph.put(html.escape(m.group(1), quote=True))
+
+    text = _BACKSLASH_ESCAPE_RE.sub(_escape_repl, text)
+
+    # 2. Code spans → placeholder (no further parsing inside)
+    def _code_repl(m: re.Match[str]) -> str:
+        code = m.group(2).strip()
+        return ph.put("<code>" + html.escape(code, quote=True) + "</code>")
+
+    text = _CODE_SPAN_RE.sub(_code_repl, text)
+
+    # 3. Autolinks
+    def _autolink_repl(m: re.Match[str]) -> str:
+        url = m.group(1)
+        return ph.put('<a href="' + _safe_url(url) + '">' + html.escape(url) + "</a>")
+
+    text = _AUTOLINK_RE.sub(_autolink_repl, text)
+
+    # 3b. Auto emails
+    def _autoemail_repl(m: re.Match[str]) -> str:
+        email = m.group(1)
+        return ph.put(
+            '<a href="mailto:' + html.escape(email) + '">' + html.escape(email) + "</a>"
+        )
+
+    text = _AUTOEMAIL_RE.sub(_autoemail_repl, text)
+
+    # 4. Images
+    def _image_repl(m: re.Match[str]) -> str:
+        alt = html.escape(m.group(1), quote=True)
+        url = _safe_url(m.group(2))
+        title = m.group(3)
+        s = '<img src="' + url + '" alt="' + alt + '"'
+        if title:
+            s += ' title="' + html.escape(title, quote=True) + '"'
+        s += " />"
+        return ph.put(s)
+
+    text = _IMAGE_RE.sub(_image_repl, text)
+
+    # 5. Inline links
+    def _link_repl(m: re.Match[str]) -> str:
+        link_text = _parse_inline(m.group(1), ref_links)
+        url = _safe_url(m.group(2))
+        title = m.group(3)
+        s = '<a href="' + url + '"'
+        if title:
+            s += ' title="' + html.escape(title, quote=True) + '"'
+        s += ">" + link_text + "</a>"
+        return ph.put(s)
+
+    text = _LINK_RE.sub(_link_repl, text)
+
+    # 5b. Reference links [text][ref]
+    def _ref_link_repl(m: re.Match[str]) -> str:
+        link_text = m.group(1)
+        ref_key = (m.group(2) or link_text).strip().lower()
+        ref = ref_links.get(ref_key)
+        if ref is None:
+            return m.group(0)
+        url, title = ref
+        s = '<a href="' + _safe_url(url) + '"'
+        if title:
+            s += ' title="' + html.escape(title, quote=True) + '"'
+        s += ">" + _parse_inline(link_text, ref_links) + "</a>"
+        return ph.put(s)
+
+    text = _REF_LINK_USE_RE.sub(_ref_link_repl, text)
+
+    # 5c. Shortcut reference links [ref]
+    def _ref_short_repl(m: re.Match[str]) -> str:
+        link_text = m.group(1)
+        ref_key = link_text.strip().lower()
+        ref = ref_links.get(ref_key)
+        if ref is None:
+            return m.group(0)
+        url, title = ref
+        s = '<a href="' + _safe_url(url) + '"'
+        if title:
+            s += ' title="' + html.escape(title, quote=True) + '"'
+        s += ">" + _parse_inline(link_text, ref_links) + "</a>"
+        return ph.put(s)
+
+    text = _REF_LINK_SHORT_RE.sub(_ref_short_repl, text)
+
+    # 5d. Extended autolinks (bare URLs without angle brackets)
+    text = _apply_bare_urls(text, ph)
+
+    # 6. Emphasis + strikethrough
+    text = _apply_emphasis(text, ph, ref_links)
+
+    # 7. Hard line breaks (protect with placeholder)
+    text = _HARD_BREAK_RE.sub(lambda m: ph.put("<br />\n"), text)
+
+    # 8. Escape remaining HTML in text
+    # We need to be careful: only escape text that hasn't been processed.
+    # The placeholder system handles this — placeholders contain final HTML.
+    # We escape the remaining raw text segments between placeholders.
+    parts = re.split(r"(\x00PH\d+\x00)", text)
+    for i, part in enumerate(parts):
+        if not part.startswith(_PH_PREFIX):
+            parts[i] = html.escape(part, quote=False)
+    text = "".join(parts)
+
+    # 9. Restore placeholders
+    text = ph.restore(text)
+
+    return text
+
+
+# ── Table parser ──────────────────────────────────────────────────────────────
+
+
+def _parse_table_row(line: str) -> list[str]:
+    """Split a table row into cells."""
+    line = line.strip()
+    if line.startswith("|"):
+        line = line[1:]
+    if line.endswith("|"):
+        line = line[:-1]
+    # Split on unescaped pipes
+    cells = re.split(r"(?<!\\)\|", line)
+    return [c.strip() for c in cells]
+
+
+def _parse_table_align(line: str) -> list[str | None]:
+    """Parse alignment row, return list of 'left', 'right', 'center', or None."""
+    cells = _parse_table_row(line)
+    aligns: list[str | None] = []
+    for cell in cells:
+        cell = cell.strip()
+        left = cell.startswith(":")
+        right = cell.endswith(":")
+        if left and right:
+            aligns.append("center")
+        elif right:
+            aligns.append("right")
+        elif left:
+            aligns.append("left")
+        else:
+            aligns.append(None)
+    return aligns
+
+
+def _render_table(
+    header_line: str,
+    align_line: str,
+    body_lines: list[str],
+    ref_links: dict[str, tuple[str, str | None]],
+) -> str:
+    """Render a GFM table to HTML."""
+    headers = _parse_table_row(header_line)
+    aligns = _parse_table_align(align_line)
+
+    out: list[str] = ["<table>\n<thead>\n<tr>\n"]
+    for i, h in enumerate(headers):
+        align = aligns[i] if i < len(aligns) else None
+        style = f' style="text-align:{align}"' if align else ""
+        out.append(f"  <th{style}>{_parse_inline(h, ref_links)}</th>\n")
+    out.append("</tr>\n</thead>\n")
+
+    if body_lines:
+        out.append("<tbody>\n")
+        for line in body_lines:
+            cells = _parse_table_row(line)
+            out.append("<tr>\n")
+            for i, cell in enumerate(cells):
+                align = aligns[i] if i < len(aligns) else None
+                style = f' style="text-align:{align}"' if align else ""
+                out.append(f"  <td{style}>{_parse_inline(cell, ref_links)}</td>\n")
+            out.append("</tr>\n")
+        out.append("</tbody>\n")
+
+    out.append("</table>\n")
+    return "".join(out)
+
+
+# ── List parser ───────────────────────────────────────────────────────────────
+
+
+def _detect_list_type(
+    line: str,
+) -> tuple[bool, int, int] | None:
+    """Detect whether a line starts a list item.
+
+    Returns:
+        (ordered, base_indent, start_num) or None if not a list item.
+    """
+    ol_m = _OL_ITEM_RE.match(line)
+    if ol_m:
+        return True, len(ol_m.group(1)), int(ol_m.group(2))
+    ul_m = _UL_ITEM_RE.match(line)
+    if ul_m:
+        return False, len(ul_m.group(1)), 1
+    return None
+
+
+def _blank_continues_list(
+    lines: list[str],
+    idx: int,
+    ordered: bool,
+    base_indent: int,
+) -> bool:
+    """Check whether a blank line at *idx* is followed by list continuation."""
+    if idx + 1 >= len(lines):
+        return False
+    next_line = lines[idx + 1]
+    if _BLANK_RE.match(next_line):
+        return False
+    # Same-level item?
+    if ordered:
+        m = _OL_ITEM_RE.match(next_line)
+        if m and len(m.group(1)) == base_indent:
+            return True
+    else:
+        m = _UL_ITEM_RE.match(next_line)
+        if m and len(m.group(1)) == base_indent:
+            return True
+    # Indented continuation / nested content
+    next_indent = len(next_line) - len(next_line.lstrip())
+    return next_indent > base_indent
+
+
+def _match_same_level_item(
+    line: str,
+    ordered: bool,
+    base_indent: int,
+) -> str | None:
+    """If *line* is a same-level list item, return its content text."""
+    if ordered:
+        m = _OL_ITEM_RE.match(line)
+        if m and len(m.group(1)) == base_indent:
+            return m.group(4)
+    else:
+        m = _UL_ITEM_RE.match(line)
+        if m and len(m.group(1)) == base_indent:
+            return m.group(3)
+    return None
+
+
+def _collect_list_items(
+    lines: list[str],
+    start_idx: int,
+    ordered: bool,
+    base_indent: int,
+) -> tuple[list[list[str]], int]:
+    """Collect raw item line groups from a list block.
+
+    Returns:
+        (items, next_idx) where each item is a list of content lines.
+    """
+    idx = start_idx
+    items: list[list[str]] = []
+    current: list[str] = []
+
+    while idx < len(lines):
+        line = lines[idx]
+
+        # Blank line — may separate items or end the list
+        if _BLANK_RE.match(line):
+            if _blank_continues_list(lines, idx, ordered, base_indent):
+                current.append("")
+                idx += 1
+                continue
+            break
+
+        # Same-level item starts a new entry
+        content = _match_same_level_item(line, ordered, base_indent)
+        if content is not None:
+            if current:
+                items.append(current)
+            current = [content]
+            idx += 1
+            continue
+
+        # Nested / continuation line
+        indent = len(line) - len(line.lstrip())
+        if indent > base_indent and current:
+            dedented = line[base_indent + 2 :] if len(line) > base_indent + 2 else ""
+            current.append(dedented)
+            idx += 1
+            continue
+
+        break
+
+    if current:
+        items.append(current)
+    return items, idx
+
+
+def _render_list_item(
+    item_lines: list[str],
+    ref_links: dict[str, tuple[str, str | None]],
+) -> str:
+    """Render a single <li> element, recursing for nested sub-lists."""
+    # Detect task list marker
+    task_class = ""
+    task_checkbox = ""
+    first_line = item_lines[0]
+    task_m = _TASK_LIST_RE.match(first_line)
+    if task_m:
+        checked = task_m.group(1) in ("x", "X")
+        task_class = ' class="task-list-item"'
+        task_checkbox = (
+            '<input class="task-list-item-checkbox" type="checkbox" disabled'
+        )
+        if checked:
+            task_checkbox += " checked"
+        task_checkbox += "/>"
+        item_lines = [first_line[task_m.end() :]] + item_lines[1:]
+
+    has_sublist = any(
+        _UL_ITEM_RE.match(il) or _OL_ITEM_RE.match(il) for il in item_lines[1:]
+    )
+    open_tag = f"<li{task_class}>" + task_checkbox
+    if has_sublist:
+        first = _parse_inline(item_lines[0], ref_links)
+        sub_html = _parse_blocks(item_lines[1:], ref_links)
+        return open_tag + first + sub_html + "</li>\n"
+    content = "\n".join(item_lines).strip()
+    return open_tag + _parse_inline(content, ref_links) + "</li>\n"
+
+
+def _parse_list_block(
+    lines: list[str],
+    start_idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+) -> tuple[str, int]:
+    """Parse a list block starting at *start_idx*. Returns (html, next_idx)."""
+    info = _detect_list_type(lines[start_idx])
+    if info is None:
+        return "", start_idx
+    ordered, base_indent, start_num = info
+
+    items, idx = _collect_list_items(lines, start_idx, ordered, base_indent)
+
+    tag = "ol" if ordered else "ul"
+    start_attr = f' start="{start_num}"' if ordered and start_num != 1 else ""
+    parts: list[str] = [f"<{tag}{start_attr}>\n"]
+    for item_lines in items:
+        parts.append(_render_list_item(item_lines, ref_links))
+    parts.append(f"</{tag}>\n")
+    return "".join(parts), idx
+
+
+# ── Block-level try-parse helpers ────────────────────────────────────────────
+
+_BlockResult = tuple[str, int, bool]
+"""(html, new_idx, consumed_para) returned by each _try_parse_* helper."""
+
+
+def _try_parse_hr(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse a thematic break."""
+    if para_lines:
+        return None
+    if _THEMATIC_BREAK_RE.match(lines[idx]):
+        return "<hr />\n", idx + 1, False
+    return None
+
+
+def _try_parse_atx_heading(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse an ATX heading."""
+    if para_lines:
+        return None
+    m = _ATX_HEADING_RE.match(lines[idx])
+    if not m:
+        return None
+    level = len(m.group(1))
+    content = re.sub(r"\s+#+\s*$", "", m.group(2).strip())
+    tag = f"h{level}"
+    h = f"<{tag}>{_parse_inline(content, ref_links)}</{tag}>\n"
+    return h, idx + 1, False
+
+
+def _try_parse_setext_heading(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse a Setext heading (requires accumulated paragraph lines)."""
+    if not para_lines:
+        return None
+    line = lines[idx]
+    if not _SETEXT_HEADING_RE.match(line):
+        return None
+    level = 1 if line.strip().startswith("=") else 2
+    content = "\n".join(para_lines)
+    tag = f"h{level}"
+    h = f"<{tag}>{_parse_inline(content.strip(), ref_links)}</{tag}>\n"
+    return h, idx + 1, True  # consumed_para=True
+
+
+def _try_parse_code_fence(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse a fenced code block."""
+    if para_lines:
+        return None
+    m = _FENCED_CODE_RE.match(lines[idx])
+    if not m:
+        return None
+    fence_indent = len(m.group(1))
+    fence_char = m.group(2)[0]
+    fence_len = len(m.group(2))
+    lang = m.group(3).strip()
+
+    code_lines: list[str] = []
+    j = idx + 1
+    close_re = re.compile(
+        r"^ {0,3}" + re.escape(fence_char) + r"{" + str(fence_len) + r",}\s*$"
+    )
+    while j < len(lines):
+        cl = lines[j]
+        if close_re.match(cl):
+            j += 1
+            break
+        code_lines.append(_strip_fence_indent(cl, fence_indent))
+        j += 1
+
+    code = "\n".join(code_lines)
+    if code and not code.endswith("\n"):
+        code += "\n"
+    escaped_code = html.escape(code, quote=False)
+    lang_attr = f' class="language-{html.escape(lang, quote=True)}"' if lang else ""
+    h = f"<pre><code{lang_attr}>{escaped_code}</code></pre>\n"
+    return h, j, False
+
+
+def _strip_fence_indent(line: str, indent: int) -> str:
+    """Remove up to *indent* leading spaces from *line*."""
+    if indent <= 0:
+        return line
+    for _ in range(indent):
+        if line.startswith(" "):
+            line = line[1:]
+        else:
+            break
+    return line
+
+
+def _try_parse_indent_code(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse an indented code block (4-space indent)."""
+    if para_lines:
+        return None
+    if not _INDENT_CODE_RE.match(lines[idx]):
+        return None
+
+    code_lines: list[str] = []
+    j = idx
+    while j < len(lines):
+        ic_m = _INDENT_CODE_RE.match(lines[j])
+        if ic_m:
+            code_lines.append(ic_m.group(1))
+            j += 1
+        elif _BLANK_RE.match(lines[j]):
+            if j + 1 < len(lines) and _INDENT_CODE_RE.match(lines[j + 1]):
+                code_lines.append("")
+                j += 1
+            else:
+                break
+        else:
+            break
+    # Remove trailing blank lines
+    while code_lines and code_lines[-1] == "":
+        code_lines.pop()
+    escaped_code = html.escape("\n".join(code_lines), quote=False)
+    h = f"<pre><code>{escaped_code}</code></pre>\n"
+    return h, j, False
+
+
+def _try_parse_blockquote(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse a block quote (can interrupt a paragraph)."""
+    if not _BLOCK_QUOTE_RE.match(lines[idx]):
+        return None
+
+    bq_lines: list[str] = []
+    j = idx
+    while j < len(lines):
+        bq_match = _BLOCK_QUOTE_RE.match(lines[j])
+        if bq_match:
+            bq_lines.append(bq_match.group(1))
+            j += 1
+        elif _BLANK_RE.match(lines[j]):
+            if j + 1 < len(lines) and _BLOCK_QUOTE_RE.match(lines[j + 1]):
+                bq_lines.append("")
+                j += 1
+            else:
+                break
+        elif lines[j].strip():
+            # Lazy continuation
+            bq_lines.append(lines[j])
+            j += 1
+        else:
+            break
+    inner = _parse_blocks(bq_lines, ref_links)
+    h = "<blockquote>\n" + inner + "</blockquote>\n"
+    return h, j, False
+
+
+def _try_parse_list(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse an ordered or unordered list."""
+    if para_lines:
+        return None
+    if not (_UL_ITEM_RE.match(lines[idx]) or _OL_ITEM_RE.match(lines[idx])):
+        return None
+    list_html, new_idx = _parse_list_block(lines, idx, ref_links)
+    return list_html, new_idx, False
+
+
+def _try_parse_table(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try to parse a GFM table."""
+    if para_lines:
+        return None
+    line = lines[idx]
+    if "|" not in line or idx + 1 >= len(lines):
+        return None
+    if not _TABLE_DELIM_RE.match(lines[idx + 1]):
+        return None
+
+    header_line = line
+    align_line = lines[idx + 1]
+    body: list[str] = []
+    j = idx + 2
+    while j < len(lines):
+        tl = lines[j]
+        if "|" in tl and not _BLANK_RE.match(tl):
+            body.append(tl)
+            j += 1
+        else:
+            break
+    h = _render_table(header_line, align_line, body, ref_links)
+    return h, j, False
+
+
+# Ordered list of try-parse functions used by the block dispatcher.
+_BLOCK_PARSERS = (
+    _try_parse_hr,
+    _try_parse_atx_heading,
+    _try_parse_setext_heading,
+    _try_parse_code_fence,
+    _try_parse_indent_code,
+    _try_parse_blockquote,
+    _try_parse_list,
+    _try_parse_table,
+)
+
+
+# ── Block parser ──────────────────────────────────────────────────────────────
+
+
+def _collect_ref_links(
+    lines: list[str],
+) -> dict[str, tuple[str, str | None]]:
+    """First pass: collect reference link definitions."""
+    refs: dict[str, tuple[str, str | None]] = {}
+    for line in lines:
+        m = _REF_LINK_RE.match(line)
+        if m:
+            key = m.group(1).strip().lower()
+            url = m.group(2)
+            title = m.group(3)
+            refs[key] = (url, title)
+    return refs
+
+
+def _parse_blocks(
+    lines: list[str],
+    ref_links: dict[str, tuple[str, str | None]],
+) -> str:
+    """Parse block-level Markdown elements from a list of lines."""
+    out: list[str] = []
+    idx = 0
+    para_lines: list[str] = []
+
+    def flush_paragraph() -> None:
+        if para_lines:
+            text = "\n".join(para_lines)
+            out.append("<p>" + _parse_inline(text.strip(), ref_links) + "</p>\n")
+            para_lines.clear()
+
+    while idx < len(lines):
+        line = lines[idx]
+
+        # Skip reference link definitions (already collected)
+        if _REF_LINK_RE.match(line):
+            flush_paragraph()
+            idx += 1
+            continue
+
+        # Blank line
+        if _BLANK_RE.match(line):
+            flush_paragraph()
+            idx += 1
+            continue
+
+        # Try each block-level parser in priority order
+        result = _dispatch_block(lines, idx, ref_links, para_lines)
+        if result is not None:
+            block_html, idx, consumed_para = result
+            if consumed_para:
+                para_lines.clear()
+            else:
+                flush_paragraph()
+            out.append(block_html)
+            continue
+
+        # Paragraph accumulation
+        para_lines.append(line)
+        idx += 1
+
+    flush_paragraph()
+    return "".join(out)
+
+
+def _dispatch_block(
+    lines: list[str],
+    idx: int,
+    ref_links: dict[str, tuple[str, str | None]],
+    para_lines: list[str],
+) -> _BlockResult | None:
+    """Try each registered block parser; return first match or None."""
+    for try_fn in _BLOCK_PARSERS:
+        result = try_fn(lines, idx, ref_links, para_lines)
+        if result is not None:
+            return result
+    return None
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def render(text: str) -> str:
+    """Convert Markdown text to HTML.
+
+    Args:
+        text: Markdown source string.
+
+    Returns:
+        HTML string.
+    """
+    # Normalize line endings
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+
+    # Split into lines
+    lines = text.split("\n")
+
+    # Remove trailing newline that produces empty last element
+    if lines and lines[-1] == "":
+        lines.pop()
+
+    # First pass: collect reference link definitions
+    ref_links = _collect_ref_links(lines)
+
+    # Second pass: parse blocks
+    return _parse_blocks(lines, ref_links)

src/veilrender/_vendor/readability.py

@@ -0,0 +1,1002 @@
+# /// zerodep
+# version = "0.1.0"
+# deps = ["soup"]
+# tier = "medium"
+# category = "text"
+# note = "Install/update via `zerodep add readability`"
+# ///
+
+"""HTML readability content extractor — zero-dep, stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Extracts the main article content from arbitrary web pages using a scoring
+algorithm inspired by Mozilla's Readability.js (Firefox Reader View).  Built
+on top of ``zerodep/soup`` for HTML parsing; no external dependencies.
+
+Algorithm overview:
+
+1. Pre-clean the DOM (remove scripts, styles, etc.)
+2. Extract metadata (JSON-LD, ``<meta>`` tags, ``<title>``)
+3. Remove unlikely candidate nodes (sidebars, footers, ads …)
+4. Transform mis-used ``<div>`` elements into ``<p>`` paragraphs
+5. Score every ``<p>``/``<pre>``/``<td>`` node based on comma count,
+   text length and class/id weight; propagate scores to parent &
+   grandparent
+6. Pick the highest-scoring container and include qualifying siblings
+7. Sanitize the extracted article (remove forms, low-quality headers …)
+8. If the result is too short, retry with relaxed heuristics
+
+Example::
+
+    from readability import extract, is_probably_readable
+
+    html = open("article.html").read()
+    if is_probably_readable(html):
+        result = extract(html)
+        print(result.title)
+        print(result.text[:200])
+
+References:
+    - Mozilla Readability.js: https://github.com/mozilla/readability
+    - python-readability: https://github.com/buriy/python-readability
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import os
+import re
+import sys
+from dataclasses import dataclass
+from html import unescape
+from typing import Any
+
+__all__ = [
+    "ReadabilityResult",
+    "extract",
+    "is_probably_readable",
+]
+
+log = logging.getLogger(__name__)
+
+# ── Lazy soup import ─────────────────────────────────────────────────────────
+
+
+def _ensure_sibling_path(name: str) -> str:
+    """Add a sibling module directory to ``sys.path`` if not present."""
+    sibling_dir = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", name))
+    if sibling_dir not in sys.path:
+        sys.path.insert(0, sibling_dir)
+    return sibling_dir
+
+
+def _load_soup():
+    _ensure_sibling_path("soup")
+    try:
+        from soup import Soup, Tag  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise NotImplementedError(
+            "readability requires the 'soup' zerodep module — "
+            "place soup/soup.py alongside readability/"
+        ) from exc
+    return Soup, Tag
+
+
+# ── Constants & regex patterns ───────────────────────────────────────────────
+
+MIN_PARAGRAPH_LENGTH = 25
+RETRY_LENGTH = 250
+DEFAULT_CHAR_THRESHOLD = 500
+
+UNLIKELY_CANDIDATES_RE = re.compile(
+    r"combx|comment|community|disqus|extra|foot|header|menu|remark|rss|"
+    r"shoutbox|sidebar|sponsor|ad-break|agegate|pagination|pager|popup|"
+    r"tweet|twitter|widget|breadcrumb|social|share|related|banner|"
+    r"cookie|consent|modal|overlay|nav\b",
+    re.I,
+)
+
+OK_MAYBE_CANDIDATE_RE = re.compile(
+    r"and|article|body|column|main|shadow|content",
+    re.I,
+)
+
+POSITIVE_RE = re.compile(
+    r"article|body|content|entry|hentry|h-entry|main|page|pagination|"
+    r"post|text|blog|story",
+    re.I,
+)
+
+NEGATIVE_RE = re.compile(
+    r"-ad-|hidden|^hid$| hid$| hid |^hid |banner|combx|comment|com-|"
+    r"contact|footer|gdpr|masthead|media|meta|outbrain|promo|related|"
+    r"scroll|share|shoutbox|sidebar|skyscraper|sponsor|shopping|tags|"
+    r"tool|widget",
+    re.I,
+)
+
+BLOCK_LEVEL_TAGS = frozenset(
+    {
+        "a",
+        "blockquote",
+        "dl",
+        "div",
+        "img",
+        "ol",
+        "p",
+        "pre",
+        "table",
+        "ul",
+        "section",
+        "figure",
+        "header",
+        "footer",
+        "nav",
+        "aside",
+        "details",
+        "fieldset",
+        "form",
+        "hr",
+        "noscript",
+        "video",
+        "audio",
+    }
+)
+
+TAGS_TO_SCORE = frozenset({"p", "pre", "td"})
+
+TAG_WEIGHTS: dict[str, int] = {
+    "div": 5,
+    "article": 5,
+    "pre": 3,
+    "td": 3,
+    "blockquote": 3,
+    "address": -3,
+    "ol": -3,
+    "ul": -3,
+    "dl": -3,
+    "dd": -3,
+    "dt": -3,
+    "li": -3,
+    "form": -3,
+    "aside": -3,
+    "h1": -5,
+    "h2": -5,
+    "h3": -5,
+    "h4": -5,
+    "h5": -5,
+    "h6": -5,
+    "th": -5,
+    "header": -5,
+    "footer": -5,
+    "nav": -5,
+}
+
+CLEAN_CONDITIONALLY_TAGS = frozenset(
+    {"table", "ul", "div", "aside", "header", "footer", "section"}
+)
+
+REMOVE_TAGS = frozenset({"form", "textarea", "input", "button", "select"})
+
+TITLE_SEPARATORS_RE = re.compile(r"\s+[\|\-–—\\/>»]\s+")
+
+# JSON-LD Article types (Schema.org)
+JSONLD_ARTICLE_TYPES = frozenset(
+    {
+        "Article",
+        "AdvertiserContentArticle",
+        "NewsArticle",
+        "AnalysisNewsArticle",
+        "AskPublicNewsArticle",
+        "BackgroundNewsArticle",
+        "OpinionNewsArticle",
+        "ReportageNewsArticle",
+        "ReviewNewsArticle",
+        "Report",
+        "SatiricalArticle",
+        "ScholarlyArticle",
+        "MedicalScholarlyArticle",
+        "SocialMediaPosting",
+        "BlogPosting",
+        "LiveBlogPosting",
+        "DiscussionForumPosting",
+        "TechArticle",
+        "APIReference",
+    }
+)
+
+# Multi-language commas for scoring
+COMMAS_RE = re.compile(r"[\u002C\u060C\uFE50\uFE10\uFE11\u2E41\u2E34\u2E32\uFF0C]")
+
+
+# ── Result dataclass ─────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class ReadabilityResult:
+    """Container for extracted article data.
+
+    Attributes:
+        title: Article title (refined from ``<title>`` or headings).
+        content: Cleaned HTML of the main content.
+        text: Plain-text rendering of the main content.
+        author: Author name, or ``None``.
+        excerpt: Article excerpt / description, or ``None``.
+        site_name: Site name (e.g. from ``og:site_name``), or ``None``.
+        published_time: Publication timestamp string, or ``None``.
+        lang: Language code from ``<html lang="...">``, or ``None``.
+        dir: Text direction (``"ltr"`` / ``"rtl"``), or ``None``.
+        length: Character count of *text*.
+    """
+
+    title: str
+    content: str
+    text: str
+    author: str | None = None
+    excerpt: str | None = None
+    site_name: str | None = None
+    published_time: str | None = None
+    lang: str | None = None
+    dir: str | None = None
+    length: int = 0
+
+
+# ── Public API ───────────────────────────────────────────────────────────────
+
+
+def extract(html: str, url: str | None = None) -> ReadabilityResult:
+    """Extract the main article content from an HTML string.
+
+    Args:
+        html: The full HTML document as a decoded string.
+        url: Optional base URL (currently unused; reserved for future
+            link absolutisation).
+
+    Returns:
+        A ``ReadabilityResult`` with the extracted content and metadata.
+    """
+    Soup, _Tag = _load_soup()
+    reader = _Readability(html, Soup, _Tag)
+    return reader.parse()
+
+
+def is_probably_readable(
+    html: str,
+    min_score: float = 20.0,
+    min_content_length: int = 140,
+) -> bool:
+    """Quick heuristic check whether *html* likely contains a readable article.
+
+    Uses the same approach as Mozilla's ``isProbablyReaderable``: accumulate
+    ``sqrt(textLen - threshold)`` over qualifying ``<p>``/``<pre>``/``<article>``
+    nodes and return ``True`` once the score exceeds *min_score*.
+
+    Args:
+        html: The HTML document string.
+        min_score: Minimum cumulative score to consider readable.
+        min_content_length: Minimum text length for a node to contribute.
+
+    Returns:
+        ``True`` if the page is probably an article.
+    """
+    Soup, _Tag = _load_soup()
+    soup = Soup(html)
+
+    score = 0.0
+    for tag in soup.find_all(["p", "pre", "article"]):
+        # Skip unlikely candidates
+        class_id = _get_class_id_string(tag)
+        if len(class_id) > 1:
+            is_unlikely = UNLIKELY_CANDIDATES_RE.search(class_id)
+            is_ok = OK_MAYBE_CANDIDATE_RE.search(class_id)
+            if is_unlikely and not is_ok:
+                continue
+
+        text = tag.get_text(strip=True)
+        text_len = len(text)
+        if text_len < min_content_length:
+            continue
+
+        score += math.sqrt(text_len - min_content_length)
+        if score >= min_score:
+            return True
+
+    return False
+
+
+# ── Internal helpers ─────────────────────────────────────────────────────────
+
+
+def _get_class_id_string(tag: Any) -> str:
+    """Return concatenated class and id for regex matching."""
+    cls = tag.get("class", [])
+    if isinstance(cls, list):
+        cls = " ".join(cls)
+    tag_id = tag.get("id", "")
+    return f"{cls} {tag_id}"
+
+
+def _normalize_spaces(s: str) -> str:
+    """Collapse all whitespace to single spaces and strip."""
+    return " ".join(s.split())
+
+
+def _text_length(tag: Any) -> int:
+    """Return the length of the whitespace-normalised text content."""
+    return len(_normalize_spaces(tag.get_text()))
+
+
+# ── Readability engine ───────────────────────────────────────────────────────
+
+
+class _Readability:
+    """Internal engine that implements the readability extraction algorithm."""
+
+    # Tags to discard during article-extraction parsing.  These are never
+    # part of the readable content and skipping them speeds up both tree
+    # construction and subsequent traversals.
+    _SKIP_TAGS = frozenset({"script", "style", "link", "noscript"})
+
+    def __init__(self, html: str, Soup: type, Tag: type) -> None:
+        self._raw_html = html
+        self._Soup = Soup
+        self._Tag = Tag
+        self._soup: Any = None
+
+    # ── Main entry point ─────────────────────────────────────────────────
+
+    def parse(self) -> ReadabilityResult:
+        """Run the full extraction pipeline and return a result."""
+        # Parse once: extract metadata from the fresh DOM before mutations.
+        self._soup = self._Soup(self._raw_html)
+        metadata = self._extract_metadata(self._soup)
+        lang = self._detect_lang(self._soup)
+        direction = self._detect_dir(self._soup)
+
+        # Grab article content.  The first iteration reuses self._soup
+        # (removing non-content tags in-place); retries use a faster
+        # parse that skips those tags during tree construction.
+        article_html, article_text = self._grab_article()
+
+        # If metadata title is empty, try to derive from article headings.
+        title = metadata.get("title", "")
+        if not title:
+            title = self._get_title_from_headings(self._soup) or ""
+
+        text = _normalize_spaces(article_text)
+        return ReadabilityResult(
+            title=title,
+            content=article_html,
+            text=text,
+            author=metadata.get("author"),
+            excerpt=metadata.get("excerpt"),
+            site_name=metadata.get("site_name"),
+            published_time=metadata.get("published_time"),
+            lang=lang,
+            dir=direction,
+            length=len(text),
+        )
+
+    # ── Article grabbing (with retry) ────────────────────────────────────
+
+    _PRE_CLEAN_TAGS = ["script", "style", "link", "noscript"]
+
+    def _grab_article(self) -> tuple[str, str]:
+        """Extract article content, retrying with relaxed rules if needed.
+
+        Returns:
+            ``(article_html, article_text)`` tuple.
+        """
+        ruthless = True
+
+        for _attempt in range(2):
+            if _attempt == 0:
+                # First attempt: reuse the DOM already parsed by parse()
+                # and strip non-content tags in-place.
+                self._pre_clean()
+            else:
+                # Retry: fast re-parse that skips non-content tags at the
+                # parser level (avoids building + decomposing subtrees).
+                self._soup = self._Soup(self._raw_html, skip_tags=self._SKIP_TAGS)
+
+            if ruthless:
+                self._remove_unlikely_candidates()
+
+            self._transform_divs_to_paragraphs()
+            candidates = self._score_paragraphs()
+
+            best = self._select_best_candidate(candidates)
+            if best is not None:
+                article_tag = self._get_article(best, candidates)
+                self._sanitize(article_tag)
+                article_html = article_tag.to_html()
+                article_text = article_tag.get_text(separator=" ", strip=True)
+
+                if len(article_text) >= RETRY_LENGTH or not ruthless:
+                    return article_html, article_text
+
+                # Too short — retry without ruthless filtering.
+                log.debug(
+                    "Article too short (%d chars), retrying without "
+                    "ruthless candidate removal",
+                    len(article_text),
+                )
+                ruthless = False
+                continue
+            else:
+                if ruthless:
+                    log.debug("No candidate found, retrying without ruthless")
+                    ruthless = False
+                    continue
+                # Fall back to body content.
+                break
+
+        # Final fallback: return body content as-is.
+        body = self._soup.find("body")
+        if body is not None:
+            return body.to_html(), body.get_text(separator=" ", strip=True)
+        return "", ""
+
+    # ── Pre-cleaning ─────────────────────────────────────────────────────
+
+    def _pre_clean(self) -> None:
+        """Remove script, style, link and other non-content tags."""
+        for tag in list(self._soup.find_all(self._PRE_CLEAN_TAGS)):
+            tag.decompose()
+
+    # ── Metadata extraction ──────────────────────────────────────────────
+
+    def _extract_metadata(self, soup: Any) -> dict[str, str | None]:
+        """Extract article metadata from JSON-LD and ``<meta>`` tags.
+
+        Args:
+            soup: A parsed ``Soup`` instance (unmutated).
+
+        Returns:
+            Dict with keys: title, author, excerpt, site_name, published_time.
+        """
+        meta: dict[str, str | None] = {
+            "title": None,
+            "author": None,
+            "excerpt": None,
+            "site_name": None,
+            "published_time": None,
+        }
+
+        # 1. Try JSON-LD first (highest priority).
+        self._parse_jsonld(soup, meta)
+
+        # 2. Parse <meta> tags.
+        self._parse_meta_tags(soup, meta)
+
+        # 3. Title from <title> element (if not yet found).
+        if not meta["title"]:
+            title_tag = soup.find("title")
+            if title_tag:
+                meta["title"] = _normalize_spaces(title_tag.get_text())
+
+        # 4. Refine title by removing site name suffixes.
+        if meta["title"]:
+            meta["title"] = self._shorten_title(meta["title"])
+
+        return meta
+
+    def _parse_jsonld(self, soup: Any, meta: dict[str, str | None]) -> None:
+        """Extract metadata from ``<script type="application/ld+json">``."""
+        for script in soup.find_all("script", attrs={"type": "application/ld+json"}):
+            text = script.get_text()
+            if not text:
+                continue
+            try:
+                data = json.loads(text)
+            except (json.JSONDecodeError, ValueError):
+                continue
+
+            # Handle @graph arrays.
+            if isinstance(data, dict) and "@graph" in data:
+                graph = data["@graph"]
+                if isinstance(graph, list):
+                    for item in graph:
+                        if self._is_article_jsonld(item):
+                            data = item
+                            break
+                    else:
+                        continue
+
+            if not self._is_article_jsonld(data):
+                continue
+
+            if not meta["title"]:
+                meta["title"] = _str_or_none(data.get("headline")) or _str_or_none(
+                    data.get("name")
+                )
+            if not meta["author"]:
+                meta["author"] = self._extract_jsonld_author(data)
+            if not meta["excerpt"]:
+                meta["excerpt"] = _str_or_none(data.get("description"))
+            if not meta["published_time"]:
+                meta["published_time"] = _str_or_none(data.get("datePublished"))
+            if not meta["site_name"]:
+                publisher = data.get("publisher")
+                if isinstance(publisher, dict):
+                    meta["site_name"] = _str_or_none(publisher.get("name"))
+
+    @staticmethod
+    def _is_article_jsonld(data: Any) -> bool:
+        """Check if *data* is a Schema.org Article (or subtype)."""
+        if not isinstance(data, dict):
+            return False
+        schema_type = data.get("@type", "")
+        if isinstance(schema_type, list):
+            return any(t in JSONLD_ARTICLE_TYPES for t in schema_type)
+        return schema_type in JSONLD_ARTICLE_TYPES
+
+    @staticmethod
+    def _extract_jsonld_author(data: dict) -> str | None:
+        """Extract author name from JSON-LD, handling various formats."""
+        author = data.get("author")
+        if author is None:
+            return None
+        if isinstance(author, str):
+            return author
+        if isinstance(author, dict):
+            return _str_or_none(author.get("name"))
+        if isinstance(author, list):
+            names = []
+            for a in author:
+                if isinstance(a, str):
+                    names.append(a)
+                elif isinstance(a, dict) and "name" in a:
+                    names.append(a["name"])
+            return ", ".join(names) if names else None
+        return None
+
+    def _parse_meta_tags(self, soup: Any, meta: dict[str, str | None]) -> None:
+        """Extract metadata from ``<meta>`` tags (OpenGraph, DC, etc.)."""
+        # Mapping of meta property/name → target field + priority (lower wins).
+        property_map: dict[str, str] = {
+            "og:title": "title",
+            "og:description": "excerpt",
+            "og:site_name": "site_name",
+            "article:author": "author",
+            "article:published_time": "published_time",
+            "dc:title": "title",
+            "dc:creator": "author",
+            "dc:description": "excerpt",
+            "dcterm:title": "title",
+            "dcterm:creator": "author",
+            "dcterm:description": "excerpt",
+            "twitter:title": "title",
+            "twitter:description": "excerpt",
+        }
+        name_map: dict[str, str] = {
+            "author": "author",
+            "description": "excerpt",
+            "parsely-author": "author",
+            "parsely-pub-date": "published_time",
+            "parsely-title": "title",
+        }
+
+        for tag in soup.find_all("meta"):
+            content = tag.get("content", "")
+            if not content:
+                continue
+            content = _normalize_spaces(unescape(content))
+
+            prop = tag.get("property", "")
+            name = tag.get("name", "")
+
+            # Match by property attribute.
+            field = property_map.get(prop) or property_map.get(prop.lower())
+            if field and not meta[field]:
+                meta[field] = content
+                continue
+
+            # Match by name attribute.
+            field = name_map.get(name) or name_map.get(name.lower())
+            if field and not meta[field]:
+                meta[field] = content
+
+    @staticmethod
+    def _shorten_title(title: str) -> str:
+        """Remove site name suffixes/prefixes from *title*.
+
+        Handles patterns like ``"Article Title | Site Name"`` by
+        splitting on common separators and picking the most likely
+        article title part.
+        """
+        parts = TITLE_SEPARATORS_RE.split(title)
+        if len(parts) > 1:
+            # Heuristic: the longest part is usually the title, not
+            # the site name.  But if the longest part is very short
+            # (< 2 words) and it's not significantly longer than the
+            # second-longest, keep the original.
+            sorted_parts = sorted(parts, key=len, reverse=True)
+            best = sorted_parts[0]
+            second = sorted_parts[1] if len(sorted_parts) > 1 else ""
+            # Use the longest part if it's meaningfully longer than
+            # the second part, OR if the first/last part is clearly
+            # the title (common patterns).
+            if len(best) > len(second):
+                return best.strip()
+            # If parts are roughly equal length, use the first one
+            # (title typically comes first).
+            return parts[0].strip()
+
+        # Try colon separator.
+        if ": " in title:
+            colon_parts = title.split(": ")
+            # Use text after colon if before-colon is short.
+            if len(colon_parts[0].split()) <= 5:
+                return ": ".join(colon_parts[1:]).strip()
+
+        return title.strip()
+
+    # ── Language / direction detection ────────────────────────────────────
+
+    @staticmethod
+    def _detect_lang(soup: Any) -> str | None:
+        """Detect language from ``<html lang="...">``."""
+        html_tag = soup.find("html")
+        if html_tag is not None:
+            lang = html_tag.get("lang")
+            if lang:
+                return lang if isinstance(lang, str) else str(lang)
+        return None
+
+    @staticmethod
+    def _detect_dir(soup: Any) -> str | None:
+        """Detect text direction from ``dir`` attribute."""
+        for tag_name in ("html", "body"):
+            tag = soup.find(tag_name)
+            if tag is not None:
+                d = tag.get("dir")
+                if d and isinstance(d, str) and d.lower() in ("ltr", "rtl"):
+                    return d.lower()
+        return None
+
+    # ── Unlikely candidate removal ───────────────────────────────────────
+
+    def _remove_unlikely_candidates(self) -> None:
+        """Remove elements whose class/id suggests non-content."""
+        for tag in list(self._soup._all_descendants()):
+            if tag.name in ("html", "body"):
+                continue
+            class_id = _get_class_id_string(tag)
+            if len(class_id) <= 1:
+                continue
+            if UNLIKELY_CANDIDATES_RE.search(
+                class_id
+            ) and not OK_MAYBE_CANDIDATE_RE.search(class_id):
+                tag.decompose()
+
+    # ── Div-to-P transformation ──────────────────────────────────────────
+
+    def _transform_divs_to_paragraphs(self) -> None:
+        """Convert ``<div>`` elements without block children into ``<p>``."""
+        for div in list(self._soup.find_all("div")):
+            has_block = any(
+                isinstance(c, self._Tag) and c.name in BLOCK_LEVEL_TAGS
+                for c in div.children
+            )
+            if not has_block:
+                div.name = "p"
+
+    # ── Scoring ──────────────────────────────────────────────────────────
+
+    def _score_paragraphs(self) -> dict[int, dict[str, Any]]:
+        """Score paragraph-like nodes and propagate to ancestors.
+
+        Returns:
+            Dict mapping ``id(tag)`` → ``{"tag": tag, "score": float}``.
+        """
+        candidates: dict[int, dict[str, Any]] = {}
+
+        for tag in self._soup.find_all(list(TAGS_TO_SCORE)):
+            inner_text = _normalize_spaces(tag.get_text())
+            if len(inner_text) < MIN_PARAGRAPH_LENGTH:
+                continue
+
+            parent = tag.parent
+            grandparent = parent.parent if parent is not None else None
+
+            # Ensure parent is initialised.
+            if parent is not None and id(parent) not in candidates:
+                candidates[id(parent)] = {
+                    "tag": parent,
+                    "score": self._init_score(parent),
+                }
+            # Ensure grandparent is initialised.
+            if grandparent is not None and id(grandparent) not in candidates:
+                candidates[id(grandparent)] = {
+                    "tag": grandparent,
+                    "score": self._init_score(grandparent),
+                }
+
+            # Content score for this paragraph.
+            inner_len = len(inner_text)
+            content_score = 1.0
+            content_score += len(COMMAS_RE.findall(inner_text))
+            content_score += min(inner_len / 100.0, 3.0)
+
+            # Propagate to parent (full) and grandparent (half).
+            if parent is not None and id(parent) in candidates:
+                candidates[id(parent)]["score"] += content_score
+            if grandparent is not None and id(grandparent) in candidates:
+                candidates[id(grandparent)]["score"] += content_score / 2.0
+
+        # Scale scores by link density.
+        for entry in candidates.values():
+            ld = self._get_link_density(entry["tag"])
+            entry["score"] *= 1.0 - ld
+
+        return candidates
+
+    def _init_score(self, tag: Any) -> float:
+        """Compute initial score for a node based on tag name and class/id."""
+        score = float(TAG_WEIGHTS.get(tag.name, 0))
+        score += self._get_class_weight(tag)
+        return score
+
+    @staticmethod
+    def _get_class_weight(tag: Any) -> float:
+        """Return ±25 weight based on class and id attribute content."""
+        weight = 0.0
+        for attr in ("class", "id"):
+            value = tag.get(attr, "")
+            if isinstance(value, list):
+                value = " ".join(value)
+            if not value:
+                continue
+            if NEGATIVE_RE.search(value):
+                weight -= 25.0
+            if POSITIVE_RE.search(value):
+                weight += 25.0
+        return weight
+
+    @staticmethod
+    def _get_link_density(tag: Any) -> float:
+        """Ratio of link text length to total text length."""
+        total_len = _text_length(tag)
+        if total_len == 0:
+            return 0.0
+        link_len = sum(_text_length(a) for a in tag.find_all("a"))
+        return link_len / total_len
+
+    # ── Candidate selection ──────────────────────────────────────────────
+
+    @staticmethod
+    def _select_best_candidate(
+        candidates: dict[int, dict[str, Any]],
+    ) -> dict[str, Any] | None:
+        """Return the candidate with the highest score, or ``None``."""
+        if not candidates:
+            return None
+        return max(candidates.values(), key=lambda c: c["score"])
+
+    # ── Article assembly ─────────────────────────────────────────────────
+
+    def _get_article(
+        self, best: dict[str, Any], candidates: dict[int, dict[str, Any]]
+    ) -> Any:
+        """Build the article container from the best candidate + siblings.
+
+        Args:
+            best: The highest-scoring candidate dict.
+            candidates: All scored candidates.
+
+        Returns:
+            A new ``Tag`` containing the article content.
+        """
+        best_tag = best["tag"]
+        parent = best_tag.parent
+
+        # Create an article wrapper.
+        article = self._Tag("div")
+        sibling_threshold = max(10.0, best["score"] * 0.2)
+
+        # If there's no parent, use the candidate itself.
+        if parent is None:
+            article.append(best_tag.extract())
+            return article
+
+        for sibling in list(parent.children):
+            if isinstance(sibling, str):
+                if sibling.strip():
+                    article.append(sibling)
+                continue
+
+            should_include = False
+
+            if sibling is best_tag:
+                should_include = True
+            elif id(sibling) in candidates:
+                if candidates[id(sibling)]["score"] >= sibling_threshold:
+                    should_include = True
+            elif isinstance(sibling, self._Tag) and sibling.name == "p":
+                link_density = self._get_link_density(sibling)
+                text = _normalize_spaces(sibling.get_text())
+                text_len = len(text)
+                if text_len > 80 and link_density < 0.25:
+                    should_include = True
+                elif (
+                    text_len <= 80 and link_density == 0 and re.search(r"\.\s*$", text)
+                ):
+                    should_include = True
+
+            if should_include:
+                article.append(sibling.extract())
+
+        return article
+
+    # ── Sanitization ─────────────────────────────────────────────────────
+
+    _HEADING_TAGS_SET = frozenset({"h1", "h2", "h3", "h4", "h5", "h6"})
+    # Combined list of form-related + heading tags for single find_all pass.
+    _REMOVE_AND_HEADING_TAGS = list(REMOVE_TAGS | _HEADING_TAGS_SET)
+
+    def _sanitize(self, article: Any) -> None:
+        """Clean the extracted article of low-quality elements."""
+        # 1+2. Remove form-related elements and low-quality headings in
+        # a single find_all pass instead of two separate traversals.
+        for tag in list(article.find_all(self._REMOVE_AND_HEADING_TAGS)):
+            if tag.name in REMOVE_TAGS:
+                tag.decompose()
+            else:
+                # Heading tag — check quality.
+                if self._get_class_weight(tag) < 0:
+                    tag.decompose()
+                elif self._get_link_density(tag) > 0.33:
+                    tag.decompose()
+
+        # 3. Conditional cleanup of tables, divs, lists, etc. — single
+        # find_all with all candidate tags instead of per-tag-name loops.
+        self._clean_conditionally_all(article)
+
+        # 4. Remove empty tags.
+        self._remove_empty_tags(article)
+
+    _EMBED_TAGS = frozenset({"embed", "object", "iframe"})
+
+    @staticmethod
+    def _count_child_tags(tag: Any, embed_tags: frozenset[str]) -> tuple:
+        """Count p, img, li, input, and embed descendant tags in one pass.
+
+        Args:
+            tag: The parent element to inspect.
+            embed_tags: Frozenset of tag names considered "embed-like".
+
+        Returns:
+            ``(p_count, img_count, li_count, input_count, embed_count)``.
+        """
+        p_count = img_count = li_count = input_count = embed_count = 0
+        for desc in tag._all_descendants():
+            dname = desc.name
+            if dname == "p":
+                p_count += 1
+            elif dname == "img":
+                img_count += 1
+            elif dname == "li":
+                li_count += 1
+            elif dname == "input":
+                input_count += 1
+            elif dname in embed_tags:
+                embed_count += 1
+        return p_count, img_count, li_count, input_count, embed_count
+
+    @staticmethod
+    def _should_remove_conditionally(
+        tag_name: str,
+        class_weight: float,
+        content_len: int,
+        link_density: float,
+        p_count: int,
+        img_count: int,
+        li_count: int,
+        input_count: int,
+        embed_count: int,
+    ) -> bool:
+        """Decide whether a conditionally-cleaned element should be removed.
+
+        Args:
+            tag_name: The tag name being evaluated.
+            class_weight: CSS class/id weight for the element.
+            content_len: Length of normalised inner text.
+            link_density: Ratio of link text to total text.
+            p_count: Number of ``<p>`` descendants.
+            img_count: Number of ``<img>`` descendants.
+            li_count: Number of ``<li>`` descendants.
+            input_count: Number of ``<input>`` descendants.
+            embed_count: Number of embed-like descendants.
+
+        Returns:
+            ``True`` if the element should be removed.
+        """
+        if img_count > 1 and p_count > 0 and (p_count / img_count) < 0.5:
+            return True
+        if li_count > p_count and tag_name not in ("ol", "ul"):
+            return True
+        if input_count > p_count / 3:
+            return True
+        if content_len < MIN_PARAGRAPH_LENGTH and (img_count == 0 or img_count > 2):
+            return True
+        if class_weight < 25 and link_density > 0.2:
+            return True
+        if class_weight >= 25 and link_density > 0.5:
+            return True
+        if (embed_count == 1 and content_len < 75) or (
+            embed_count > 1 and content_len < 200
+        ):
+            return True
+        return False
+
+    _CLEAN_COND_TAGS_LIST = list(CLEAN_CONDITIONALLY_TAGS)
+
+    def _clean_conditionally_all(self, article: Any) -> None:
+        """Remove conditionally-cleaned elements in a single find_all pass."""
+        for tag in list(article.find_all(self._CLEAN_COND_TAGS_LIST)):
+            class_weight = self._get_class_weight(tag)
+            # Quick reject: very negative weight.
+            if class_weight < -25:
+                tag.decompose()
+                continue
+
+            inner_text = _normalize_spaces(tag.get_text())
+            comma_count = len(COMMAS_RE.findall(inner_text))
+
+            # Commas indicate content-rich nodes; keep them.
+            if comma_count >= 10:
+                continue
+
+            counts = self._count_child_tags(tag, self._EMBED_TAGS)
+            content_len = len(inner_text)
+            link_density = self._get_link_density(tag)
+
+            if self._should_remove_conditionally(
+                tag.name, class_weight, content_len, link_density, *counts
+            ):
+                tag.decompose()
+
+    @staticmethod
+    def _remove_empty_tags(article: Any) -> None:
+        """Remove tags that have no text content and no images/embeds."""
+        keep_tags = frozenset(
+            {"img", "br", "hr", "embed", "object", "iframe", "video", "audio"}
+        )
+        # Process in reverse document order (children before parents) so
+        # that a single pass is sufficient.
+        for tag in reversed(article._all_descendants()):
+            if tag.name in keep_tags:
+                continue
+            if not tag.children:
+                tag.decompose()
+            elif not tag.get_text(strip=True) and not tag.find_all(list(keep_tags)):
+                tag.decompose()
+
+    # ── Title fallback from headings ─────────────────────────────────────
+
+    @staticmethod
+    def _get_title_from_headings(soup: Any) -> str | None:
+        """Try to find a title from ``<h1>`` or ``<h2>`` headings."""
+        for level in ("h1", "h2"):
+            heading = soup.find(level)
+            if heading is not None:
+                text = _normalize_spaces(heading.get_text())
+                if text:
+                    return text
+        return None
+
+
+# ── Module-level helpers ─────────────────────────────────────────────────────
+
+
+def _str_or_none(value: Any) -> str | None:
+    """Return a non-empty stripped string or ``None``."""
+    if value is None:
+        return None
+    s = str(value).strip()
+    return s if s else None

src/veilrender/_vendor/retry.py

@@ -0,0 +1,503 @@
+# /// zerodep
+# version = "0.3.0"
+# deps = []
+# tier = "simple"
+# category = "process"
+# note = "Install/update via `zerodep add retry`"
+# ///
+
+"""Zero-dependency retry with configurable backoff strategies.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Decorator-based retry with exponential / linear / fixed backoff,
+jitter, exception and result filtering, and async support.
+
+Basic usage::
+
+    @retry(max_retries=3)
+    def call_api():
+        return get("https://api.example.com/data")
+
+Async usage::
+
+    @retry(max_retries=3, retry_on=(ConnectionError, TimeoutError))
+    async def call_api():
+        return await async_get("https://api.example.com/data")
+
+Imperative usage::
+
+    result = retry_call(call_api, max_retries=5)
+
+HTTP status filtering::
+
+    @retry(retry_on=retry_if_status(429, 502, 503))
+    def call_api():
+        resp = get("https://api.example.com/data")
+        resp.raise_for_status()
+        return resp
+"""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import functools
+import inspect
+import random
+import time
+from typing import Any, Callable
+
+__all__ = [
+    # Constants
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_BASE_DELAY",
+    "DEFAULT_MAX_DELAY",
+    "DEFAULT_BACKOFF_FACTOR",
+    # Exceptions
+    "RetryError",
+    # Data classes
+    "RetryState",
+    # Predicates
+    "retry_if_exception",
+    "retry_if_result",
+    "retry_if_status",
+    # Main API
+    "retry",
+    "retry_call",
+]
+
+# ── Defaults ──
+
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BASE_DELAY = 1.0
+DEFAULT_MAX_DELAY = 60.0
+DEFAULT_BACKOFF_FACTOR = 2.0
+
+
+# ── Exceptions ──
+
+
+class RetryError(Exception):
+    """Raised when all retry attempts are exhausted.
+
+    Attributes:
+        last_exception: The exception from the final attempt, or ``None``
+            if retries were triggered by result predicate.
+        attempts: Total number of calls made (initial + retries).
+    """
+
+    def __init__(self, last_exception: BaseException | None, attempts: int) -> None:
+        self.last_exception = last_exception
+        self.attempts = attempts
+        super().__init__(
+            f"Retry exhausted after {attempts} attempt(s)"
+            + (f": {last_exception}" if last_exception else "")
+        )
+
+
+# ── Retry State ──
+
+
+@dataclasses.dataclass
+class RetryState:
+    """Information about the current retry, passed to *on_retry* callback.
+
+    Attributes:
+        attempt: 1-based retry number (1 = first retry, not the initial call).
+        exception: The exception that triggered this retry, or ``None``.
+        result: The return value that triggered this retry, or ``None``.
+        delay: Seconds to sleep before the next attempt.
+        elapsed: Seconds elapsed since the initial call.
+    """
+
+    attempt: int
+    exception: BaseException | None
+    result: Any
+    delay: float
+    elapsed: float
+
+
+# ── Retry Condition Helpers ──
+
+
+def retry_if_exception(
+    *exc_types: type[BaseException],
+) -> Callable[[BaseException], bool]:
+    """Build a predicate that matches specific exception types.
+
+    Args:
+        *exc_types: Exception classes to retry on.
+
+    Returns:
+        A callable ``(exc) -> bool``.
+    """
+
+    def predicate(exc: BaseException) -> bool:
+        return isinstance(exc, exc_types)
+
+    return predicate
+
+
+def retry_if_result(predicate: Callable[[Any], bool]) -> Callable[[Any], bool]:
+    """Mark a callable as a result-retry predicate (identity helper).
+
+    Args:
+        predicate: A callable ``(result) -> bool`` returning ``True`` to retry.
+
+    Returns:
+        The same callable, for self-documenting call sites.
+    """
+    return predicate
+
+
+def retry_if_status(*status_codes: int) -> Callable[[BaseException], bool]:
+    """Build a predicate that retries on HTTP status codes.
+
+    Works with any exception carrying a ``status_code`` attribute
+    (e.g. ``httpclient.HTTPError``).
+
+    Args:
+        *status_codes: HTTP status codes to retry on (e.g. 429, 502, 503).
+
+    Returns:
+        A callable ``(exc) -> bool``.
+    """
+    codes = set(status_codes)
+
+    def predicate(exc: BaseException) -> bool:
+        sc = getattr(exc, "status_code", None)
+        return sc is not None and sc in codes
+
+    return predicate
+
+
+# ── Internal Helpers ──
+
+
+def _compute_delay(
+    attempt: int,
+    backoff: str,
+    base_delay: float,
+    backoff_factor: float,
+    max_delay: float,
+    jitter: str,
+) -> float:
+    """Compute the sleep duration for a given retry attempt.
+
+    Args:
+        attempt: 0-based retry index (0 = first retry).
+        backoff: Strategy name.
+        base_delay: Base delay in seconds.
+        backoff_factor: Multiplier for exponential backoff.
+        max_delay: Upper bound on delay.
+        jitter: Jitter mode.
+
+    Returns:
+        Sleep duration in seconds.
+
+    Raises:
+        ValueError: On unknown *backoff* or *jitter* value.
+    """
+    if backoff == "exponential":
+        delay = base_delay * (backoff_factor**attempt)
+    elif backoff == "linear":
+        delay = base_delay * (attempt + 1)
+    elif backoff == "fixed":
+        delay = base_delay
+    else:
+        raise ValueError(f"Unknown backoff strategy: {backoff!r}")
+
+    delay = min(delay, max_delay)
+
+    if jitter == "full":
+        delay = random.uniform(0, delay)
+    elif jitter == "equal":
+        half = delay / 2
+        delay = half + random.uniform(0, half)
+    elif jitter == "none":
+        pass
+    else:
+        raise ValueError(f"Unknown jitter mode: {jitter!r}")
+
+    return delay
+
+
+def _should_retry_exception(
+    exc: BaseException,
+    retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool],
+) -> bool:
+    """Check whether *exc* matches the retry condition."""
+    if isinstance(retry_on, tuple):
+        return isinstance(exc, retry_on)
+    return retry_on(exc)
+
+
+# ── Core Retry Loops ──
+
+
+def _retry_sync(
+    fn: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    *,
+    max_retries: int,
+    base_delay: float,
+    max_delay: float,
+    backoff: str,
+    backoff_factor: float,
+    jitter: str,
+    retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool],
+    retry_on_result: Callable[[Any], bool] | None,
+    on_retry: Callable[[RetryState], None] | None,
+) -> Any:
+    start = time.monotonic()
+
+    for attempt in range(max_retries + 1):  # 0 = initial call
+        try:
+            result = fn(*args, **kwargs)
+
+            if retry_on_result is not None and retry_on_result(result):
+                if attempt >= max_retries:
+                    raise RetryError(None, max_retries + 1)
+                delay = _compute_delay(
+                    attempt, backoff, base_delay, backoff_factor, max_delay, jitter
+                )
+                if on_retry:
+                    on_retry(
+                        RetryState(
+                            attempt=attempt + 1,
+                            exception=None,
+                            result=result,
+                            delay=delay,
+                            elapsed=time.monotonic() - start,
+                        )
+                    )
+                time.sleep(delay)
+                continue
+
+            return result
+
+        except BaseException as exc:
+            if not _should_retry_exception(exc, retry_on) or attempt >= max_retries:
+                raise
+
+            delay = _compute_delay(
+                attempt, backoff, base_delay, backoff_factor, max_delay, jitter
+            )
+            if on_retry:
+                on_retry(
+                    RetryState(
+                        attempt=attempt + 1,
+                        exception=exc,
+                        result=None,
+                        delay=delay,
+                        elapsed=time.monotonic() - start,
+                    )
+                )
+            time.sleep(delay)
+
+
+async def _retry_async(
+    fn: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    *,
+    max_retries: int,
+    base_delay: float,
+    max_delay: float,
+    backoff: str,
+    backoff_factor: float,
+    jitter: str,
+    retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool],
+    retry_on_result: Callable[[Any], bool] | None,
+    on_retry: Callable[[RetryState], None] | None,
+) -> Any:
+    start = time.monotonic()
+
+    for attempt in range(max_retries + 1):
+        try:
+            result = await fn(*args, **kwargs)
+
+            if retry_on_result is not None and retry_on_result(result):
+                if attempt >= max_retries:
+                    raise RetryError(None, max_retries + 1)
+                delay = _compute_delay(
+                    attempt, backoff, base_delay, backoff_factor, max_delay, jitter
+                )
+                if on_retry:
+                    on_retry(
+                        RetryState(
+                            attempt=attempt + 1,
+                            exception=None,
+                            result=result,
+                            delay=delay,
+                            elapsed=time.monotonic() - start,
+                        )
+                    )
+                await asyncio.sleep(delay)
+                continue
+
+            return result
+
+        except BaseException as exc:
+            if not _should_retry_exception(exc, retry_on) or attempt >= max_retries:
+                raise
+
+            delay = _compute_delay(
+                attempt, backoff, base_delay, backoff_factor, max_delay, jitter
+            )
+            if on_retry:
+                on_retry(
+                    RetryState(
+                        attempt=attempt + 1,
+                        exception=exc,
+                        result=None,
+                        delay=delay,
+                        elapsed=time.monotonic() - start,
+                    )
+                )
+            await asyncio.sleep(delay)
+
+
+# ── Public API ──
+
+
+def retry(
+    fn: Callable[..., Any] | None = None,
+    *,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    base_delay: float = DEFAULT_BASE_DELAY,
+    max_delay: float = DEFAULT_MAX_DELAY,
+    backoff: str = "exponential",
+    backoff_factor: float = DEFAULT_BACKOFF_FACTOR,
+    jitter: str = "full",
+    retry_on: tuple[type[BaseException], ...] | Callable[[BaseException], bool] = (
+        Exception,
+    ),
+    retry_on_result: Callable[[Any], bool] | None = None,
+    on_retry: Callable[[RetryState], None] | None = None,
+) -> Callable[..., Any]:
+    """Decorator that retries a function on failure with configurable backoff.
+
+    Can be used with or without arguments::
+
+        @retry
+        def f(): ...
+
+        @retry()
+        def g(): ...
+
+        @retry(max_retries=5, backoff="linear")
+        def h(): ...
+
+    Automatically detects async functions and uses ``asyncio.sleep``.
+
+    Args:
+        fn: The function to decorate (set automatically when used as
+            ``@retry`` without parentheses).
+        max_retries: Maximum number of retries (not counting the initial call).
+        base_delay: Base delay in seconds before the first retry.
+        max_delay: Upper bound on computed delay.
+        backoff: Backoff strategy — ``"exponential"``, ``"linear"``, or
+            ``"fixed"``.
+        backoff_factor: Multiplier for exponential backoff.
+        jitter: Jitter mode — ``"full"`` (uniform [0, delay]),
+            ``"equal"`` (delay/2 + uniform [0, delay/2]), or ``"none"``.
+        retry_on: Exception types or a callable ``(exc) -> bool`` deciding
+            whether to retry.  Defaults to ``(Exception,)``.
+        retry_on_result: Optional callable ``(result) -> bool``.  When it
+            returns ``True`` the call is retried.
+        on_retry: Optional callback invoked before each retry sleep with a
+            :class:`RetryState` instance.
+
+    Returns:
+        The decorated function (sync or async, matching the original).
+
+    Raises:
+        RetryError: When retries are exhausted due to *retry_on_result*.
+        The original exception: When retries are exhausted due to exceptions.
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                return await _retry_async(
+                    fn,
+                    args,
+                    kwargs,
+                    max_retries=max_retries,
+                    base_delay=base_delay,
+                    max_delay=max_delay,
+                    backoff=backoff,
+                    backoff_factor=backoff_factor,
+                    jitter=jitter,
+                    retry_on=retry_on,
+                    retry_on_result=retry_on_result,
+                    on_retry=on_retry,
+                )
+
+            return async_wrapper
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return _retry_sync(
+                fn,
+                args,
+                kwargs,
+                max_retries=max_retries,
+                base_delay=base_delay,
+                max_delay=max_delay,
+                backoff=backoff,
+                backoff_factor=backoff_factor,
+                jitter=jitter,
+                retry_on=retry_on,
+                retry_on_result=retry_on_result,
+                on_retry=on_retry,
+            )
+
+        return sync_wrapper
+
+    if fn is not None:
+        return decorator(fn)
+    return decorator
+
+
+def retry_call(
+    fn: Callable[..., Any],
+    args: tuple[Any, ...] = (),
+    kwargs: dict[str, Any] | None = None,
+    **retry_kwargs: Any,
+) -> Any:
+    """Call *fn* with retry logic without using a decorator.
+
+    Args:
+        fn: The callable to invoke.
+        args: Positional arguments for *fn*.
+        kwargs: Keyword arguments for *fn*.
+        **retry_kwargs: Same keyword arguments accepted by :func:`retry`.
+
+    Returns:
+        The return value of *fn* on success.
+    """
+    if kwargs is None:
+        kwargs = {}
+
+    opts: dict[str, Any] = dict(
+        max_retries=retry_kwargs.pop("max_retries", DEFAULT_MAX_RETRIES),
+        base_delay=retry_kwargs.pop("base_delay", DEFAULT_BASE_DELAY),
+        max_delay=retry_kwargs.pop("max_delay", DEFAULT_MAX_DELAY),
+        backoff=retry_kwargs.pop("backoff", "exponential"),
+        backoff_factor=retry_kwargs.pop("backoff_factor", DEFAULT_BACKOFF_FACTOR),
+        jitter=retry_kwargs.pop("jitter", "full"),
+        retry_on=retry_kwargs.pop("retry_on", (Exception,)),
+        retry_on_result=retry_kwargs.pop("retry_on_result", None),
+        on_retry=retry_kwargs.pop("on_retry", None),
+    )
+
+    if inspect.iscoroutinefunction(fn):
+        return _retry_async(fn, args, kwargs, **opts)
+    return _retry_sync(fn, args, kwargs, **opts)

src/veilrender/_vendor/soup.py

@@ -0,0 +1,998 @@
+# /// zerodep
+# version = "0.6.0"
+# deps = []
+# tier = "medium"
+# category = "text"
+# note = "Install/update via `zerodep add soup`"
+# ///
+
+"""HTML parser with BeautifulSoup-like API — zero-dep, stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Provides a lightweight DOM tree built on top of ``html.parser.HTMLParser``.
+Supports ``find``, ``find_all``, ``select``, ``select_one``, ``get_text``,
+``decompose``, and ``find_parent`` — the subset of BeautifulSoup used by
+the vast majority of real-world scraping scripts.
+
+Supports CSS pseudo-selectors: ``:first-child``, ``:last-child``,
+``:only-child``, and ``:not(selector)``.
+
+Does NOT implement: ``.prettify()``, ``.stripped_strings``, ``.descendants``
+iterator, ``.next_sibling`` / ``.previous_sibling``, ``NavigableString`` class,
+multiple parser backends.
+
+Example::
+
+    soup = Soup("<html><body><p class='msg'>Hello</p></body></html>")
+    print(soup.find("p", class_="msg").text)
+    # Hello
+"""
+
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+from typing import Any
+
+__all__ = [
+    "SELF_CLOSING_TAGS",
+    "Tag",
+    "Soup",
+]
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+SELF_CLOSING_TAGS = frozenset(
+    {
+        "area",
+        "base",
+        "br",
+        "col",
+        "embed",
+        "hr",
+        "img",
+        "input",
+        "link",
+        "meta",
+        "param",
+        "source",
+        "track",
+        "wbr",
+    }
+)
+
+# ── Tag ───────────────────────────────────────────────────────────────────────
+
+
+class Tag:
+    """A single HTML element node.
+
+    Attributes:
+        name: Tag name (e.g. ``"div"``).
+        attrs: Dictionary of attribute name to value.  The ``class`` attribute
+            is stored as a **list** of class names; all others as ``str``.
+        children: Ordered child nodes — either ``Tag`` or plain ``str``.
+        parent: Parent ``Tag``, or ``None`` for the root document.
+    """
+
+    __slots__ = ("name", "attrs", "children", "parent")
+
+    def __init__(
+        self,
+        name: str,
+        attrs: dict[str, str | list[str]] | None = None,
+        parent: Tag | None = None,
+    ) -> None:
+        self.name: str = name
+        self.attrs: dict[str, str | list[str]] = attrs if attrs is not None else {}
+        self.children: list[Tag | str] = []
+        self.parent: Tag | None = parent
+
+    # ── Attribute access ──────────────────────────────────────────────────
+
+    def get(self, attr: str, default: Any = None) -> Any:
+        """Return attribute value, or *default* if not present."""
+        return self.attrs.get(attr, default)
+
+    def __getitem__(self, attr: str) -> Any:
+        """Return attribute value; raise ``KeyError`` if missing."""
+        return self.attrs[attr]
+
+    def __contains__(self, attr: str) -> bool:
+        return attr in self.attrs
+
+    def __setitem__(self, attr: str, value: Any) -> None:
+        """Set an attribute value (e.g. ``tag['id'] = 'main'``)."""
+        self.attrs[attr] = value
+
+    def __delitem__(self, attr: str) -> None:
+        """Delete an attribute (e.g. ``del tag['id']``)."""
+        del self.attrs[attr]
+
+    # ── Text helpers ──────────────────────────────────────────────────────
+
+    @property
+    def text(self) -> str:
+        """Concatenated text content of this element and all descendants."""
+        return self.get_text()
+
+    @property
+    def string(self) -> str | None:
+        """If this element has exactly one text child (possibly nested), return it.
+
+        Returns ``None`` when the element has no children, multiple children,
+        or a mix of text and tags.
+        """
+        # Direct single-text child
+        if len(self.children) == 1:
+            child = self.children[0]
+            if isinstance(child, str):
+                return child
+            return child.string
+        # No children or multiple children -> None
+        return None
+
+    def get_text(self, separator: str = "", strip: bool = False) -> str:
+        """Return all text under this element concatenated.
+
+        Args:
+            separator: Inserted between text fragments.
+            strip: If ``True`` each fragment is whitespace-stripped and empty
+                fragments are dropped.
+
+        Returns:
+            The combined text.
+        """
+        parts: list[str] = []
+        self._collect_text(parts)
+        if strip:
+            parts = [p.strip() for p in parts]
+            parts = [p for p in parts if p]
+        return separator.join(parts)
+
+    def _collect_text(self, acc: list[str]) -> None:
+        for child in self.children:
+            if isinstance(child, str):
+                acc.append(child)
+            else:
+                child._collect_text(acc)
+
+    # ── Tree modification ─────────────────────────────────────────────────
+
+    def append(self, child: Tag | str) -> None:
+        """Append *child* to this element's children.
+
+        If *child* is a ``Tag`` already attached to a parent, it is first
+        detached from its old position.
+
+        Args:
+            child: A ``Tag`` or plain text string to append.
+        """
+        if isinstance(child, Tag):
+            if child.parent is not None:
+                try:
+                    child.parent.children.remove(child)
+                except ValueError:
+                    pass
+            child.parent = self
+        self.children.append(child)
+
+    def insert(self, index: int, child: Tag | str) -> None:
+        """Insert *child* at *index* in this element's children.
+
+        Args:
+            index: Position to insert at (same semantics as ``list.insert``).
+            child: A ``Tag`` or plain text string to insert.
+        """
+        if isinstance(child, Tag):
+            if child.parent is not None:
+                try:
+                    child.parent.children.remove(child)
+                except ValueError:
+                    pass
+            child.parent = self
+        self.children.insert(index, child)
+
+    def extract(self) -> Tag:
+        """Remove this element from its parent but keep its content intact.
+
+        Unlike ``decompose``, the element and its subtree remain usable
+        after extraction.
+
+        Returns:
+            This element (now detached).
+        """
+        if self.parent is not None:
+            try:
+                self.parent.children.remove(self)
+            except ValueError:
+                pass
+            self.parent = None
+        return self
+
+    def replace_with(self, new_node: Tag | str) -> Tag:
+        """Replace this element with *new_node* in the parent's children.
+
+        Args:
+            new_node: The replacement ``Tag`` or text string.
+
+        Returns:
+            This element (now detached).
+
+        Raises:
+            ValueError: If the element has no parent.
+        """
+        if self.parent is None:
+            raise ValueError("Cannot replace a detached element")
+        parent = self.parent
+        for i, child in enumerate(parent.children):
+            if child is self:
+                parent.children[i] = new_node
+                if isinstance(new_node, Tag):
+                    if new_node.parent is not None:
+                        try:
+                            new_node.parent.children.remove(new_node)
+                        except ValueError:
+                            pass
+                    new_node.parent = parent
+                self.parent = None
+                return self
+        raise ValueError("Element not found in parent's children")  # pragma: no cover
+
+    def unwrap(self) -> None:
+        """Remove this tag but keep its children (re-parent them).
+
+        The children are spliced into the parent's children list at the
+        position formerly occupied by this element.
+        """
+        if self.parent is None:
+            return
+        parent = self.parent
+        idx = next(i for i, c in enumerate(parent.children) if c is self)
+        # Splice children into parent at the position of this element.
+        for child in self.children:
+            if isinstance(child, Tag):
+                child.parent = parent
+        parent.children[idx : idx + 1] = self.children
+        self.children = []
+        self.parent = None
+
+    def decompose(self) -> None:
+        """Remove this element from its parent and discard its content."""
+        if self.parent is not None:
+            try:
+                self.parent.children.remove(self)
+            except ValueError:
+                pass
+            self.parent = None
+        self.children.clear()
+
+    # ── Searching ─────────────────────────────────────────────────────────
+
+    def find(
+        self,
+        name: str | list[str] | None = None,
+        attrs: dict[str, str | bool] | None = None,
+        *,
+        class_: str | None = None,
+        **kwargs: str | bool,
+    ) -> Tag | None:
+        """Return the first descendant matching the criteria, or ``None``.
+
+        Args:
+            name: Tag name(s) to match. ``None`` matches any tag.
+            attrs: Dict of attribute filters.
+            class_: Shorthand for ``attrs={"class": value}``.
+            **kwargs: Extra attribute filters (``href=True`` means *has* href).
+
+        Returns:
+            The first matching ``Tag``, or ``None``.
+        """
+        results = self.find_all(name, attrs, class_=class_, limit=1, **kwargs)
+        return results[0] if results else None
+
+    def find_all(
+        self,
+        name: str | list[str] | None = None,
+        attrs: dict[str, str | bool] | None = None,
+        *,
+        class_: str | None = None,
+        limit: int | None = None,
+        **kwargs: str | bool,
+    ) -> list[Tag]:
+        """Return all descendants matching the criteria.
+
+        Args:
+            name: Tag name(s) to match.
+            attrs: Dict of attribute filters.
+            class_: Shorthand for ``attrs={"class": value}``.
+            limit: Stop after finding this many results.
+            **kwargs: Extra attribute filters.
+
+        Returns:
+            A list of matching ``Tag`` objects.
+        """
+        merged = dict(attrs) if attrs else {}
+        if class_ is not None:
+            merged["class"] = class_
+        merged.update(kwargs)
+
+        # Fast path: name-only search with no attribute filters.
+        if not merged:
+            if isinstance(name, str):
+                results: list[Tag] = []
+                self._search_by_single_name(name, results, limit)
+                return results
+            if isinstance(name, list):
+                name_set: frozenset[str] = frozenset(name)
+                results = []
+                self._search_by_name_set(name_set, results, limit)
+                return results
+
+        if isinstance(name, list):
+            name_set = frozenset(name)
+        else:
+            name_set = None  # type: ignore[assignment]
+
+        results = []
+        self._search(name, name_set, merged, results, limit)
+        return results
+
+    def __call__(self, *args: Any, **kwargs: Any) -> list[Tag]:
+        """Calling a tag is equivalent to ``find_all``."""
+        return self.find_all(*args, **kwargs)
+
+    def _search(
+        self,
+        name: str | list[str] | None,
+        name_set: frozenset[str] | None,
+        attr_filters: dict[str, str | bool],
+        results: list[Tag],
+        limit: int | None,
+    ) -> None:
+        for child in self.children:
+            if limit is not None and len(results) >= limit:
+                return
+            if isinstance(child, Tag):
+                if _matches(child, name, name_set, attr_filters):
+                    results.append(child)
+                    if limit is not None and len(results) >= limit:
+                        return
+                child._search(name, name_set, attr_filters, results, limit)
+
+    def _search_by_name_set(
+        self,
+        name_set: frozenset[str],
+        results: list[Tag],
+        limit: int | None,
+    ) -> None:
+        """Fast path for searching by a set of tag names with no attr filters."""
+        for child in self.children:
+            if limit is not None and len(results) >= limit:
+                return
+            if isinstance(child, Tag):
+                if child.name in name_set:
+                    results.append(child)
+                    if limit is not None and len(results) >= limit:
+                        return
+                child._search_by_name_set(name_set, results, limit)
+
+    def _search_by_single_name(
+        self,
+        name: str,
+        results: list[Tag],
+        limit: int | None,
+    ) -> None:
+        """Fast path for searching by a single tag name with no attr filters."""
+        for child in self.children:
+            if limit is not None and len(results) >= limit:
+                return
+            if isinstance(child, Tag):
+                if child.name == name:
+                    results.append(child)
+                    if limit is not None and len(results) >= limit:
+                        return
+                child._search_by_single_name(name, results, limit)
+
+    # ── find_parent ───────────────────────────────────────────────────────
+
+    def find_parent(self, name: str | None = None) -> Tag | None:
+        """Walk up the tree and return the first ancestor matching *name*.
+
+        Args:
+            name: Tag name to match. ``None`` returns the immediate parent.
+
+        Returns:
+            The matching ancestor ``Tag``, or ``None``.
+        """
+        node = self.parent
+        if name is None:
+            return node
+        while node is not None:
+            if node.name == name:
+                return node
+            node = node.parent
+        return None
+
+    # ── CSS selectors ─────────────────────────────────────────────────────
+
+    def select(self, css_selector: str) -> list[Tag]:
+        """Return all descendants matching a CSS selector (simple subset).
+
+        Supported patterns: ``tag``, ``.class``, ``#id``, ``[attr]``,
+        ``[attr="value"]``, descendant (``a b``), child (``a > b``),
+        compound (``div.cls#id``), multiple classes (``div.a.b``).
+
+        Args:
+            css_selector: The CSS selector string.
+
+        Returns:
+            A list of matching ``Tag`` objects.
+        """
+        parts = _parse_selector(css_selector)
+        candidates: list[Tag] = self._all_descendants()
+        return [tag for tag in candidates if _selector_matches(tag, parts)]
+
+    def select_one(self, css_selector: str) -> Tag | None:
+        """Like ``select``, but return only the first match (or ``None``).
+
+        Args:
+            css_selector: The CSS selector string.
+
+        Returns:
+            The first matching ``Tag``, or ``None``.
+        """
+        parts = _parse_selector(css_selector)
+        for tag in self._all_descendants():
+            if _selector_matches(tag, parts):
+                return tag
+        return None
+
+    def _all_descendants(self) -> list[Tag]:
+        """Collect all descendant Tag nodes in document order."""
+        result: list[Tag] = []
+        self._collect_descendants(result)
+        return result
+
+    def _collect_descendants(self, acc: list[Tag]) -> None:
+        for child in self.children:
+            if isinstance(child, Tag):
+                acc.append(child)
+                child._collect_descendants(acc)
+
+    # ── Serialization ────────────────────────────────────────────────────
+
+    def to_html(self) -> str:
+        """Serialize this element and its descendants back to an HTML string.
+
+        Returns:
+            The HTML markup for this subtree.
+        """
+        parts: list[str] = []
+        self._serialize(parts)
+        return "".join(parts)
+
+    def _serialize(self, acc: list[str]) -> None:
+        """Recursively build HTML string pieces into *acc*."""
+        # Build opening tag
+        attr_parts: list[str] = []
+        for k, v in self.attrs.items():
+            if isinstance(v, list):
+                attr_parts.append(f'{k}="{" ".join(v)}"')
+            elif v == "":
+                attr_parts.append(k)
+            else:
+                attr_parts.append(f'{k}="{v}"')
+        attrs_str = (" " + " ".join(attr_parts)) if attr_parts else ""
+
+        if self.name.lower() in SELF_CLOSING_TAGS:
+            acc.append(f"<{self.name}{attrs_str}>")
+            return
+
+        acc.append(f"<{self.name}{attrs_str}>")
+        for child in self.children:
+            if isinstance(child, str):
+                acc.append(child)
+            else:
+                child._serialize(acc)
+        acc.append(f"</{self.name}>")
+
+    def __str__(self) -> str:
+        """Return the HTML serialization of this element."""
+        return self.to_html()
+
+    # ── Repr ──────────────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        attrs_str = ""
+        if self.attrs:
+            parts = []
+            for k, v in self.attrs.items():
+                if isinstance(v, list):
+                    parts.append(f'{k}="{" ".join(v)}"')
+                else:
+                    parts.append(f'{k}="{v}"')
+            attrs_str = " " + " ".join(parts)
+        return f"<{self.name}{attrs_str}>"
+
+
+# ── Match helpers ─────────────────────────────────────────────────────────────
+
+
+def _check_name_match(
+    tag: Tag,
+    name: str | list[str] | None,
+    name_set: frozenset[str] | None = None,
+) -> bool:
+    """Return True if *tag* satisfies the *name* filter."""
+    if name is None:
+        return True
+    if name_set is not None:
+        return tag.name in name_set
+    if isinstance(name, list):
+        return tag.name in name
+    return tag.name == name
+
+
+def _check_attr_filter(tag: Tag, key: str, expected: str | bool) -> bool:
+    """Return True if *tag* satisfies a single attribute filter."""
+    actual = tag.attrs.get(key)
+    if expected is True:
+        return actual is not None
+    if expected is False:
+        return actual is None
+    # Value comparison
+    if key == "class":
+        return _class_matches(actual, expected)
+    if actual is None:
+        return False
+    if isinstance(actual, list):
+        return expected in actual
+    return actual == expected
+
+
+def _matches(
+    tag: Tag,
+    name: str | list[str] | None,
+    name_set: frozenset[str] | None,
+    attr_filters: dict[str, str | bool],
+) -> bool:
+    """Check whether *tag* satisfies *name* and *attr_filters*."""
+    if not _check_name_match(tag, name, name_set):
+        return False
+    return all(_check_attr_filter(tag, k, v) for k, v in attr_filters.items())
+
+
+def _class_matches(actual: str | list[str] | None, expected: str) -> bool:
+    """Return True if *expected* class is present in *actual*.
+
+    *actual* may be a list (``["a", "b"]``) or ``None``.
+    *expected* is a single class name string.
+    """
+    if actual is None:
+        return False
+    if isinstance(actual, list):
+        return expected in actual
+    return actual == expected
+
+
+# ── CSS selector parser ───────────────────────────────────────────────────────
+
+# A parsed selector is a list of *steps*.  Each step is
+# ``(combinator, simple_selector_list)`` where combinator is one of
+# ``"descendant"`` or ``"child"`` (the first step has ``"descendant"`` as a
+# dummy).  A simple selector is a dict with optional keys ``tag``, ``id``,
+# ``classes``, ``attrs``.
+
+_SIMPLE_RE = re.compile(
+    r"""
+    (?P<tag>[a-zA-Z][a-zA-Z0-9-]*)     # tag name
+    |(?P<cls>\.[a-zA-Z_-][a-zA-Z0-9_-]*)  # .class
+    |(?P<id>\#[a-zA-Z_-][a-zA-Z0-9_-]*)   # #id
+    |(?P<attr>\[[^\]]+\])              # [attr] or [attr="val"]
+    |(?P<pseudo>:(?:first-child|last-child|only-child))  # structural pseudo
+    |(?P<not>:not\()                   # :not( — argument parsed separately
+    """,
+    re.VERBOSE,
+)
+
+_ATTR_RE = re.compile(
+    r"""
+    \[
+    \s*(?P<name>[a-zA-Z_-][a-zA-Z0-9_-]*)
+    (?:\s*=\s*["']?(?P<value>[^"'\]]*)["']?)?
+    \s*\]
+    """,
+    re.VERBOSE,
+)
+
+SelectorStep = tuple[str, dict[str, Any]]
+
+
+_WS = frozenset(" \t\n")
+
+
+def _skip_whitespace(selector: str, pos: int) -> int:
+    """Advance *pos* past any whitespace characters."""
+    while pos < len(selector) and selector[pos] in _WS:
+        pos += 1
+    return pos
+
+
+def _tokenize_whitespace(
+    selector: str, pos: int, tokens: list[str | dict[str, Any]]
+) -> int:
+    """Handle whitespace at *pos*, emitting a combinator token if needed.
+
+    Returns the updated position.
+    """
+    rest = selector[pos:].lstrip()
+    if rest.startswith(">"):
+        tokens.append(">")
+        pos = selector.index(">", pos) + 1
+        return _skip_whitespace(selector, pos)
+    # Space combinator only if the previous token is not already a combinator
+    if tokens and tokens[-1] not in (" ", ">"):
+        tokens.append(" ")
+    return pos + 1
+
+
+def _apply_regex_match(m: re.Match[str], compound: dict[str, Any]) -> None:
+    """Populate *compound* dict from a single ``_SIMPLE_RE`` match."""
+    if m.group("tag"):
+        compound["tag"] = m.group("tag")
+    elif m.group("cls"):
+        compound.setdefault("classes", []).append(m.group("cls")[1:])
+    elif m.group("id"):
+        compound["id"] = m.group("id")[1:]
+    elif m.group("attr"):
+        am = _ATTR_RE.match(m.group("attr"))
+        if am:
+            compound.setdefault("attrs", []).append(
+                (am.group("name"), am.group("value"))
+            )
+    elif m.group("pseudo"):
+        compound.setdefault("pseudos", []).append(m.group("pseudo")[1:])
+
+
+def _parse_not_argument(selector: str, pos: int) -> tuple[dict[str, Any], int]:
+    """Parse the simple selector inside ``:not(...)``, return (inner, new_pos).
+
+    *pos* should point right after the opening ``(``.  The closing ``)`` is
+    consumed and *new_pos* points past it.
+    """
+    inner, pos = _parse_compound(selector, pos)
+    if inner is None:
+        inner = {}
+    pos = _skip_whitespace(selector, pos)
+    if pos < len(selector) and selector[pos] == ")":
+        pos += 1
+    return inner, pos
+
+
+def _parse_compound(selector: str, pos: int) -> tuple[dict[str, Any] | None, int]:
+    """Parse a compound simple selector starting at *pos*.
+
+    Returns ``(compound_dict_or_None, new_pos)``.
+    """
+    compound: dict[str, Any] = {}
+    matched_any = False
+    while pos < len(selector):
+        m = _SIMPLE_RE.match(selector, pos)
+        if m is None:
+            break
+        matched_any = True
+        if m.group("not"):
+            # :not( matched — parse the inner selector and closing paren
+            pos = m.end()
+            inner, pos = _parse_not_argument(selector, pos)
+            compound.setdefault("nots", []).append(inner)
+        else:
+            _apply_regex_match(m, compound)
+            pos = m.end()
+    return (compound if matched_any else None), pos
+
+
+def _tokens_to_steps(tokens: list[str | dict[str, Any]]) -> list[SelectorStep]:
+    """Convert a flat token list into ``(combinator, simple)`` step list."""
+    steps: list[SelectorStep] = []
+    combinator = "descendant"
+    for tok in tokens:
+        if tok == " ":
+            combinator = "descendant"
+        elif tok == ">":
+            combinator = "child"
+        else:
+            assert isinstance(tok, dict)
+            steps.append((combinator, tok))
+            combinator = "descendant"
+    return steps
+
+
+def _parse_selector(selector: str) -> list[SelectorStep]:
+    """Parse a simple CSS selector string into step list.
+
+    Returns a list of ``(combinator, simple)`` tuples.
+    """
+    tokens: list[str | dict[str, Any]] = []
+    pos = 0
+    selector = selector.strip()
+
+    while pos < len(selector):
+        if selector[pos] in _WS:
+            pos = _tokenize_whitespace(selector, pos, tokens)
+            continue
+
+        if selector[pos] == ">":
+            tokens.append(">")
+            pos = _skip_whitespace(selector, pos + 1)
+            continue
+
+        compound, pos = _parse_compound(selector, pos)
+        if compound is not None:
+            tokens.append(compound)
+        else:
+            pos += 1  # skip unknown character to avoid infinite loop
+
+    return _tokens_to_steps(tokens)
+
+
+def _classes_match(tag: Tag, required_classes: list[str]) -> bool:
+    """Return True if *tag* has all *required_classes*."""
+    tag_classes = tag.attrs.get("class")
+    if tag_classes is None:
+        return False
+    if isinstance(tag_classes, str):
+        tag_classes = [tag_classes]
+    return all(cls in tag_classes for cls in required_classes)
+
+
+def _attr_value_matches(actual: str | list[str], expected: str) -> bool:
+    """Return True if *actual* attribute value equals *expected*."""
+    if isinstance(actual, list):
+        return expected in actual
+    return actual == expected
+
+
+def _selector_attrs_match(tag: Tag, attrs: list[tuple[str, str | None]]) -> bool:
+    """Return True if *tag* satisfies all attribute constraints from a selector."""
+    for attr_name, attr_val in attrs:
+        actual = tag.attrs.get(attr_name)
+        if actual is None:
+            return False
+        if attr_val is not None and not _attr_value_matches(actual, attr_val):
+            return False
+    return True
+
+
+def _element_siblings(tag: Tag) -> list[Tag]:
+    """Return element (non-text) children of *tag*'s parent."""
+    if tag.parent is None:
+        return [tag]
+    return [c for c in tag.parent.children if isinstance(c, Tag)]
+
+
+def _pseudo_matches(tag: Tag, pseudo: str) -> bool:
+    """Return True if *tag* satisfies the structural pseudo-class *pseudo*."""
+    siblings = _element_siblings(tag)
+    if pseudo == "first-child":
+        return siblings[0] is tag
+    if pseudo == "last-child":
+        return siblings[-1] is tag
+    if pseudo == "only-child":
+        return len(siblings) == 1
+    return False  # pragma: no cover
+
+
+def _simple_matches(tag: Tag, simple: dict[str, Any]) -> bool:
+    """Check if *tag* matches a single compound simple selector."""
+    if "tag" in simple and tag.name != simple["tag"]:
+        return False
+    if "id" in simple and tag.attrs.get("id") != simple["id"]:
+        return False
+    if "classes" in simple and not _classes_match(tag, simple["classes"]):
+        return False
+    if "attrs" in simple and not _selector_attrs_match(tag, simple["attrs"]):
+        return False
+    if "pseudos" in simple:
+        for pseudo in simple["pseudos"]:
+            if not _pseudo_matches(tag, pseudo):
+                return False
+    if "nots" in simple:
+        for inner in simple["nots"]:
+            if _simple_matches(tag, inner):
+                return False
+    return True
+
+
+def _selector_matches(tag: Tag, steps: list[SelectorStep]) -> bool:
+    """Return ``True`` if *tag* matches the full parsed selector."""
+    if not steps:
+        return True
+
+    # The last step must match the tag itself.
+    combinator, simple = steps[-1]
+    if not _simple_matches(tag, simple):
+        return False
+
+    if len(steps) == 1:
+        return True
+
+    # Walk remaining steps backwards up the tree.
+    remaining = steps[:-1]
+    return _ancestor_matches(tag, remaining)
+
+
+def _ancestor_matches(tag: Tag, steps: list[SelectorStep]) -> bool:
+    """Verify that ancestors of *tag* satisfy the remaining selector steps."""
+    if not steps:
+        return True
+
+    combinator, simple = steps[-1]
+    rest = steps[:-1]
+
+    if combinator == "child":
+        parent = tag.parent
+        if parent is None or not _simple_matches(parent, simple):
+            return False
+        return _ancestor_matches(parent, rest)
+    else:
+        # descendant — walk up until we find a match
+        node = tag.parent
+        while node is not None:
+            if _simple_matches(node, simple):
+                if _ancestor_matches(node, rest):
+                    return True
+            node = node.parent
+        return False
+
+
+# ── HTML parser ───────────────────────────────────────────────────────────────
+
+
+class _TreeBuilder(HTMLParser):
+    """Build a ``Tag`` tree from HTML markup.
+
+    Args:
+        skip_tags: Optional frozenset of tag names to omit from the tree.
+            When a skipped tag is encountered, it and all its descendants
+            (including text) are silently discarded.
+    """
+
+    def __init__(self, skip_tags: frozenset[str] | None = None) -> None:
+        super().__init__(convert_charrefs=True)
+        self.root = Tag("[document]")
+        self.current: Tag = self.root
+        self._skip_tags: frozenset[str] = skip_tags or frozenset()
+        # Depth counter for nested skipped tags (> 0 means discarding).
+        self._skip_depth: int = 0
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        # If we're inside a skipped subtree, track nesting depth only.
+        if self._skip_depth > 0:
+            if tag not in SELF_CLOSING_TAGS:
+                self._skip_depth += 1
+            return
+
+        # Check if this tag should be skipped.
+        if tag in self._skip_tags:
+            if tag not in SELF_CLOSING_TAGS:
+                self._skip_depth = 1
+            return
+
+        attr_dict: dict[str, str | list[str]] = {}
+        for key, value in attrs:
+            if value is None:
+                value = ""
+            if key == "class":
+                attr_dict["class"] = value.split()
+            else:
+                attr_dict[key] = value
+
+        node = Tag(tag, attr_dict, parent=self.current)
+        self.current.children.append(node)
+
+        if tag not in SELF_CLOSING_TAGS:
+            self.current = node
+
+    def handle_endtag(self, tag: str) -> None:
+        # If we're inside a skipped subtree, decrement depth.
+        if self._skip_depth > 0:
+            self._skip_depth -= 1
+            return
+
+        # Walk up to find the matching open tag (tolerates malformed HTML)
+        node = self.current
+        while node is not None and node.name != tag:
+            node = node.parent
+        if node is not None and node.parent is not None:
+            self.current = node.parent
+        # If no matching open tag found, do nothing (malformed HTML tolerance)
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        # Explicit self-closing tag like <br/>
+        if self._skip_depth > 0 or tag in self._skip_tags:
+            return
+        self.handle_starttag(tag, attrs)
+        # Don't descend into it — it has no children.  If handle_starttag
+        # pushed current down, pop back up.
+        if self.current.name == tag:
+            if self.current.parent is not None:
+                self.current = self.current.parent
+
+    def handle_data(self, data: str) -> None:
+        if self._skip_depth > 0:
+            return
+        self.current.children.append(data)
+
+    def handle_comment(self, data: str) -> None:
+        # Comments are silently dropped (matching BS4 default).
+        pass
+
+
+# ── Soup (document root) ─────────────────────────────────────────────────────
+
+
+class Soup(Tag):
+    """Parse an HTML document and provide a BeautifulSoup-like API.
+
+    Args:
+        markup: The HTML string to parse.
+        parser: Ignored (present only for API compatibility with BS4).
+            Only ``"html.parser"`` is supported.
+        skip_tags: Optional frozenset of tag names to omit during parsing.
+            Skipped tags and all their descendants are silently discarded,
+            which can significantly speed up parsing of pages with many
+            ``<script>`` or ``<style>`` blocks.
+
+    Example::
+
+        soup = Soup("<p>Hello <b>world</b></p>")
+        print(soup.find("b").text)
+        # world
+    """
+
+    def __init__(
+        self,
+        markup: str,
+        parser: str = "html.parser",
+        skip_tags: frozenset[str] | None = None,
+    ) -> None:
+        super().__init__("[document]")
+        builder = _TreeBuilder(skip_tags=skip_tags)
+        builder.feed(markup)
+        # Adopt the root's children as our own.
+        self.children = builder.root.children
+        for child in self.children:
+            if isinstance(child, Tag):
+                child.parent = self
+
+    def new_tag(
+        self, name: str, attrs: dict[str, str | list[str]] | None = None
+    ) -> Tag:
+        """Create a new detached ``Tag`` (not yet in the tree).
+
+        Args:
+            name: Tag name (e.g. ``"p"``).
+            attrs: Optional attribute dictionary.
+
+        Returns:
+            A new ``Tag`` instance with no parent.
+        """
+        return Tag(name, attrs)
+
+    def to_html(self) -> str:
+        """Serialize the entire document back to an HTML string.
+
+        Returns:
+            The HTML markup for the whole document.
+        """
+        parts: list[str] = []
+        for child in self.children:
+            if isinstance(child, str):
+                parts.append(child)
+            else:
+                child._serialize(parts)
+        return "".join(parts)

src/veilrender/_vendor/structlog.py

@@ -0,0 +1,888 @@
+# /// zerodep
+# version = "0.3.0"
+# deps = []
+# tier = "medium"
+# category = "devtools"
+# note = "Install/update via `zerodep add structlog`"
+# ///
+
+"""Zero-dependency structured logging with pretty console output.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Structured logging library inspired by structlog, with a loguru-style
+colored console renderer.  Provides bound loggers with context propagation,
+a processor pipeline, and multiple output renderers (console, JSON, key-value).
+
+Quick start (pretty console output, zero config)::
+
+    from structlog import get_logger
+    logger = get_logger()
+    logger.info("server started", host="0.0.0.0", port=8080)
+
+Bound logger (context propagation)::
+
+    log = get_logger().bind(request_id="abc-123")
+    log.info("handling request")
+    log = log.bind(user_id=42)
+    log.info("authenticated")
+
+One-call setup with stdlib integration::
+
+    from structlog import setup_logging
+    logger = setup_logging(level="DEBUG", renderer="json")
+    logger.info("structured", key="value")
+
+Custom processor pipeline::
+
+    from structlog import configure, add_log_level, TimeStamper, JSONRenderer
+    configure(processors=[add_log_level, TimeStamper(), JSONRenderer()])
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime
+import json as _json
+import logging
+import os
+import sys
+import traceback
+from typing import IO, Any, Callable
+
+__all__ = [
+    # Type aliases
+    "EventDict",
+    "Processor",
+    "LoggerFactory",
+    # Exceptions
+    "DropEvent",
+    # Logger factories
+    "PrintLogger",
+    "PrintLoggerFactory",
+    "StdlibLoggerFactory",
+    # Processors
+    "add_log_level",
+    "add_logger_name",
+    "TimeStamper",
+    "format_exc_info",
+    # Renderers
+    "KeyValueRenderer",
+    "JSONRenderer",
+    "ConsoleRenderer",
+    # Bound logger
+    "BoundLogger",
+    # Configuration
+    "configure",
+    "reset_defaults",
+    "get_config",
+    "get_logger",
+    "wrap_logger",
+    # Setup helper
+    "setup_logging",
+    # Utilities
+    "truncate_string",
+    "truncate_base64",
+]
+
+# ── Type Aliases ─────────────────────────────────────────────────────────────
+
+EventDict = dict[str, Any]
+"""A log event dictionary passed through the processor pipeline."""
+
+Processor = Callable[[Any, str, EventDict], EventDict | str]
+"""Signature: (logger, method_name, event_dict) -> event_dict or rendered str."""
+
+LoggerFactory = Callable[..., Any]
+"""Callable that creates an underlying logger instance."""
+
+
+# ── Exceptions ───────────────────────────────────────────────────────────────
+
+
+class DropEvent(Exception):
+    """Raise inside a processor to silently discard the current log event."""
+
+
+# ── Level Mapping ────────────────────────────────────────────────────────────
+
+_NAME_TO_LEVEL: dict[str, int] = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+    "warn": logging.WARNING,
+    "error": logging.ERROR,
+    "critical": logging.CRITICAL,
+    "fatal": logging.CRITICAL,
+    "exception": logging.ERROR,
+}
+
+_LEVEL_TO_NAME: dict[int, str] = {
+    logging.DEBUG: "debug",
+    logging.INFO: "info",
+    logging.WARNING: "warning",
+    logging.ERROR: "error",
+    logging.CRITICAL: "critical",
+}
+
+
+# ── ANSI Colors ──────────────────────────────────────────────────────────────
+
+
+class _Colors:
+    """ANSI escape codes for terminal colorization."""
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    ITALIC = "\033[3m"
+    UNDERLINE = "\033[4m"
+    STRIKETHROUGH = "\033[9m"
+
+    BLACK = "\033[30m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    WHITE = "\033[37m"
+
+    BRIGHT_BLACK = "\033[90m"
+    BRIGHT_RED = "\033[91m"
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_MAGENTA = "\033[95m"
+    BRIGHT_CYAN = "\033[96m"
+    BRIGHT_WHITE = "\033[97m"
+
+
+_LEVEL_STYLES: dict[str, str] = {
+    "debug": _Colors.BLUE,
+    "info": _Colors.BRIGHT_WHITE,
+    "warning": _Colors.YELLOW,
+    "warn": _Colors.YELLOW,
+    "error": _Colors.RED,
+    "critical": _Colors.BRIGHT_RED + _Colors.BOLD,
+    "fatal": _Colors.BRIGHT_RED + _Colors.BOLD,
+    "exception": _Colors.RED,
+}
+
+_LEVEL_LABEL_STYLES: dict[str, str] = {
+    "debug": _Colors.CYAN,
+    "info": _Colors.GREEN,
+    "warning": _Colors.YELLOW,
+    "warn": _Colors.YELLOW,
+    "error": _Colors.RED,
+    "critical": _Colors.BRIGHT_RED + _Colors.BOLD,
+    "fatal": _Colors.BRIGHT_RED + _Colors.BOLD,
+    "exception": _Colors.RED,
+}
+
+_LEVEL_LABELS: dict[str, str] = {
+    "debug": "DEBUG   ",
+    "info": "INFO    ",
+    "warning": "WARNING ",
+    "warn": "WARNING ",
+    "error": "ERROR   ",
+    "critical": "CRITICAL",
+    "fatal": "FATAL   ",
+    "exception": "ERROR   ",
+}
+
+
+def _supports_color(stream: Any = None) -> bool:
+    """Check if the output stream supports ANSI color codes.
+
+    Respects the ``FORCE_COLOR`` and ``NO_COLOR`` environment variables
+    (see https://force-color.org/ and https://no-color.org/).
+
+    Args:
+        stream: The output stream to check.  Defaults to ``sys.stderr``.
+
+    Returns:
+        True if the stream is a color-capable terminal.
+    """
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    if os.environ.get("NO_COLOR"):
+        return False
+    s = stream or sys.stderr
+    if not hasattr(s, "isatty") or not s.isatty():
+        return False
+    if os.environ.get("TERM", "") == "dumb":
+        return False
+    return True
+
+
+# ── Logger Factories ─────────────────────────────────────────────────────────
+
+
+class PrintLogger:
+    """Minimal logger that writes to a file handle via ``print()``.
+
+    This is the default underlying logger.  It has no filtering, no
+    handler chain -- just ``print()`` to the configured stream.
+
+    Args:
+        file: Output stream.  Defaults to ``sys.stderr``.
+    """
+
+    def __init__(self, file: IO[str] | None = None) -> None:
+        self._file = file or sys.stderr
+        self._write = self._file.write
+        self._flush = self._file.flush
+
+    def msg(self, message: str) -> None:
+        """Write *message* followed by a newline."""
+        self._write(message + "\n")
+        self._flush()
+
+    debug = info = warning = warn = error = critical = fatal = msg
+
+
+class PrintLoggerFactory:
+    """Factory that creates :class:`PrintLogger` instances.
+
+    Args:
+        file: Output stream passed to each ``PrintLogger``.
+    """
+
+    def __init__(self, file: IO[str] | None = None) -> None:
+        self._file = file
+
+    def __call__(self, *args: Any) -> PrintLogger:
+        return PrintLogger(file=self._file)
+
+
+class StdlibLoggerFactory:
+    """Factory that returns a :class:`logging.Logger` from the stdlib.
+
+    Args:
+        name: Logger name passed to ``logging.getLogger()``.
+            If *None*, uses the root logger.
+    """
+
+    def __init__(self, name: str | None = None) -> None:
+        self._name = name
+
+    def __call__(self, *args: Any) -> logging.Logger:
+        if args:
+            return logging.getLogger(args[0])
+        return logging.getLogger(self._name)
+
+
+# ── Built-in Processors ──────────────────────────────────────────────────────
+
+
+def add_log_level(logger: Any, method_name: str, event_dict: EventDict) -> EventDict:
+    """Add ``level`` key derived from the log method name.
+
+    Example:
+        ``logger.info(...)`` -> ``event_dict["level"] = "info"``
+    """
+    event_dict["level"] = method_name
+    return event_dict
+
+
+def add_logger_name(logger: Any, method_name: str, event_dict: EventDict) -> EventDict:
+    """Add ``logger`` key from the underlying logger's name."""
+    name = getattr(logger, "name", None) or ""
+    event_dict["logger"] = name
+    return event_dict
+
+
+class TimeStamper:
+    """Processor that adds a timestamp to the event dict.
+
+    Args:
+        fmt: Timestamp format.  ``"iso"`` for ISO 8601, ``None`` for a
+            UNIX float, or a :func:`~datetime.datetime.strftime` format
+            string.  Defaults to ``"iso"``.
+        utc: If *True*, use UTC; otherwise local time.
+        key: Dict key for the timestamp.  Defaults to ``"timestamp"``.
+    """
+
+    __slots__ = ("_fmt", "_utc", "_key")
+
+    def __init__(
+        self,
+        fmt: str | None = "iso",
+        utc: bool = True,
+        key: str = "timestamp",
+    ) -> None:
+        self._fmt = fmt
+        self._utc = utc
+        self._key = key
+
+    def __call__(
+        self, logger: Any, method_name: str, event_dict: EventDict
+    ) -> EventDict:
+        now = (
+            datetime.datetime.now(datetime.timezone.utc)
+            if self._utc
+            else datetime.datetime.now()
+        )
+        if self._fmt is None:
+            event_dict[self._key] = now.timestamp()
+        elif self._fmt == "iso":
+            event_dict[self._key] = now.isoformat()
+        else:
+            event_dict[self._key] = now.strftime(self._fmt)
+        return event_dict
+
+
+def format_exc_info(logger: Any, method_name: str, event_dict: EventDict) -> EventDict:
+    """Replace ``exc_info`` with a formatted ``exception`` string.
+
+    If ``exc_info`` is *True*, captures the current exception via
+    :func:`sys.exc_info`.  If it is an exception tuple, formats it
+    directly.  The ``exc_info`` key is removed and replaced with
+    ``exception``.
+    """
+    exc_info = event_dict.pop("exc_info", None)
+    if exc_info is None or exc_info is False:
+        return event_dict
+
+    if exc_info is True:
+        exc_info = sys.exc_info()
+
+    if isinstance(exc_info, BaseException):
+        exc_info = (type(exc_info), exc_info, exc_info.__traceback__)
+
+    if isinstance(exc_info, tuple) and exc_info[0] is not None:
+        event_dict["exception"] = "".join(
+            traceback.format_exception(*exc_info)
+        ).rstrip()
+
+    return event_dict
+
+
+# ── Renderers (final processors) ─────────────────────────────────────────────
+
+
+class KeyValueRenderer:
+    """Render the event dict as ``key=value`` pairs.
+
+    Args:
+        key_order: Keys to render first, in this order.
+        sort_keys: Sort remaining keys alphabetically.
+        drop_missing: Skip *key_order* keys that are absent from the dict.
+    """
+
+    __slots__ = ("_key_order", "_sort_keys", "_drop_missing")
+
+    def __init__(
+        self,
+        key_order: list[str] | None = None,
+        sort_keys: bool = False,
+        drop_missing: bool = True,
+    ) -> None:
+        self._key_order = key_order or []
+        self._sort_keys = sort_keys
+        self._drop_missing = drop_missing
+
+    def __call__(self, logger: Any, method_name: str, event_dict: EventDict) -> str:
+        ordered: list[tuple[str, Any]] = []
+        remaining = dict(event_dict)
+
+        for key in self._key_order:
+            if key in remaining:
+                ordered.append((key, remaining.pop(key)))
+            elif not self._drop_missing:
+                ordered.append((key, None))
+
+        rest = sorted(remaining.items()) if self._sort_keys else list(remaining.items())
+        ordered.extend(rest)
+
+        parts = [
+            f"{k}={v!r}" if not isinstance(v, str) else f"{k}={v}" for k, v in ordered
+        ]
+        return " ".join(parts)
+
+
+class JSONRenderer:
+    """Render the event dict as a JSON string.
+
+    Args:
+        serializer: JSON serialization function.  Defaults to
+            :func:`json.dumps`.
+        **dumps_kw: Extra keyword arguments passed to *serializer*.
+    """
+
+    __slots__ = ("_serializer", "_dumps_kw")
+
+    def __init__(
+        self,
+        serializer: Callable[..., str] = _json.dumps,
+        **dumps_kw: Any,
+    ) -> None:
+        self._serializer = serializer
+        self._dumps_kw = dumps_kw
+        if "default" not in self._dumps_kw:
+            self._dumps_kw["default"] = _json_default
+
+    def __call__(self, logger: Any, method_name: str, event_dict: EventDict) -> str:
+        return self._serializer(event_dict, **self._dumps_kw)
+
+
+def _json_default(obj: Any) -> Any:
+    """Fallback serializer for objects that ``json.dumps`` cannot handle."""
+    if isinstance(obj, datetime.datetime):
+        return obj.isoformat()
+    if isinstance(obj, datetime.date):
+        return obj.isoformat()
+    if isinstance(obj, set | frozenset):
+        return sorted(obj, key=str)
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", errors="replace")
+    return str(obj)
+
+
+class ConsoleRenderer:
+    """Render the event dict as colorized, loguru-style console output.
+
+    Output format::
+
+        2026-03-27 14:30:00.123 | INFO     | event message    key=val key=val
+
+    Args:
+        colors: Enable ANSI color codes.  *None* auto-detects terminal
+            support.
+        pad_event: Pad the event field to this width for alignment.
+        level_styles: Override per-level ANSI color strings.
+    """
+
+    __slots__ = ("_colors", "_pad_event", "_level_styles")
+
+    def __init__(
+        self,
+        colors: bool | None = None,
+        pad_event: int = 30,
+        level_styles: dict[str, str] | None = None,
+    ) -> None:
+        self._colors = _supports_color() if colors is None else colors
+        self._pad_event = pad_event
+        self._level_styles = level_styles or _LEVEL_STYLES
+
+    def __call__(self, logger: Any, method_name: str, event_dict: EventDict) -> str:
+        # Extract well-known keys
+        event = str(event_dict.pop("event", ""))
+        level = event_dict.pop("level", method_name)
+        timestamp = event_dict.pop("timestamp", None)
+        event_dict.pop("logger", None)
+        exception = event_dict.pop("exception", None)
+
+        # Build timestamp string
+        if timestamp is None:
+            now = datetime.datetime.now()
+            ms = now.microsecond // 1000
+            ts_str = now.strftime("%Y-%m-%d %H:%M:%S.") + f"{ms:03d}"
+        elif isinstance(timestamp, str):
+            # Try to format ISO timestamps more compactly
+            ts_str = _compact_iso(timestamp)
+        elif isinstance(timestamp, float):
+            dt = datetime.datetime.fromtimestamp(timestamp)
+            ts_str = dt.strftime("%Y-%m-%d %H:%M:%S.") + f"{dt.microsecond // 1000:03d}"
+        else:
+            ts_str = str(timestamp)
+
+        # Build level label
+        level_str = _LEVEL_LABELS.get(level, f"{level.upper():<8s}")
+
+        # Build key=value pairs from remaining context
+        kv_parts: list[str] = []
+        for k, v in event_dict.items():
+            kv_parts.append(f"{k}={v!r}" if not isinstance(v, str) else f"{k}={v}")
+        kv_str = " ".join(kv_parts)
+
+        # Pad event
+        padded_event = event.ljust(self._pad_event) if kv_str else event
+
+        # Assemble
+        if self._colors:
+            msg_color = self._level_styles.get(level, _Colors.WHITE)
+            label_color = _LEVEL_LABEL_STYLES.get(level, _Colors.WHITE)
+
+            line = (
+                f"{_Colors.GREEN}{ts_str}{_Colors.RESET} | "
+                f"{label_color}{_Colors.BOLD}{level_str}{_Colors.RESET} | "
+                f"{msg_color}{padded_event}{_Colors.RESET}"
+            )
+            if kv_str:
+                line += f" {_Colors.DIM}{kv_str}{_Colors.RESET}"
+            if exception:
+                line += f"\n{_Colors.RED}{exception}{_Colors.RESET}"
+        else:
+            line = f"{ts_str} | {level_str} | {padded_event}"
+            if kv_str:
+                line += f" {kv_str}"
+            if exception:
+                line += f"\n{exception}"
+
+        return line
+
+
+def _compact_iso(ts: str) -> str:
+    """Convert an ISO 8601 timestamp to ``YYYY-MM-DD HH:MM:SS.mmm`` format."""
+    try:
+        dt = datetime.datetime.fromisoformat(ts)
+        return dt.strftime("%Y-%m-%d %H:%M:%S.") + f"{dt.microsecond // 1000:03d}"
+    except (ValueError, AttributeError):
+        return ts
+
+
+# ── BoundLogger ──────────────────────────────────────────────────────────────
+
+
+class BoundLogger:
+    """A logger that carries bound context through a processor pipeline.
+
+    Do not instantiate directly; use :func:`get_logger` or
+    :func:`wrap_logger` instead.
+
+    Args:
+        logger: The underlying logger instance (e.g. ``PrintLogger``).
+        processors: Ordered list of processors to run on each log event.
+        context: Initial context dictionary.
+    """
+
+    __slots__ = ("_logger", "_processors", "_context")
+
+    def __init__(
+        self,
+        logger: Any,
+        processors: list[Processor],
+        context: dict[str, Any],
+    ) -> None:
+        self._logger = logger
+        self._processors = processors
+        self._context = context
+
+    def bind(self, **new_values: Any) -> BoundLogger:
+        """Return a new logger with *new_values* merged into the context."""
+        new_ctx = {**self._context, **new_values}
+        return BoundLogger(self._logger, self._processors, new_ctx)
+
+    def unbind(self, *keys: str) -> BoundLogger:
+        """Return a new logger with *keys* removed from the context."""
+        new_ctx = {k: v for k, v in self._context.items() if k not in keys}
+        return BoundLogger(self._logger, self._processors, new_ctx)
+
+    def new(self, **new_values: Any) -> BoundLogger:
+        """Return a new logger with *new_values* replacing the context."""
+        return BoundLogger(self._logger, self._processors, dict(new_values))
+
+    # ── Log methods ──
+
+    def debug(self, event: str | None = None, /, **kw: Any) -> None:
+        self._process("debug", event, kw)
+
+    def info(self, event: str | None = None, /, **kw: Any) -> None:
+        self._process("info", event, kw)
+
+    def warning(self, event: str | None = None, /, **kw: Any) -> None:
+        self._process("warning", event, kw)
+
+    def warn(self, event: str | None = None, /, **kw: Any) -> None:
+        self._process("warning", event, kw)
+
+    def error(self, event: str | None = None, /, **kw: Any) -> None:
+        self._process("error", event, kw)
+
+    def critical(self, event: str | None = None, /, **kw: Any) -> None:
+        self._process("critical", event, kw)
+
+    def fatal(self, event: str | None = None, /, **kw: Any) -> None:
+        self._process("critical", event, kw)
+
+    def exception(self, event: str | None = None, /, **kw: Any) -> None:
+        kw.setdefault("exc_info", True)
+        self._process("error", event, kw)
+
+    def log(self, level: int, event: str | None = None, /, **kw: Any) -> None:
+        method_name = _LEVEL_TO_NAME.get(level, "info")
+        self._process(method_name, event, kw)
+
+    # ── Internal ──
+
+    def _process(self, method_name: str, event: str | None, kw: dict[str, Any]) -> None:
+        """Merge context, run processors, and emit via the underlying logger."""
+        event_dict: EventDict = {**self._context, **kw}
+        if event is not None:
+            event_dict["event"] = event
+        elif "event" not in event_dict:
+            event_dict["event"] = ""
+
+        try:
+            for proc in self._processors:
+                event_dict_or_str = proc(self._logger, method_name, event_dict)
+                if isinstance(event_dict_or_str, str):
+                    # Final renderer returned a string -- emit and stop.
+                    _emit(self._logger, method_name, event_dict_or_str)
+                    return
+                event_dict = event_dict_or_str
+        except DropEvent:
+            return
+
+        # If no processor returned a string, emit the repr of event_dict.
+        _emit(self._logger, method_name, str(event_dict))
+
+
+def _emit(logger: Any, method_name: str, message: str) -> None:
+    """Dispatch *message* to the underlying logger."""
+    if isinstance(logger, logging.Logger):
+        level = _NAME_TO_LEVEL.get(method_name, logging.INFO)
+        logger.log(level, "%s", message)
+    else:
+        func = getattr(logger, method_name, None) or getattr(logger, "msg", None)
+        if func:
+            func(message)
+
+
+# ── Configuration ────────────────────────────────────────────────────────────
+
+
+@dataclasses.dataclass
+class _Configuration:
+    """Global structlog configuration."""
+
+    processors: list[Processor]
+    wrapper_class: type[BoundLogger]
+    context_class: type
+    logger_factory: LoggerFactory
+    cache_logger_on_first_use: bool
+
+
+def _make_defaults() -> _Configuration:
+    return _Configuration(
+        processors=[add_log_level, TimeStamper(), ConsoleRenderer()],
+        wrapper_class=BoundLogger,
+        context_class=dict,
+        logger_factory=PrintLoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+_config: _Configuration = _make_defaults()
+_logger_cache: dict[Any, BoundLogger] = {}
+
+
+def configure(
+    processors: list[Processor] | None = None,
+    wrapper_class: type[BoundLogger] | None = None,
+    context_class: type[dict] | None = None,
+    logger_factory: LoggerFactory | None = None,
+    cache_logger_on_first_use: bool | None = None,
+) -> None:
+    """Override the global configuration.
+
+    Only non-*None* arguments are changed.  Call :func:`reset_defaults` to
+    restore factory settings.
+
+    Args:
+        processors: Ordered processor list.
+        wrapper_class: BoundLogger subclass to use.
+        context_class: Dict-like class for context storage.
+        logger_factory: Factory for the underlying logger.
+        cache_logger_on_first_use: Cache loggers returned by
+            :func:`get_logger`.
+    """
+    global _config
+    _logger_cache.clear()
+    p = _config
+    _config = _Configuration(
+        processors=(processors if processors is not None else p.processors),
+        wrapper_class=(wrapper_class if wrapper_class is not None else p.wrapper_class),
+        context_class=(context_class if context_class is not None else p.context_class),
+        logger_factory=(
+            logger_factory if logger_factory is not None else p.logger_factory
+        ),
+        cache_logger_on_first_use=(
+            cache_logger_on_first_use
+            if cache_logger_on_first_use is not None
+            else p.cache_logger_on_first_use
+        ),
+    )
+
+
+def reset_defaults() -> None:
+    """Restore the global configuration to factory defaults."""
+    global _config
+    _logger_cache.clear()
+    _config = _make_defaults()
+
+
+def get_config() -> _Configuration:
+    """Return the current global configuration (read-only snapshot)."""
+    return _config
+
+
+# ── Logger Creation ──────────────────────────────────────────────────────────
+
+
+def get_logger(*args: Any, **initial_values: Any) -> BoundLogger:
+    """Create a :class:`BoundLogger` using the global configuration.
+
+    Positional arguments are forwarded to the logger factory (e.g. a
+    logger name).  Keyword arguments become the initial bound context.
+
+    Returns:
+        A configured :class:`BoundLogger`.
+    """
+    cache_key = args if not initial_values else None
+
+    if cache_key is not None and _config.cache_logger_on_first_use:
+        cached = _logger_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+    underlying = _config.logger_factory(*args)
+    ctx = (
+        _config.context_class(initial_values)
+        if initial_values
+        else _config.context_class()
+    )
+    bound = _config.wrapper_class(
+        logger=underlying,
+        processors=list(_config.processors),
+        context=ctx,
+    )
+
+    if cache_key is not None and _config.cache_logger_on_first_use:
+        _logger_cache[cache_key] = bound
+
+    return bound
+
+
+def wrap_logger(
+    logger: Any,
+    processors: list[Processor] | None = None,
+    **initial_values: Any,
+) -> BoundLogger:
+    """Wrap an existing logger with a processor pipeline.
+
+    Args:
+        logger: Any object with ``debug``/``info``/... methods.
+        processors: Processor list.  Defaults to the global config.
+        **initial_values: Initial bound context.
+
+    Returns:
+        A :class:`BoundLogger` wrapping *logger*.
+    """
+    procs = processors if processors is not None else list(_config.processors)
+    ctx = dict(initial_values)
+    return BoundLogger(logger=logger, processors=procs, context=ctx)
+
+
+# ── Convenience Setup ────────────────────────────────────────────────────────
+
+
+def _resolve_level(level: int | str) -> int:
+    """Convert a level name or int to a logging level int."""
+    if isinstance(level, int):
+        return level
+    return _NAME_TO_LEVEL.get(level.lower(), logging.INFO)
+
+
+def setup_logging(
+    level: int | str = logging.INFO,
+    renderer: str = "console",
+    colors: bool | None = None,
+    processors: list[Processor] | None = None,
+    logger_name: str | None = None,
+    stream: IO[str] | None = None,
+) -> BoundLogger:
+    """One-call logging setup with stdlib integration.
+
+    Configures both stdlib ``logging`` and the structlog processor
+    pipeline in a single call.
+
+    Args:
+        level: Log level (name or int).  Defaults to ``INFO``.
+        renderer: Output renderer: ``"console"``, ``"json"``, or ``"kv"``.
+        colors: Enable ANSI colors.  *None* auto-detects.
+        processors: Custom processor list.  Overrides *renderer* if given.
+        logger_name: stdlib logger name.
+        stream: Output stream.  Defaults to ``sys.stderr``.
+
+    Returns:
+        A ready-to-use :class:`BoundLogger`.
+    """
+    resolved_level = _resolve_level(level)
+    out = stream or sys.stderr
+
+    if processors is None:
+        base: list[Processor] = [add_log_level, TimeStamper()]
+        if renderer == "json":
+            base.append(JSONRenderer())
+        elif renderer == "kv":
+            base.append(KeyValueRenderer(key_order=["event", "level", "timestamp"]))
+        else:
+            base.append(ConsoleRenderer(colors=colors))
+        processors = base
+
+    # Configure stdlib logging to pass through rendered strings.
+    stdlib_logger = logging.getLogger(logger_name)
+    stdlib_logger.setLevel(resolved_level)
+    stdlib_logger.propagate = False
+
+    # Remove existing handlers to avoid duplicate output on repeated calls.
+    stdlib_logger.handlers.clear()
+
+    handler = logging.StreamHandler(out)
+    handler.setLevel(resolved_level)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    stdlib_logger.addHandler(handler)
+
+    configure(
+        processors=processors,
+        logger_factory=StdlibLoggerFactory(name=logger_name),
+    )
+
+    return get_logger()
+
+
+# ── Utilities ────────────────────────────────────────────────────────────────
+
+
+def truncate_string(s: str, max_length: int, suffix: str = "...") -> str:
+    """Truncate *s* to *max_length*, appending a count of remaining chars.
+
+    Args:
+        s: The string to truncate.
+        max_length: Maximum number of characters to keep.
+        suffix: Separator between the kept text and the count.
+
+    Returns:
+        The original string if short enough, otherwise truncated with a
+        ``"...[N more chars]"`` suffix.
+    """
+    if len(s) <= max_length:
+        return s
+    remaining = len(s) - max_length
+    return f"{s[:max_length]}{suffix}[{remaining} more chars]"
+
+
+def truncate_base64(data_url: str, max_length: int = 100) -> str:
+    """Truncate base64 data-URLs for cleaner logging.
+
+    Args:
+        data_url: A ``data:`` URL or any string.
+        max_length: Maximum base64 payload chars to keep.
+
+    Returns:
+        The truncated URL, or the original string if not a data-URL.
+    """
+    if not data_url.startswith("data:"):
+        return data_url
+    if ";base64," in data_url:
+        header, base64_data = data_url.split(";base64,", 1)
+        if len(base64_data) > max_length:
+            remaining = len(base64_data) - max_length
+            return (
+                f"{header};base64,{base64_data[:max_length]}...[{remaining} more chars]"
+            )
+    return data_url

src/veilrender/_vendor/useragent.py

@@ -0,0 +1,475 @@
+# /// zerodep
+# version = "0.1.0"
+# deps = []
+# tier = "simple"
+# category = "network"
+# note = "Install/update via `zerodep add useragent`"
+# ///
+
+"""Lightweight User-Agent generator for Chrome/Edge with Client Hints.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Generates realistic browser UA strings and matching ``Sec-CH-UA-*`` headers.
+Covers Windows, macOS, Linux (desktop) and Android (mobile) platforms with
+Chrome and Edge browsers only -- this is intentionally minimal.
+
+Inspired by `ua-generator <https://github.com/iamdual/ua-generator>`_ (Apache-2.0).
+
+Zero external dependencies -- stdlib ``random`` only.
+
+Basic usage::
+
+    from useragent import generate
+
+    ua = generate(browser="chrome", device="desktop")
+    print(ua.text)        # full User-Agent string
+    print(ua.headers.get())  # dict with UA + Client Hints headers
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Sequence, Union
+
+__all__ = ["UserAgent", "generate"]
+
+__version__ = "0.1.0"
+
+# ---------------------------------------------------------------------------
+# Version data
+# ---------------------------------------------------------------------------
+
+# (major, build) pairs.  Patch is randomised at generation time.
+# Sources:
+#   Chrome -- https://chromereleases.googleblog.com/search/label/Stable%20updates
+#   Edge   -- https://learn.microsoft.com/en-us/deployedge/microsoft-edge-release-schedule
+
+_CHROME_VERSIONS: list[tuple[int, int]] = [
+    (120, 6099),
+    (121, 6167),
+    (122, 6261),
+    (123, 6312),
+    (124, 6367),
+    (125, 6422),
+    (126, 6478),
+    (127, 6533),
+    (128, 6613),
+    (129, 6668),
+    (130, 6723),
+    (131, 6778),
+    (132, 6834),
+    (133, 6943),
+    (134, 6998),
+    (135, 7049),
+    (136, 7103),
+    (137, 7151),
+    (138, 7204),
+    (139, 7258),
+    (140, 7339),
+    (141, 7390),
+    (142, 7444),
+    (143, 7499),
+    (144, 7559),
+    (145, 7632),
+    (146, 7680),
+]
+
+_EDGE_VERSIONS: list[tuple[int, int]] = [
+    (120, 2210),
+    (121, 2277),
+    (122, 2365),
+    (123, 2420),
+    (124, 2478),
+    (125, 2535),
+    (126, 2592),
+    (127, 2651),
+    (128, 2739),
+    (129, 2792),
+    (130, 2849),
+    (131, 2903),
+    (132, 2957),
+    (133, 3065),
+    (134, 3124),
+    (135, 3179),
+    (136, 3240),
+    (137, 3296),
+    (138, 3351),
+    (139, 3405),
+    (140, 3485),
+    (141, 3537),
+    (142, 3595),
+    (143, 3650),
+    (144, 3719),
+    (145, 3800),
+    (146, 3856),
+]
+
+# Windows NT versions: (nt_major, nt_minor, ch_platform_range)
+_WINDOWS_VERSIONS: list[tuple[float, tuple[int, int]]] = [
+    (10.0, (1, 10)),  # Windows 10
+    (10.0, (13, 16)),  # Windows 11
+]
+
+# macOS versions: (major, minor, max_build)
+_MACOS_VERSIONS: list[tuple[int, int, int]] = [
+    (13, 6, 9),
+    (13, 7, 8),
+    (14, 4, 1),
+    (14, 5, 0),
+    (14, 6, 1),
+    (14, 7, 8),
+    (14, 8, 4),
+    (15, 0, 1),
+    (15, 1, 1),
+    (15, 2, 1),
+    (15, 3, 1),
+    (15, 4, 1),
+    (15, 5, 0),
+    (15, 6, 1),
+    (15, 7, 4),
+    (26, 0, 1),
+    (26, 1, 0),
+    (26, 2, 0),
+    (26, 3, 2),
+]
+
+# Android model strings (Samsung subset -- most common vendor)
+_ANDROID_MODELS: tuple[str, ...] = (
+    "SM-G991B",
+    "SM-G996B",
+    "SM-G998B",
+    "SM-A526B",
+    "SM-A536B",
+    "SM-S901B",
+    "SM-S906B",
+    "SM-S908B",
+    "SM-S911B",
+    "SM-S916B",
+    "SM-S918B",
+    "SM-S921B",
+    "SM-S926B",
+    "SM-S928B",
+    "SM-A546B",
+    "SM-A556B",
+    "SM-A346B",
+    "SM-A256B",
+    "SM-A156B",
+    "SM-G781B",
+)
+
+_DESKTOP_PLATFORMS = ("windows", "macos", "linux")
+_MOBILE_PLATFORMS = ("android",)
+_ALL_PLATFORMS = _DESKTOP_PLATFORMS + _MOBILE_PLATFORMS
+
+_WEBKIT = "537.36"
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _pick_chrome_version() -> tuple[int, int, int, int]:
+    """Return (major, minor=0, build, patch)."""
+    major, build = random.choice(_CHROME_VERSIONS)
+    return (major, 0, build, random.randint(0, 255))
+
+
+def _pick_edge_version() -> tuple[int, int, int, int]:
+    major, build = random.choice(_EDGE_VERSIONS)
+    return (major, 0, build, random.randint(0, 99))
+
+
+def _fmt_ver(v: tuple[int, ...], n: int = 4, sep: str = ".") -> str:
+    """Format version tuple to string, padding with 0s up to *n* parts."""
+    parts = list(v[:n])
+    while len(parts) < n:
+        parts.append(0)
+    return sep.join(str(p) for p in parts)
+
+
+def _pick_platform(device: str | None) -> str:
+    if device == "desktop":
+        return random.choice(_DESKTOP_PLATFORMS)
+    if device == "mobile":
+        return random.choice(_MOBILE_PLATFORMS)
+    return random.choice(_ALL_PLATFORMS)
+
+
+def _build_ua_string(
+    browser: str,
+    platform: str,
+    ver: tuple[int, int, int, int],
+) -> str:
+    """Build a User-Agent string from browser/platform/version."""
+    chrome_str = _fmt_ver(ver)
+
+    if platform == "windows":
+        nt = random.choice(_WINDOWS_VERSIONS)
+        nt_str = f"{nt[0]:.1f}".replace(".0", ".0")  # "10.0"
+        base = (
+            f"Mozilla/5.0 (Windows NT {nt_str}; Win64; x64) "
+            f"AppleWebKit/{_WEBKIT} (KHTML, like Gecko) "
+            f"Chrome/{chrome_str} Safari/{_WEBKIT}"
+        )
+        if browser == "edge":
+            base += f" Edg/{chrome_str}"
+        return base
+
+    if platform == "linux":
+        tpl = random.choice(
+            (
+                f"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/{_WEBKIT} "
+                f"(KHTML, like Gecko) Chrome/{chrome_str} Safari/{_WEBKIT}",
+                f"Mozilla/5.0 (X11; Ubuntu; Linux x86_64) AppleWebKit/{_WEBKIT} "
+                f"(KHTML, like Gecko) Chrome/{chrome_str} Safari/{_WEBKIT}",
+            )
+        )
+        if browser == "edge":
+            tpl += f" Edg/{chrome_str}"
+        return tpl
+
+    if platform == "macos":
+        mv = random.choice(_MACOS_VERSIONS)
+        build = random.randint(0, mv[2]) if mv[2] > 0 else 0
+        mac_str = f"{mv[0]}_{mv[1]}"
+        if build:
+            mac_str += f"_{build}"
+        base = (
+            f"Mozilla/5.0 (Macintosh; Intel Mac OS X {mac_str}) "
+            f"AppleWebKit/{_WEBKIT} (KHTML, like Gecko) "
+            f"Chrome/{chrome_str} Safari/{_WEBKIT}"
+        )
+        if browser == "edge":
+            base += f" Edg/{chrome_str}"
+        return base
+
+    if platform == "android":
+        android_ver = random.randint(12, 16)
+        model = random.choice(_ANDROID_MODELS)
+        base = (
+            f"Mozilla/5.0 (Linux; Android {android_ver}; {model}) "
+            f"AppleWebKit/{_WEBKIT} (KHTML, like Gecko) "
+            f"Chrome/{chrome_str} Mobile Safari/{_WEBKIT}"
+        )
+        if browser == "edge":
+            base += f" EdgA/{chrome_str}"
+        return base
+
+    raise ValueError(f"Unsupported platform: {platform}")
+
+
+# ---------------------------------------------------------------------------
+# Client Hints serialization
+# ---------------------------------------------------------------------------
+
+
+def _ch_bool(val: bool) -> str:
+    return "?1" if val else "?0"
+
+
+def _ch_string(val: str) -> str:
+    return f'"{val}"'
+
+
+def _ch_brand_list(brands: list[dict[str, str]]) -> str:
+    return ", ".join(f'"{b["brand"]}";v="{b["version"]}"' for b in brands)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+class UserAgent:
+    """A generated user-agent with matching Client Hints headers.
+
+    Attributes:
+        browser: Browser name (``"chrome"`` or ``"edge"``).
+        platform: Platform name (``"windows"``, ``"macos"``, ``"linux"``,
+            or ``"android"``).
+        version: 4-tuple ``(major, minor, build, patch)``.
+        text: The full User-Agent string.
+        headers: A :class:`_Headers` instance for Client Hints.
+
+    Example::
+
+        ua = generate(browser=["chrome", "edge"])
+        ua.headers.accept_ch("Sec-CH-UA-Platform-Version")
+        headers = ua.headers.get()
+    """
+
+    def __init__(
+        self,
+        *,
+        browser: str,
+        platform: str,
+        version: tuple[int, int, int, int],
+        ua_string: str,
+    ) -> None:
+        self.browser = browser
+        self.platform = platform
+        self.version = version
+        self.text = ua_string
+        self.headers = _Headers(self)
+
+    # -- Client Hints data methods --
+
+    def _is_mobile(self) -> bool:
+        return self.platform in _MOBILE_PLATFORMS
+
+    def _ch_platform_name(self) -> str:
+        mapping = {
+            "windows": "Windows",
+            "macos": "macOS",
+            "linux": "Linux",
+            "android": "Android",
+        }
+        return mapping.get(self.platform, self.platform.title())
+
+    def _ch_platform_version(self) -> str:
+        if self.platform == "windows":
+            lo, hi = random.choice(_WINDOWS_VERSIONS)[1]
+            return f"{random.randint(lo, hi)}.0.0"
+        if self.platform == "macos":
+            mv = random.choice(_MACOS_VERSIONS)
+            return f"{mv[0]}.{mv[1]}.{random.randint(0, max(mv[2], 1))}"
+        if self.platform == "android":
+            return f"{random.randint(12, 16)}.0.0"
+        # Linux
+        return ""
+
+    def _ch_brands(self, full_version: bool = False) -> list[dict[str, str]]:
+        ver_str = _fmt_ver(self.version) if full_version else str(self.version[0])
+        filler_ver = "99.0.0.0" if full_version else "99"
+        brands: list[dict[str, str]] = [{"brand": "Not A(Brand", "version": filler_ver}]
+        if self.browser == "chrome":
+            brands.append({"brand": "Chromium", "version": ver_str})
+            brands.append({"brand": "Google Chrome", "version": ver_str})
+        elif self.browser == "edge":
+            brands.append({"brand": "Chromium", "version": ver_str})
+            brands.append({"brand": "Microsoft Edge", "version": ver_str})
+        return brands
+
+    def _ch_architecture(self) -> str:
+        if self.platform in ("android",):
+            return "arm"
+        if self.platform == "macos":
+            return random.choice(("arm", "x86", "arm", "arm"))
+        return "x86"
+
+    def _ch_bitness(self) -> str:
+        if self.platform == "android":
+            return random.choice(("32", "64", "32", "32"))
+        return "64"
+
+    def _ch_model(self) -> str:
+        if self.platform == "android":
+            return random.choice(_ANDROID_MODELS)
+        return ""
+
+    def __str__(self) -> str:
+        return self.text
+
+    def __repr__(self) -> str:
+        return f"UserAgent(browser={self.browser!r}, platform={self.platform!r})"
+
+
+class _Headers:
+    """Lazy header builder matching the ``ua_generator.Headers`` interface."""
+
+    def __init__(self, ua: UserAgent) -> None:
+        self._ua = ua
+        self._headers: dict[str, str] = {}
+        self._initialised = False
+
+    def _reset(self) -> None:
+        self._initialised = True
+        self._headers = {"user-agent": self._ua.text}
+        # Low-entropy hints (always included for Chromium)
+        self._add("sec-ch-ua")
+        self._add("sec-ch-ua-mobile")
+        self._add("sec-ch-ua-platform")
+
+    def _add(self, key: str) -> None:
+        ua = self._ua
+        if key == "sec-ch-ua":
+            self._headers[key] = _ch_brand_list(ua._ch_brands(full_version=False))
+        elif key == "sec-ch-ua-full-version-list":
+            self._headers[key] = _ch_brand_list(ua._ch_brands(full_version=True))
+        elif key == "sec-ch-ua-platform":
+            self._headers[key] = _ch_string(ua._ch_platform_name())
+        elif key == "sec-ch-ua-platform-version":
+            self._headers[key] = _ch_string(ua._ch_platform_version())
+        elif key == "sec-ch-ua-mobile":
+            self._headers[key] = _ch_bool(ua._is_mobile())
+        elif key == "sec-ch-ua-arch":
+            self._headers[key] = _ch_string(ua._ch_architecture())
+        elif key == "sec-ch-ua-bitness":
+            self._headers[key] = _ch_string(ua._ch_bitness())
+        elif key == "sec-ch-ua-model":
+            self._headers[key] = _ch_string(ua._ch_model())
+
+    def accept_ch(self, val: str) -> None:
+        """Process an ``Accept-CH`` header value and populate matching hints.
+
+        Args:
+            val: Comma-separated list of hint names
+                (e.g. ``"Sec-CH-UA-Platform-Version, Sec-CH-UA-Arch"``).
+        """
+        self._reset()
+        for hint in val.split(","):
+            self._add(hint.strip().lower())
+
+    def get(self) -> dict[str, str]:
+        """Return all generated headers as a dict."""
+        if not self._initialised:
+            self._reset()
+        return self._headers
+
+
+def generate(
+    *,
+    browser: Union[str, Sequence[str]] | None = None,
+    device: str | None = None,
+) -> UserAgent:
+    """Generate a random User-Agent with matching Client Hints.
+
+    Args:
+        browser: Browser name or list of names to pick from.
+            Supported: ``"chrome"``, ``"edge"``. Defaults to both.
+        device: Device type -- ``"desktop"`` or ``"mobile"``.
+            Defaults to random selection across all platforms.
+
+    Returns:
+        A :class:`UserAgent` instance.
+
+    Raises:
+        ValueError: If *browser* is not ``"chrome"`` or ``"edge"``.
+    """
+    # Resolve browser
+    if browser is None:
+        chosen_browser = random.choice(("chrome", "edge"))
+    elif isinstance(browser, str):
+        chosen_browser = browser
+    else:
+        chosen_browser = random.choice(list(browser))
+
+    if chosen_browser not in ("chrome", "edge"):
+        raise ValueError(f"Unsupported browser: {chosen_browser!r}")
+
+    # Resolve platform
+    platform = _pick_platform(device)
+
+    # Pick version
+    if chosen_browser == "chrome":
+        ver = _pick_chrome_version()
+    else:
+        ver = _pick_edge_version()
+
+    ua_string = _build_ua_string(chosen_browser, platform, ver)
+    return UserAgent(
+        browser=chosen_browser, platform=platform, version=ver, ua_string=ua_string
+    )

src/veilrender/_vendor/yaml.py

@@ -0,0 +1,1124 @@
+# /// zerodep
+# version = "0.3.1"
+# deps = []
+# tier = "subsystem"
+# category = "serialization"
+# note = "Install/update via `zerodep add yaml`"
+# ///
+
+"""YAML parser and serializer (common subset) — zero dependencies, stdlib only, Python 3.10+.
+
+Part of zerodep: https://github.com/Oaklight/zerodep
+Copyright (c) 2026 Peng Ding. MIT License.
+
+Supports the most commonly used YAML features: mappings, sequences,
+scalars (str/int/float/bool/null), flow style, block scalars,
+multi-document streams, and comments.
+
+Does NOT implement: anchors/aliases, tags, merge keys, complex keys.
+
+Example::
+
+    data = load("name: Alice\nage: 30")
+    # {'name': 'Alice', 'age': 30}
+    print(dump(data))
+    # age: 30
+    # name: Alice
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import IO, Any, Iterator, overload
+
+__all__ = [
+    "YAMLError",
+    "load",
+    "load_all",
+    "dump",
+    "dump_all",
+]
+
+# ── Exceptions ─────────────────────────────────────────────────────────────────
+
+
+class YAMLError(Exception):
+    """Raised when YAML parsing fails."""
+
+
+# ── Scalar type resolution ─────────────────────────────────────────────────────
+
+_NULL_RE = re.compile(r"\A(?:null|Null|NULL|~)\Z")
+_BOOL_TRUE_RE = re.compile(r"\A(?:true|True|TRUE|yes|Yes|YES|on|On|ON)\Z")
+_BOOL_FALSE_RE = re.compile(r"\A(?:false|False|FALSE|no|No|NO|off|Off|OFF)\Z")
+_INT_RE = re.compile(r"\A[-+]?(?:0|[1-9][0-9_]*)\Z")
+_INT_HEX_RE = re.compile(r"\A0x[0-9a-fA-F_]+\Z")
+_INT_OCT_RE = re.compile(r"\A0[0-7_]+\Z")  # YAML 1.1 octal: 0777 (not 0o777)
+_INT_BIN_RE = re.compile(r"\A0b[01_]+\Z")
+# YAML 1.1 requires explicit sign (+/-) in exponent when base has decimal point
+_FLOAT_RE = re.compile(r"\A[-+]?(?:\.[0-9]+|[0-9]+\.[0-9]*)(?:[eE][-+][0-9]+)?\Z")
+_INF_RE = re.compile(r"\A[-+]?\.(?:inf|Inf|INF)\Z")
+_NAN_RE = re.compile(r"\A\.(?:nan|NaN|NAN)\Z")
+
+
+def _resolve_scalar(value: str) -> str | int | float | bool | None:
+    """Resolve a plain (unquoted) scalar string to a typed Python value."""
+    if not value:
+        return None
+    if _NULL_RE.match(value):
+        return None
+    if _BOOL_TRUE_RE.match(value):
+        return True
+    if _BOOL_FALSE_RE.match(value):
+        return False
+    if _INT_RE.match(value):
+        return int(value.replace("_", ""))
+    if _INT_HEX_RE.match(value):
+        return int(value.replace("_", ""), 16)
+    if _INT_OCT_RE.match(value):
+        return int(value.replace("_", ""), 8)  # YAML 1.1: 0777 -> 511
+    if _INT_BIN_RE.match(value):
+        return int(value.replace("_", ""), 2)
+    if _FLOAT_RE.match(value):
+        return float(value.replace("_", ""))
+    if _INF_RE.match(value):
+        return float("-inf") if value.startswith("-") else float("inf")
+    if _NAN_RE.match(value):
+        return float("nan")
+    return value
+
+
+# ── String unquoting ───────────────────────────────────────────────────────────
+
+_DQ_ESCAPE_MAP = {
+    "\\": "\\",
+    '"': '"',
+    "n": "\n",
+    "r": "\r",
+    "t": "\t",
+    "0": "\0",
+    "a": "\a",
+    "b": "\b",
+    "e": "\x1b",
+    "v": "\v",
+    "/": "/",
+    " ": " ",
+    "N": "\x85",
+    "_": "\xa0",
+}
+
+
+def _unescape_double_quoted(s: str) -> str:
+    """Process escape sequences in a double-quoted YAML string."""
+    result: list[str] = []
+    i = 0
+    while i < len(s):
+        if s[i] == "\\" and i + 1 < len(s):
+            nxt = s[i + 1]
+            if nxt in _DQ_ESCAPE_MAP:
+                result.append(_DQ_ESCAPE_MAP[nxt])
+                i += 2
+            elif nxt == "x" and i + 3 < len(s):
+                result.append(chr(int(s[i + 2 : i + 4], 16)))
+                i += 4
+            elif nxt == "u" and i + 5 < len(s):
+                result.append(chr(int(s[i + 2 : i + 6], 16)))
+                i += 6
+            elif nxt == "U" and i + 9 < len(s):
+                result.append(chr(int(s[i + 2 : i + 10], 16)))
+                i += 10
+            else:
+                result.append(s[i])
+                i += 1
+        else:
+            result.append(s[i])
+            i += 1
+    return "".join(result)
+
+
+def _unquote(s: str) -> str:
+    """Remove quotes from a YAML scalar and process escapes if needed."""
+    if len(s) >= 2:
+        if s[0] == "'" and s[-1] == "'":
+            # Single-quoted: only '' escapes to '
+            return s[1:-1].replace("''", "'")
+        if s[0] == '"' and s[-1] == '"':
+            return _unescape_double_quoted(s[1:-1])
+    return s
+
+
+# ── Scanner ────────────────────────────────────────────────────────────────────
+
+
+class _Line:
+    """A logical line with tracked indentation and line number."""
+
+    __slots__ = ("indent", "text", "lineno")
+
+    def __init__(self, indent: int, text: str, lineno: int):
+        self.indent = indent
+        self.text = text
+        self.lineno = lineno
+
+    def __repr__(self) -> str:
+        return f"_Line({self.lineno}: indent={self.indent}, {self.text!r})"
+
+
+def _strip_inline_comment(text: str) -> str:
+    """Remove inline comments from a line, respecting quoted strings."""
+    in_single = False
+    in_double = False
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if ch == "\\" and in_double and i + 1 < len(text):
+            i += 2
+            continue
+        if ch == "'" and not in_double:
+            in_single = not in_single
+        elif ch == '"' and not in_single:
+            in_double = not in_double
+        elif ch == "#" and not in_single and not in_double:
+            # Must be preceded by whitespace to be a comment
+            if i == 0 or text[i - 1] in (" ", "\t"):
+                return text[:i].rstrip()
+        i += 1
+    return text
+
+
+def _scan(text: str) -> list[_Line]:
+    """Convert raw YAML text into a list of logical lines."""
+    lines: list[_Line] = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        # Preserve completely empty lines for block scalar detection
+        stripped = raw.lstrip()
+        if not stripped or stripped[0] == "#":
+            continue
+        indent = len(raw) - len(stripped)
+        # Don't strip comments from block scalar indicators or document markers
+        if stripped.startswith("---") or stripped.startswith("..."):
+            lines.append(_Line(indent, stripped, lineno))
+        else:
+            cleaned = _strip_inline_comment(stripped)
+            if cleaned:
+                lines.append(_Line(indent, cleaned, lineno))
+    return lines
+
+
+# ── Parser ─────────────────────────────────────────────────────────────────────
+
+
+class _Parser:
+    """Recursive-descent YAML parser for the common subset."""
+
+    def __init__(self, lines: list[_Line], raw_lines: list[str]):
+        self._lines = lines
+        self._raw_lines = raw_lines  # original text lines for block scalars
+        self._pos = 0
+
+    def _peek(self) -> _Line | None:
+        if self._pos < len(self._lines):
+            return self._lines[self._pos]
+        return None
+
+    def _advance(self) -> _Line:
+        line = self._lines[self._pos]
+        self._pos += 1
+        return line
+
+    def _error(self, msg: str, lineno: int | None = None) -> YAMLError:
+        if lineno is None:
+            cur = self._peek()
+            lineno = cur.lineno if cur else -1
+        return YAMLError(f"line {lineno}: {msg}")
+
+    # ── Document parsing ──
+
+    def parse_stream(self) -> list[Any]:
+        """Parse the entire stream, returning a list of documents."""
+        documents: list[Any] = []
+
+        # Skip leading document marker if present
+        cur = self._peek()
+        if cur is not None and cur.text == "---":
+            self._advance()
+
+        while self._pos < len(self._lines):
+            doc = self._parse_node(-1)
+            documents.append(doc)
+
+            # Check for document separator
+            cur = self._peek()
+            if cur is not None and cur.text in ("---", "..."):
+                self._advance()
+                # '...' without following '---' ends the stream
+                if cur.text == "...":
+                    cur2 = self._peek()
+                    if cur2 is None or cur2.text != "---":
+                        break
+                    self._advance()  # skip the ---
+
+        if not documents:
+            documents.append(None)
+
+        return documents
+
+    def _parse_node(self, parent_indent: int) -> Any:
+        """Parse a YAML node (mapping, sequence, or scalar)."""
+        cur = self._peek()
+        if cur is None:
+            return None
+
+        # Document end markers
+        if cur.text in ("---", "..."):
+            return None
+
+        text = cur.text
+
+        # Flow collections
+        if text.startswith("{"):
+            return self._parse_flow_mapping()
+        if text.startswith("["):
+            return self._parse_flow_sequence()
+
+        # Block scalar
+        if text.startswith("|") or text.startswith(">"):
+            return self._parse_block_scalar()
+
+        # Block sequence
+        if text.startswith("- ") or text == "-":
+            return self._parse_block_sequence(cur.indent)
+
+        # Check if it's a mapping (contains ': ' or ends with ':')
+        if self._is_mapping_line(text):
+            return self._parse_block_mapping(cur.indent)
+
+        # Plain scalar
+        self._advance()
+        return self._parse_scalar_value(text)
+
+    @staticmethod
+    def _skip_quoted_key(text: str) -> int:
+        """Return the index after the quoted prefix of *text*.
+
+        If *text* starts with a single- or double-quoted string the returned
+        index points just past the closing quote.  For unquoted text ``0`` is
+        returned so callers can scan from the beginning.
+
+        Returns ``-1`` when a single-quoted string has no closing quote (the
+        caller should treat this as "not a mapping line").
+        """
+        if text.startswith("'"):
+            end = text.find("'", 1)
+            return -1 if end < 0 else end + 1
+        if text.startswith('"'):
+            i = 1
+            while i < len(text):
+                if text[i] == "\\" and i + 1 < len(text):
+                    i += 2
+                    continue
+                if text[i] == '"':
+                    return i + 1
+                i += 1
+        return 0
+
+    @staticmethod
+    def _find_mapping_colon(text: str, start: int) -> int:
+        """Find the position of the mapping separator colon starting from *start*.
+
+        Returns the index of the ``:`` that acts as a mapping separator, or
+        ``-1`` if none is found.  A colon qualifies when it is either the last
+        character or is immediately followed by a space or tab.
+        """
+        i = start
+        while i < len(text):
+            if text[i] == ":":
+                if i + 1 == len(text) or text[i + 1] in (" ", "\t"):
+                    return i
+            i += 1
+        return -1
+
+    def _is_mapping_line(self, text: str) -> bool:
+        """Check if a line represents a mapping key."""
+        i = self._skip_quoted_key(text)
+        if i < 0:
+            return False
+        return self._find_mapping_colon(text, i) >= 0
+
+    def _split_mapping_line(self, text: str) -> tuple[str, str]:
+        """Split a mapping line into key and value parts."""
+        i = self._skip_quoted_key(text)
+        if i < 0:
+            return text, ""
+        colon = self._find_mapping_colon(text, i)
+        if colon < 0:
+            return text, ""
+        if colon + 1 == len(text):
+            return text[:colon], ""
+        return text[:colon], text[colon + 2 :].strip()
+
+    # ── Block mapping ──
+
+    def _parse_inline_value(self, raw_value: str, lineno: int) -> Any:
+        """Parse an inline mapping or sequence value."""
+        if raw_value.startswith(("{", "[")):
+            return self._parse_flow_from_text(raw_value)
+        if raw_value.startswith(("|", ">")):
+            return self._parse_block_scalar_from_indicator(raw_value, lineno)
+        return self._parse_scalar_value(raw_value)
+
+    def _at_block_end(self, cur: _Line | None, indent: int) -> bool:
+        """Return True when the current line should stop a block collection."""
+        if cur is None or cur.indent < indent:
+            return True
+        return cur.text in ("---", "...") or cur.indent != indent
+
+    def _parse_block_mapping(self, indent: int) -> dict:
+        result: dict[Any, Any] = {}
+        while True:
+            cur = self._peek()
+            if self._at_block_end(cur, indent):
+                break
+            assert cur is not None  # guaranteed by _at_block_end
+            if not self._is_mapping_line(cur.text):
+                break
+
+            self._advance()
+            raw_key, raw_value = self._split_mapping_line(cur.text)
+            key = self._parse_scalar_value(raw_key)
+
+            if raw_value:
+                value = self._parse_inline_value(raw_value, cur.lineno)
+            else:
+                nxt = self._peek()
+                if nxt is None or nxt.indent <= indent or nxt.text in ("---", "..."):
+                    value = None
+                else:
+                    value = self._parse_node(indent)
+            result[key] = value
+        return result
+
+    # ── Block sequence ──
+
+    def _parse_sequence_mapping_item(
+        self, item_text: str, cur: _Line, indent: int
+    ) -> dict:
+        """Parse a mapping that starts on a sequence item line (``- key: val``)."""
+        raw_key, raw_value = self._split_mapping_line(item_text)
+        key = self._parse_scalar_value(raw_key)
+        mapping: dict[Any, Any] = {}
+
+        if raw_value:
+            mapping[key] = self._parse_inline_value(raw_value, cur.lineno)
+        else:
+            nxt = self._peek()
+            if (
+                nxt is not None
+                and nxt.indent > indent
+                and nxt.text not in ("---", "...")
+            ):
+                mapping[key] = self._parse_node(indent)
+            else:
+                mapping[key] = None
+
+        # Continue reading mapping entries at deeper indent
+        nxt = self._peek()
+        if nxt is not None and nxt.indent > indent and self._is_mapping_line(nxt.text):
+            rest = self._parse_block_mapping(nxt.indent)
+            mapping.update(rest)
+
+        return mapping
+
+    def _parse_sequence_item(self, item_text: str, cur: _Line, indent: int) -> Any:
+        """Parse the value part of a single sequence item."""
+        if not item_text:
+            nxt = self._peek()
+            if nxt is None or nxt.indent <= indent or nxt.text in ("---", "..."):
+                return None
+            return self._parse_node(indent)
+        if item_text.startswith(("{", "[")):
+            return self._parse_flow_from_text(item_text)
+        if self._is_mapping_line(item_text):
+            return self._parse_sequence_mapping_item(item_text, cur, indent)
+        return self._parse_scalar_value(item_text)
+
+    def _parse_block_sequence(self, indent: int) -> list:
+        result: list[Any] = []
+        while True:
+            cur = self._peek()
+            if self._at_block_end(cur, indent):
+                break
+            assert cur is not None
+            if not (cur.text.startswith("- ") or cur.text == "-"):
+                break
+
+            self._advance()
+            item_text = cur.text[2:].strip() if cur.text.startswith("- ") else ""
+            result.append(self._parse_sequence_item(item_text, cur, indent))
+
+        return result
+
+    # ── Block scalars ──
+
+    def _parse_block_scalar(self) -> str:
+        cur = self._advance()
+        return self._parse_block_scalar_from_indicator(cur.text, cur.lineno)
+
+    @staticmethod
+    def _parse_chomping_indicator(header: str) -> tuple[str, int]:
+        """Parse the block scalar header for chomping mode and explicit indent.
+
+        Args:
+            header: The portion of the indicator line after ``|`` or ``>``.
+
+        Returns:
+            A ``(chomp, explicit_indent)`` tuple.
+        """
+        chomp = "clip"
+        explicit_indent = 0
+        for ch in header:
+            if ch == "-":
+                chomp = "strip"
+            elif ch == "+":
+                chomp = "keep"
+            elif ch.isdigit():
+                explicit_indent = int(ch)
+        return chomp, explicit_indent
+
+    def _collect_scalar_lines(self, raw_lineno: int, explicit_indent: int) -> list[str]:
+        """Collect raw content lines for a block scalar.
+
+        Args:
+            raw_lineno: 1-based line number of the indicator (content starts
+                on the *next* raw line).
+            explicit_indent: Explicit indentation width from the header, or
+                ``0`` to auto-detect.
+
+        Returns:
+            List of content lines with leading indentation stripped.
+        """
+        if raw_lineno >= len(self._raw_lines):
+            return []
+
+        content_indent = self._detect_scalar_indent(raw_lineno, explicit_indent)
+        if content_indent == 0:
+            return []
+
+        content_lines: list[str] = []
+        for j in range(raw_lineno, len(self._raw_lines)):
+            raw = self._raw_lines[j]
+            if not raw.strip():
+                content_lines.append("")
+                continue
+            line_indent = len(raw) - len(raw.lstrip())
+            if line_indent < content_indent:
+                break
+            content_lines.append(raw[content_indent:])
+        return content_lines
+
+    def _detect_scalar_indent(self, raw_lineno: int, explicit: int) -> int:
+        """Determine the content indentation for a block scalar."""
+        if explicit > 0:
+            return explicit
+        for j in range(raw_lineno, len(self._raw_lines)):
+            raw = self._raw_lines[j]
+            stripped = raw.lstrip()
+            if stripped and not stripped.startswith("#"):
+                return len(raw) - len(stripped)
+        return 0
+
+    @staticmethod
+    def _fold_lines(content_lines: list[str]) -> str:
+        """Fold content lines (``>`` mode): replace single newlines with spaces."""
+        parts: list[str] = []
+        for line in content_lines:
+            if not line:
+                parts.append("\n")
+            elif parts and parts[-1] != "\n" and not parts[-1].endswith("\n"):
+                parts.append(" " + line)
+            else:
+                parts.append(line)
+        return "".join(parts)
+
+    @staticmethod
+    def _apply_chomping(text: str, chomp: str) -> str:
+        """Apply the chomping rule (strip / keep / clip) to block scalar text."""
+        if chomp == "strip":
+            return text
+        if chomp == "keep":
+            return text + "\n"
+        # clip
+        return text + "\n" if text else ""
+
+    def _parse_block_scalar_from_indicator(
+        self, indicator_line: str, lineno: int
+    ) -> str:
+        """Parse a | or > block scalar, reading content lines from raw_lines."""
+        indicator = indicator_line[0]
+        header = indicator_line[1:].strip()
+
+        chomp, explicit_indent = self._parse_chomping_indicator(header)
+        content_lines = self._collect_scalar_lines(lineno, explicit_indent)
+
+        # Skip consumed content lines in the scanner
+        while True:
+            nxt = self._peek()
+            if nxt is None:
+                break
+            if nxt.lineno <= lineno + len(content_lines):
+                self._advance()
+            else:
+                break
+
+        # Remove trailing empty lines
+        while content_lines and not content_lines[-1]:
+            content_lines.pop()
+
+        if indicator == "|":
+            text = "\n".join(content_lines)
+        else:
+            text = self._fold_lines(content_lines)
+
+        return self._apply_chomping(text, chomp)
+
+    # ── Flow collections ──
+
+    def _parse_flow_mapping(self) -> dict:
+        cur = self._advance()
+        return self._parse_flow_from_text(cur.text)
+
+    def _parse_flow_sequence(self) -> list:
+        cur = self._advance()
+        return self._parse_flow_from_text(cur.text)
+
+    def _parse_flow_from_text(self, text: str) -> Any:
+        """Parse a flow collection from raw text."""
+        tokens = _FlowTokenizer(text)
+        return tokens.parse()
+
+    # ── Scalar value ──
+
+    def _parse_scalar_value(self, text: str) -> Any:
+        """Parse a scalar value, handling quoting and type resolution."""
+        if not text:
+            return None
+        # Quoted strings
+        if (text.startswith("'") and text.endswith("'")) or (
+            text.startswith('"') and text.endswith('"')
+        ):
+            return _unquote(text)
+        # Plain scalar
+        return _resolve_scalar(text)
+
+
+# ── Flow tokenizer ────────────────────────────────────────────────────────────
+
+
+class _FlowTokenizer:
+    """Character-level parser for flow-style YAML collections."""
+
+    def __init__(self, text: str):
+        self._text = text
+        self._pos = 0
+
+    def _skip_ws(self) -> None:
+        while self._pos < len(self._text) and self._text[self._pos] in (
+            " ",
+            "\t",
+            "\n",
+            "\r",
+        ):
+            self._pos += 1
+
+    def _peek(self) -> str:
+        if self._pos < len(self._text):
+            return self._text[self._pos]
+        return ""
+
+    def parse(self) -> Any:
+        self._skip_ws()
+        ch = self._peek()
+        if ch == "{":
+            return self._parse_mapping()
+        if ch == "[":
+            return self._parse_sequence()
+        return self._parse_value()
+
+    def _parse_mapping(self) -> dict:
+        self._pos += 1  # skip {
+        result: dict[Any, Any] = {}
+        self._skip_ws()
+        if self._peek() == "}":
+            self._pos += 1
+            return result
+
+        while True:
+            self._skip_ws()
+            key = self._parse_value()
+            self._skip_ws()
+            if self._peek() == ":":
+                self._pos += 1
+                self._skip_ws()
+                value = self.parse()
+            else:
+                value = None
+            result[key] = value
+            self._skip_ws()
+            if self._peek() == ",":
+                self._pos += 1
+                self._skip_ws()
+                if self._peek() == "}":
+                    self._pos += 1
+                    break
+            elif self._peek() == "}":
+                self._pos += 1
+                break
+            else:
+                break
+        return result
+
+    def _parse_sequence(self) -> list:
+        self._pos += 1  # skip [
+        result: list[Any] = []
+        self._skip_ws()
+        if self._peek() == "]":
+            self._pos += 1
+            return result
+
+        while True:
+            self._skip_ws()
+            item = self.parse()
+            result.append(item)
+            self._skip_ws()
+            if self._peek() == ",":
+                self._pos += 1
+                self._skip_ws()
+                if self._peek() == "]":
+                    self._pos += 1
+                    break
+            elif self._peek() == "]":
+                self._pos += 1
+                break
+            else:
+                break
+        return result
+
+    def _parse_value(self) -> Any:
+        self._skip_ws()
+        ch = self._peek()
+        if ch == "{":
+            return self._parse_mapping()
+        if ch == "[":
+            return self._parse_sequence()
+        if ch == "'":
+            return self._parse_single_quoted()
+        if ch == '"':
+            return self._parse_double_quoted()
+        return self._parse_plain_scalar()
+
+    def _parse_single_quoted(self) -> str:
+        self._pos += 1  # skip opening '
+        parts: list[str] = []
+        while self._pos < len(self._text):
+            ch = self._text[self._pos]
+            if ch == "'":
+                if self._pos + 1 < len(self._text) and self._text[self._pos + 1] == "'":
+                    parts.append("'")
+                    self._pos += 2
+                else:
+                    self._pos += 1
+                    break
+            else:
+                parts.append(ch)
+                self._pos += 1
+        return "".join(parts)
+
+    def _parse_double_quoted(self) -> str:
+        self._pos += 1  # skip opening "
+        parts: list[str] = []
+        while self._pos < len(self._text):
+            ch = self._text[self._pos]
+            if ch == "\\" and self._pos + 1 < len(self._text):
+                nxt = self._text[self._pos + 1]
+                if nxt in _DQ_ESCAPE_MAP:
+                    parts.append(_DQ_ESCAPE_MAP[nxt])
+                    self._pos += 2
+                else:
+                    parts.append(ch)
+                    self._pos += 1
+            elif ch == '"':
+                self._pos += 1
+                break
+            else:
+                parts.append(ch)
+                self._pos += 1
+        return "".join(parts)
+
+    def _parse_plain_scalar(self) -> Any:
+        start = self._pos
+        # Read until a flow indicator or end
+        while self._pos < len(self._text):
+            ch = self._text[self._pos]
+            if ch in (",", "}", "]", "{", "[", ":"):
+                break
+            self._pos += 1
+        raw = self._text[start : self._pos].strip()
+        if not raw:
+            return None
+        return _resolve_scalar(raw)
+
+
+# ── Dumper ─────────────────────────────────────────────────────────────────────
+
+# Characters that force quoting in a plain scalar
+_NEEDS_QUOTE_RE = re.compile(
+    r"[:\#{}\[\],&*?|>!%@`]"
+    r"|^[-?]$"
+    r"|^\s"
+    r"|\s$"
+    r"|\n"
+)
+
+
+class _Dumper:
+    """YAML serializer."""
+
+    def __init__(
+        self,
+        indent: int = 2,
+        default_flow_style: bool | None = None,
+        sort_keys: bool = True,
+        allow_unicode: bool = True,
+    ):
+        self._indent = indent
+        self._flow = default_flow_style
+        self._sort_keys = sort_keys
+        self._allow_unicode = allow_unicode
+        self._seen: set[int] = set()
+
+    def dump(self, data: Any) -> str:
+        self._seen.clear()
+        result = self._represent(data, 0)
+        if result.endswith("\n"):
+            return result
+        return result + "\n"
+
+    def _represent(self, data: Any, level: int) -> str:
+        if isinstance(data, dict):
+            return self._represent_mapping(data, level)
+        if isinstance(data, (list, tuple)):
+            return self._represent_sequence(data, level)
+        return self._represent_scalar(data)
+
+    def _represent_mapping(self, data: dict, level: int) -> str:
+        if id(data) in self._seen:
+            raise YAMLError("Circular reference detected")
+        self._seen.add(id(data))
+
+        if not data:
+            return "{}"
+
+        if self._flow is True:
+            items = []
+            keys = sorted(data.keys(), key=str) if self._sort_keys else data.keys()
+            for key in keys:
+                k = self._represent_scalar(key)
+                v = self._represent(data[key], level)
+                items.append(f"{k}: {v}")
+            self._seen.discard(id(data))
+            return "{" + ", ".join(items) + "}"
+
+        lines: list[str] = []
+        prefix = " " * (self._indent * level)
+        keys = sorted(data.keys(), key=str) if self._sort_keys else data.keys()
+        for key in keys:
+            k = self._represent_scalar(key)
+            val = data[key]
+            if isinstance(val, dict) and val:
+                lines.append(f"{prefix}{k}:")
+                lines.append(self._represent_mapping(val, level + 1))
+            elif isinstance(val, (list, tuple)) and val:
+                lines.append(f"{prefix}{k}:")
+                lines.append(self._represent_sequence(val, level + 1))
+            else:
+                v = self._represent(val, level + 1)
+                lines.append(f"{prefix}{k}: {v}")
+        self._seen.discard(id(data))
+        return "\n".join(lines)
+
+    def _represent_key_value_line(
+        self, key_str: str, val: Any, line_prefix: str, level: int
+    ) -> list[str]:
+        """Represent a single key-value pair for use inside a sequence item."""
+        if isinstance(val, (dict, list, tuple)) and val:
+            return [f"{line_prefix}{key_str}:", self._represent(val, level)]
+        v = self._represent(val, level)
+        return [f"{line_prefix}{key_str}: {v}"]
+
+    def _represent_dict_in_sequence(
+        self, item: dict, prefix: str, level: int
+    ) -> list[str]:
+        """Represent a dict that appears as a sequence item (``- key: val``)."""
+        keys = sorted(item.keys(), key=str) if self._sort_keys else list(item.keys())
+        first_key = keys[0]
+        k = self._represent_scalar(first_key)
+        lines = self._represent_key_value_line(
+            k, item[first_key], f"{prefix}- ", level + 2
+        )
+        inner_prefix = prefix + " " * self._indent
+        for rk in keys[1:]:
+            rk_s = self._represent_scalar(rk)
+            lines.extend(
+                self._represent_key_value_line(rk_s, item[rk], inner_prefix, level + 2)
+            )
+        return lines
+
+    def _represent_sequence(self, data: list | tuple, level: int) -> str:
+        if id(data) in self._seen:
+            raise YAMLError("Circular reference detected")
+        self._seen.add(id(data))
+
+        if not data:
+            return "[]"
+
+        if self._flow is True:
+            items = [self._represent(item, level) for item in data]
+            self._seen.discard(id(data))
+            return "[" + ", ".join(items) + "]"
+
+        lines: list[str] = []
+        prefix = " " * (self._indent * level)
+        for item in data:
+            if isinstance(item, dict) and item:
+                lines.extend(self._represent_dict_in_sequence(item, prefix, level))
+            elif isinstance(item, (list, tuple)) and item:
+                lines.append(f"{prefix}-")
+                lines.append(self._represent_sequence(item, level + 1))
+            else:
+                v = self._represent(item, level + 1)
+                lines.append(f"{prefix}- {v}")
+
+        self._seen.discard(id(data))
+        return "\n".join(lines)
+
+    def _represent_scalar(self, data: Any) -> str:
+        if data is None:
+            return "null"
+        if isinstance(data, bool):
+            return "true" if data else "false"
+        if isinstance(data, int):
+            return str(data)
+        if isinstance(data, float):
+            if math.isnan(data):
+                return ".nan"
+            if math.isinf(data):
+                return ".inf" if data > 0 else "-.inf"
+            return str(data)
+        if isinstance(data, str):
+            return self._represent_str(data)
+        return str(data)
+
+    def _represent_str(self, s: str) -> str:
+        if not s:
+            return "''"
+
+        # Check if it looks like a special YAML value
+        if (
+            _NULL_RE.match(s)
+            or _BOOL_TRUE_RE.match(s)
+            or _BOOL_FALSE_RE.match(s)
+            or _INT_RE.match(s)
+            or _INT_HEX_RE.match(s)
+            or _FLOAT_RE.match(s)
+            or _INF_RE.match(s)
+            or _NAN_RE.match(s)
+        ):
+            return f"'{s}'"
+
+        # Check if quoting is needed
+        if _NEEDS_QUOTE_RE.search(s):
+            if "\n" in s:
+                # Use literal block scalar for multiline
+                return "|\n" + "\n".join("  " + line for line in s.split("\n"))
+            # Use single quotes, escaping internal single quotes
+            return "'" + s.replace("'", "''") + "'"
+
+        return s
+
+
+# ── Public API ─────────────────────────────────────────────────────────────────
+
+
+def load(text: str) -> Any:
+    """Parse a YAML string and return a Python object.
+
+    Only produces safe types: dict, list, str, int, float, bool, None.
+    Equivalent to PyYAML's ``yaml.safe_load()``.
+
+    Args:
+        text: YAML document string.
+
+    Returns:
+        Parsed Python object.
+
+    Raises:
+        YAMLError: If the YAML is malformed.
+    """
+    if not text or not text.strip():
+        return None
+    raw_lines = text.splitlines()
+    lines = _scan(text)
+    if not lines:
+        return None
+    parser = _Parser(lines, raw_lines)
+    docs = parser.parse_stream()
+    return docs[0] if docs else None
+
+
+def load_all(text: str) -> Iterator[Any]:
+    """Parse a multi-document YAML string.
+
+    Yields one Python object per YAML document (separated by ``---``).
+
+    Args:
+        text: Multi-document YAML string.
+
+    Yields:
+        Parsed Python objects, one per document.
+    """
+    if not text or not text.strip():
+        yield None
+        return
+    raw_lines = text.splitlines()
+    lines = _scan(text)
+    if not lines:
+        yield None
+        return
+    parser = _Parser(lines, raw_lines)
+    docs = parser.parse_stream()
+    yield from docs
+
+
+@overload
+def dump(
+    data: Any,
+    stream: None = None,
+    *,
+    default_flow_style: bool | None = None,
+    indent: int = 2,
+    sort_keys: bool = True,
+    allow_unicode: bool = True,
+) -> str: ...
+
+
+@overload
+def dump(
+    data: Any,
+    stream: IO[str],
+    *,
+    default_flow_style: bool | None = None,
+    indent: int = 2,
+    sort_keys: bool = True,
+    allow_unicode: bool = True,
+) -> None: ...
+
+
+def dump(
+    data: Any,
+    stream: IO[str] | None = None,
+    *,
+    default_flow_style: bool | None = None,
+    indent: int = 2,
+    sort_keys: bool = True,
+    allow_unicode: bool = True,
+) -> str | None:
+    """Serialize a Python object to a YAML string.
+
+    Args:
+        data: Python object to serialize.
+        stream: If provided, write to this stream and return None.
+        default_flow_style: True for flow (inline) style, False for block,
+            None for auto (empty collections use flow).
+        indent: Number of spaces per indentation level.
+        sort_keys: Sort mapping keys alphabetically.
+        allow_unicode: Allow unicode characters in output.
+
+    Returns:
+        YAML string if *stream* is None, otherwise None.
+    """
+    dumper = _Dumper(
+        indent=indent,
+        default_flow_style=default_flow_style,
+        sort_keys=sort_keys,
+        allow_unicode=allow_unicode,
+    )
+    result = dumper.dump(data)
+    if stream is not None:
+        stream.write(result)
+        return None
+    return result
+
+
+@overload
+def dump_all(
+    documents: list[Any] | tuple[Any, ...],
+    stream: None = None,
+    *,
+    default_flow_style: bool | None = None,
+    indent: int = 2,
+    sort_keys: bool = True,
+    allow_unicode: bool = True,
+) -> str: ...
+
+
+@overload
+def dump_all(
+    documents: list[Any] | tuple[Any, ...],
+    stream: IO[str],
+    *,
+    default_flow_style: bool | None = None,
+    indent: int = 2,
+    sort_keys: bool = True,
+    allow_unicode: bool = True,
+) -> None: ...
+
+
+def dump_all(
+    documents: list[Any] | tuple[Any, ...],
+    stream: IO[str] | None = None,
+    *,
+    default_flow_style: bool | None = None,
+    indent: int = 2,
+    sort_keys: bool = True,
+    allow_unicode: bool = True,
+) -> str | None:
+    """Serialize multiple Python objects as a multi-document YAML string.
+
+    Args:
+        documents: Iterable of Python objects to serialize.
+        stream: If provided, write to this stream and return None.
+        default_flow_style: True for flow style, False for block, None for auto.
+        indent: Number of spaces per indentation level.
+        sort_keys: Sort mapping keys alphabetically.
+        allow_unicode: Allow unicode characters in output.
+
+    Returns:
+        YAML string if *stream* is None, otherwise None.
+    """
+    dumper = _Dumper(
+        indent=indent,
+        default_flow_style=default_flow_style,
+        sort_keys=sort_keys,
+        allow_unicode=allow_unicode,
+    )
+    parts: list[str] = []
+    for i, doc in enumerate(documents):
+        if i > 0:
+            parts.append("---\n")
+        parts.append(dumper.dump(doc))
+    result = "".join(parts)
+    if stream is not None:
+        stream.write(result)
+        return None
+    return result

src/veilrender/app.py

@@ -0,0 +1,158 @@
+"""VeilRender application entry point."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import sys
+
+from veilrender._vendor.httpserver import App
+from veilrender.browser import browser_manager
+from veilrender.cdp_proxy import handle_cdp_upgrade, is_websocket_upgrade
+from veilrender.config import settings
+from veilrender.routes import health, render, screenshot
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+async def _pipe(source: asyncio.StreamReader, dest: asyncio.StreamReader) -> None:
+    """Relay remaining data from *source* into *dest* until EOF."""
+    try:
+        while True:
+            chunk = await source.read(8192)
+            if not chunk:
+                break
+            dest.feed_data(chunk)
+    except Exception:
+        pass
+    finally:
+        dest.feed_eof()
+
+
+def create_app() -> App:
+    """Create and configure the VeilRender application."""
+    app = App(max_body_size=10 * 1024 * 1024)  # 10 MB
+
+    # Register routes
+    health.register(app)
+    render.register(app)
+    screenshot.register(app)
+
+    return app
+
+
+def main() -> None:
+    """Run the VeilRender server with HTTP + CDP WebSocket multiplexing."""
+    app = create_app()
+
+    async def run_server() -> None:
+        await browser_manager.start()
+
+        shutdown_event = asyncio.Event()
+
+        async def handle_connection(
+            reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+        ) -> None:
+            """Multiplex: WebSocket upgrade to /cdp → CDP proxy, else → HTTP."""
+            try:
+                # Peek at the first request to decide routing
+                raw = b""
+                while b"\r\n\r\n" not in raw:
+                    chunk = await asyncio.wait_for(reader.read(8192), timeout=30)
+                    if not chunk:
+                        writer.close()
+                        return
+                    raw += chunk
+
+                # Parse the request line and headers
+                header_block, _, body_start = raw.partition(b"\r\n\r\n")
+                lines = header_block.decode("latin-1").split("\r\n")
+                request_line = lines[0]
+                parts = request_line.split(" ", 2)
+                if len(parts) < 2:
+                    writer.close()
+                    return
+
+                method = parts[0].upper()
+                raw_path = parts[1]
+
+                # Parse path and query string
+                if "?" in raw_path:
+                    path, query_string = raw_path.split("?", 1)
+                else:
+                    path, query_string = raw_path, ""
+
+                # Parse headers
+                headers: dict[str, str] = {}
+                for line in lines[1:]:
+                    if ":" in line:
+                        key, _, value = line.partition(":")
+                        headers[key.strip().lower()] = value.strip()
+
+                # Check if this is a WebSocket upgrade to /cdp
+                if is_websocket_upgrade(method, headers, path):
+                    await handle_cdp_upgrade(
+                        reader,
+                        writer,
+                        headers,
+                        path,
+                        query_string,
+                        browser_manager.get_cdp_url,
+                    )
+                    return
+
+                # Otherwise, delegate to httpserver.
+                # Re-feed the buffered bytes and pipe any remaining body
+                # data from the original reader so POST bodies are not
+                # truncated (see #5).
+                combined_reader = asyncio.StreamReader()
+                combined_reader.feed_data(raw)
+                pipe_task = asyncio.create_task(_pipe(reader, combined_reader))
+                try:
+                    await app._handle_connection(combined_reader, writer)
+                finally:
+                    pipe_task.cancel()
+            except Exception:
+                logger.debug("Connection handler error", exc_info=True)
+                try:
+                    writer.close()
+                except Exception:
+                    pass
+
+        server = await asyncio.start_server(
+            handle_connection, settings.host, settings.port
+        )
+        addr = (
+            server.sockets[0].getsockname()
+            if server.sockets
+            else (settings.host, settings.port)
+        )
+        logger.info(
+            "VeilRender serving on %s:%d (auth=%s, cdp=ws://%s:%d/cdp)",
+            addr[0],
+            addr[1],
+            "enabled" if settings.api_token else "disabled",
+            addr[0],
+            addr[1],
+        )
+
+        loop = asyncio.get_running_loop()
+        if sys.platform != "win32":
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, shutdown_event.set)
+
+        try:
+            async with server:
+                await shutdown_event.wait()
+        finally:
+            await browser_manager.stop()
+
+    try:
+        asyncio.run(run_server())
+    except KeyboardInterrupt:
+        pass

src/veilrender/auth.py

@@ -0,0 +1,39 @@
+"""Token-based authentication."""
+
+from __future__ import annotations
+
+from veilrender._vendor.httpserver import HTTPException, Request
+from veilrender.config import settings
+
+
+def verify_token(request: Request) -> None:
+    """Verify the API token from header or query param.
+
+    Checks ``Authorization: Bearer <token>`` header first, then falls
+    back to ``?token=<token>`` query parameter.
+
+    Raises:
+        HTTPException: 401 if token is invalid, 403 if token is missing.
+
+    If ``VEILRENDER_API_TOKEN`` is not configured, auth is disabled.
+    """
+    expected = settings.api_token
+    if expected is None:
+        return
+
+    # Check Authorization header
+    auth_header = request.headers.get("authorization", "")
+    if auth_header.startswith("Bearer "):
+        token = auth_header[7:].strip()
+        if token == expected:
+            return
+        raise HTTPException(401, "Invalid token")
+
+    # Check query param
+    token_params = request.query_params.get("token", [])
+    if token_params:
+        if token_params[0] == expected:
+            return
+        raise HTTPException(401, "Invalid token")
+
+    raise HTTPException(403, "Authentication required")

src/veilrender/browser.py

@@ -0,0 +1,172 @@
+"""Playwright browser lifecycle management."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import subprocess
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator
+
+from cloakbrowser import ensure_binary, get_default_stealth_args
+from playwright.async_api import Browser, BrowserContext, Page, async_playwright
+
+from veilrender.config import settings
+
+logger = logging.getLogger(__name__)
+
+CDP_PORT = 9222
+
+
+class BrowserManager:
+    """Manages a shared Playwright browser instance.
+
+    Launches Chromium directly (not via Playwright's launch()) so that
+    ``--remote-debugging-port`` actually takes effect. Playwright then
+    connects over CDP, and the CDP port is also available for external
+    clients via the WebSocket proxy.
+    """
+
+    def __init__(self) -> None:
+        self._playwright = None
+        self._browser: Browser | None = None
+        self._chrome_proc: subprocess.Popen | None = None  # type: ignore[type-arg]
+        self._semaphore = asyncio.Semaphore(settings.max_concurrent)
+        self._lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        """Launch Chromium with CDP and connect Playwright to it."""
+        executable_path = ensure_binary()
+        stealth_args = get_default_stealth_args()
+
+        chrome_args = [
+            executable_path,
+            "--headless",
+            f"--remote-debugging-port={CDP_PORT}",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-setuid-sandbox",
+            "--disable-dev-shm-usage",
+            "--disable-gpu",
+            *stealth_args,
+            "about:blank",
+        ]
+
+        self._chrome_proc = subprocess.Popen(
+            chrome_args,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+        )
+
+        # Wait for CDP to be ready
+        cdp_url = f"http://127.0.0.1:{CDP_PORT}"
+        for attempt in range(30):
+            try:
+                import urllib.request
+
+                urllib.request.urlopen(f"{cdp_url}/json/version", timeout=1)
+                break
+            except Exception:
+                await asyncio.sleep(0.5)
+        else:
+            stderr = (
+                self._chrome_proc.stderr.read().decode()
+                if self._chrome_proc.stderr
+                else ""
+            )
+            raise RuntimeError(
+                f"Chromium CDP not ready after 15s. stderr: {stderr[:500]}"
+            )
+
+        # Connect Playwright over CDP
+        self._playwright = await async_playwright().start()
+        self._browser = await self._playwright.chromium.connect_over_cdp(
+            f"http://127.0.0.1:{CDP_PORT}"
+        )
+        logger.info(
+            "Browser started (CloakBrowser %s, CDP on :%d)", executable_path, CDP_PORT
+        )
+
+    async def get_cdp_url(self) -> str | None:
+        """Return the internal CDP WebSocket URL, or None if unavailable."""
+        await self._ensure_browser()
+        try:
+            import urllib.request
+            import json
+
+            resp = urllib.request.urlopen(
+                f"http://127.0.0.1:{CDP_PORT}/json/version", timeout=2
+            )
+            data = json.loads(resp.read())
+            ws_url = data.get("webSocketDebuggerUrl")
+            if ws_url:
+                return ws_url
+        except Exception:
+            logger.debug("Failed to get CDP WebSocket URL", exc_info=True)
+        return f"ws://127.0.0.1:{CDP_PORT}"
+
+    async def stop(self) -> None:
+        """Close the browser, Playwright, and Chromium process."""
+        if self._browser:
+            try:
+                await self._browser.close()
+            except Exception:
+                pass
+            self._browser = None
+        if self._playwright:
+            await self._playwright.stop()
+            self._playwright = None
+        if self._chrome_proc:
+            self._chrome_proc.terminate()
+            try:
+                self._chrome_proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._chrome_proc.kill()
+            self._chrome_proc = None
+        logger.info("Browser stopped")
+
+    async def _ensure_browser(self) -> Browser:
+        """Restart browser if it crashed."""
+        async with self._lock:
+            chrome_dead = (
+                self._chrome_proc is None or self._chrome_proc.poll() is not None
+            )
+            browser_dead = self._browser is None or not self._browser.is_connected()
+            if chrome_dead or browser_dead:
+                logger.warning("Browser not connected, restarting...")
+                await self.stop()
+                await self.start()
+            assert self._browser is not None
+            return self._browser
+
+    @asynccontextmanager
+    async def get_page(
+        self,
+        *,
+        viewport_width: int | None = None,
+        viewport_height: int | None = None,
+    ) -> AsyncIterator[tuple[BrowserContext, Page]]:
+        """Create an isolated browser context and page.
+
+        Yields:
+            A (context, page) tuple. Both are closed automatically.
+        """
+        async with self._semaphore:
+            browser = await self._ensure_browser()
+            context: BrowserContext | None = None
+            try:
+                context = await browser.new_context(
+                    viewport={
+                        "width": viewport_width or settings.viewport_width,
+                        "height": viewport_height or settings.viewport_height,
+                    },
+                    user_agent=None,  # use Playwright default
+                )
+                page = await context.new_page()
+                yield context, page
+            finally:
+                if context:
+                    await context.close()
+
+
+browser_manager = BrowserManager()

src/veilrender/cdp_proxy.py

@@ -0,0 +1,314 @@
+"""CDP WebSocket proxy — expose browser CDP over a single port.
+
+Handles WebSocket upgrade requests to ``/cdp`` and proxies CDP messages
+between the external client and an internal Chromium CDP endpoint.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import logging
+import os
+import struct
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from veilrender.auth import verify_token
+from veilrender._vendor.httpserver import Request
+
+logger = logging.getLogger(__name__)
+
+# WebSocket opcodes
+_OP_TEXT = 0x1
+_OP_BINARY = 0x2
+_OP_CLOSE = 0x8
+_OP_PING = 0x9
+_OP_PONG = 0xA
+
+_WS_MAGIC = b"258EAFA5-E914-47DA-95CA-5B0D11CF9245"
+
+# Maximum allowed WebSocket frame payload size (16 MB).
+# Frames exceeding this limit are rejected to prevent OOM from
+# malicious headers claiming excessively large payloads.
+MAX_FRAME_SIZE = 16 * 1024 * 1024
+
+
+def _accept_key(key: str) -> str:
+    """Compute Sec-WebSocket-Accept from Sec-WebSocket-Key."""
+    digest = hashlib.sha1(key.encode() + _WS_MAGIC).digest()
+    return base64.b64encode(digest).decode()
+
+
+async def _read_ws_frame(
+    reader: asyncio.StreamReader,
+) -> tuple[bool, int, bytes] | None:
+    """Read one WebSocket frame. Returns (fin, opcode, payload) or None on EOF."""
+    try:
+        head = await reader.readexactly(2)
+    except (asyncio.IncompleteReadError, ConnectionError):
+        return None
+
+    fin = bool(head[0] & 0x80)
+    opcode = head[0] & 0x0F
+    masked = bool(head[1] & 0x80)
+    length = head[1] & 0x7F
+
+    if length == 126:
+        raw = await reader.readexactly(2)
+        length = struct.unpack("!H", raw)[0]
+    elif length == 127:
+        raw = await reader.readexactly(8)
+        length = struct.unpack("!Q", raw)[0]
+
+    if length > MAX_FRAME_SIZE:
+        logger.warning("WebSocket frame too large (%d bytes), dropping", length)
+        return None
+
+    if masked:
+        mask = await reader.readexactly(4)
+        data = bytearray(await reader.readexactly(length))
+        for i in range(length):
+            data[i] ^= mask[i % 4]
+        return fin, opcode, bytes(data)
+    else:
+        data = await reader.readexactly(length)
+        return fin, opcode, data
+
+
+def _make_ws_frame(
+    opcode: int, payload: bytes, *, fin: bool = True, mask: bool = False
+) -> bytes:
+    """Build a WebSocket frame."""
+    frame = bytearray()
+    frame.append((0x80 if fin else 0x00) | opcode)
+
+    length = len(payload)
+    if length < 126:
+        frame.append((0x80 if mask else 0) | length)
+    elif length < 65536:
+        frame.append((0x80 if mask else 0) | 126)
+        frame.extend(struct.pack("!H", length))
+    else:
+        frame.append((0x80 if mask else 0) | 127)
+        frame.extend(struct.pack("!Q", length))
+
+    if mask:
+        mask_key = os.urandom(4)
+        frame.extend(mask_key)
+        masked = bytearray(payload)
+        for i in range(length):
+            masked[i] ^= mask_key[i % 4]
+        frame.extend(masked)
+    else:
+        frame.extend(payload)
+
+    return bytes(frame)
+
+
+async def _proxy_ws(
+    src_reader: asyncio.StreamReader,
+    dst_writer: asyncio.StreamWriter,
+    *,
+    src_masked: bool,
+    dst_mask: bool,
+    label: str,
+) -> None:
+    """Forward WebSocket frames from src to dst until close/EOF."""
+    while True:
+        result = await _read_ws_frame(src_reader)
+        if result is None:
+            break
+
+        fin, opcode, payload = result
+
+        if opcode == _OP_CLOSE:
+            frame = _make_ws_frame(_OP_CLOSE, payload, fin=True, mask=dst_mask)
+            dst_writer.write(frame)
+            await dst_writer.drain()
+            break
+        elif opcode == _OP_PING:
+            # Forward pings as-is to the other side
+            frame = _make_ws_frame(_OP_PING, payload, fin=True, mask=dst_mask)
+            dst_writer.write(frame)
+            await dst_writer.drain()
+        else:
+            frame = _make_ws_frame(opcode, payload, fin=fin, mask=dst_mask)
+            dst_writer.write(frame)
+            await dst_writer.drain()
+
+
+def is_websocket_upgrade(method: str, headers: dict[str, str], path: str) -> bool:
+    """Check if this HTTP request is a WebSocket upgrade to /cdp."""
+    if not path.startswith("/cdp"):
+        return False
+    upgrade = headers.get("upgrade", "").lower()
+    connection = headers.get("connection", "").lower()
+    return method == "GET" and "websocket" in upgrade and "upgrade" in connection
+
+
+async def handle_cdp_upgrade(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    headers: dict[str, str],
+    path: str,
+    query_string: str,
+    get_cdp_url: Callable[[], Coroutine[Any, Any, str | None]],
+) -> None:
+    """Handle a WebSocket upgrade for CDP proxying.
+
+    Args:
+        reader: Client's stream reader.
+        writer: Client's stream writer.
+        headers: Parsed HTTP headers from the upgrade request.
+        path: Request path.
+        query_string: Raw query string.
+        get_cdp_url: Async callable that returns the internal CDP WebSocket URL,
+            or None if no browser is available.
+    """
+    # Auth check — build a minimal Request object for verify_token
+    try:
+        req = Request(
+            method="GET",
+            path=path,
+            query_string=query_string,
+            headers=headers,
+            body=b"",
+            client_addr=writer.get_extra_info("peername") or ("0.0.0.0", 0),
+        )
+        verify_token(req)
+    except Exception:
+        writer.write(b"HTTP/1.1 401 Unauthorized\r\n\r\n")
+        await writer.drain()
+        writer.close()
+        return
+
+    # Get WebSocket accept key
+    ws_key = headers.get("sec-websocket-key", "")
+    if not ws_key:
+        writer.write(b"HTTP/1.1 400 Bad Request\r\n\r\nMissing Sec-WebSocket-Key\r\n")
+        await writer.drain()
+        writer.close()
+        return
+
+    # Get internal CDP URL
+    cdp_url = await get_cdp_url()
+    if cdp_url is None:
+        writer.write(
+            b"HTTP/1.1 503 Service Unavailable\r\n\r\nNo browser available\r\n"
+        )
+        await writer.drain()
+        writer.close()
+        return
+
+    # Connect to internal CDP
+    # Parse ws://host:port/path from cdp_url
+    from urllib.parse import urlparse
+
+    parsed = urlparse(cdp_url)
+    cdp_host = parsed.hostname or "127.0.0.1"
+    cdp_port = parsed.port or 9222
+    cdp_path = parsed.path or "/"
+
+    try:
+        cdp_reader, cdp_writer = await asyncio.open_connection(cdp_host, cdp_port)
+    except Exception as exc:
+        logger.error("Failed to connect to CDP at %s: %s", cdp_url, exc)
+        writer.write(b"HTTP/1.1 502 Bad Gateway\r\n\r\n")
+        await writer.drain()
+        writer.close()
+        return
+
+    # WebSocket handshake with internal CDP
+    cdp_ws_key = base64.b64encode(os.urandom(16)).decode()
+    ws_protocol = headers.get("sec-websocket-protocol", "")
+    handshake = (
+        f"GET {cdp_path} HTTP/1.1\r\n"
+        f"Host: {cdp_host}:{cdp_port}\r\n"
+        f"Upgrade: websocket\r\n"
+        f"Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Version: 13\r\n"
+        f"Sec-WebSocket-Key: {cdp_ws_key}\r\n"
+    )
+    if ws_protocol:
+        handshake += f"Sec-WebSocket-Protocol: {ws_protocol}\r\n"
+    handshake += "\r\n"
+    cdp_writer.write(handshake.encode())
+    await cdp_writer.drain()
+
+    # Read CDP handshake response
+    cdp_response = b""
+    while b"\r\n\r\n" not in cdp_response:
+        chunk = await cdp_reader.read(4096)
+        if not chunk:
+            logger.error("CDP handshake failed: connection closed")
+            writer.write(b"HTTP/1.1 502 Bad Gateway\r\n\r\n")
+            await writer.drain()
+            writer.close()
+            cdp_writer.close()
+            return
+        cdp_response += chunk
+
+    if b"101" not in cdp_response.split(b"\r\n")[0]:
+        logger.error("CDP handshake failed: %s", cdp_response[:200])
+        writer.write(b"HTTP/1.1 502 Bad Gateway\r\n\r\n")
+        await writer.drain()
+        writer.close()
+        cdp_writer.close()
+        return
+
+    # Complete WebSocket handshake with the external client
+    accept = _accept_key(ws_key)
+    response = (
+        f"HTTP/1.1 101 Switching Protocols\r\n"
+        f"Upgrade: websocket\r\n"
+        f"Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Accept: {accept}\r\n"
+    )
+    if ws_protocol:
+        response += f"Sec-WebSocket-Protocol: {ws_protocol}\r\n"
+    response += "\r\n"
+    writer.write(response.encode())
+    await writer.drain()
+
+    logger.info("CDP proxy session started")
+
+    # Bidirectional proxy — when one direction ends, cancel the other
+    t1 = asyncio.create_task(
+        _proxy_ws(
+            reader,
+            cdp_writer,
+            src_masked=True,
+            dst_mask=True,
+            label="client→cdp",
+        )
+    )
+    t2 = asyncio.create_task(
+        _proxy_ws(
+            cdp_reader,
+            writer,
+            src_masked=False,
+            dst_mask=False,
+            label="cdp→client",
+        )
+    )
+
+    try:
+        done, pending = await asyncio.wait(
+            {t1, t2}, return_when=asyncio.FIRST_COMPLETED
+        )
+        for t in pending:
+            t.cancel()
+        # Await cancelled tasks to suppress warnings
+        for t in pending:
+            try:
+                await t
+            except asyncio.CancelledError:
+                pass
+    except Exception as exc:
+        logger.debug("CDP proxy ended: %s", exc)
+    finally:
+        logger.info("CDP proxy session ended")
+        cdp_writer.close()
+        writer.close()

src/veilrender/config.py

@@ -0,0 +1,25 @@
+"""Application settings loaded from environment variables."""
+
+from __future__ import annotations
+
+import os
+
+
+class Settings:
+    """Configuration from ``VEILRENDER_*`` environment variables."""
+
+    def __init__(self) -> None:
+        self.api_token: str | None = os.environ.get("VEILRENDER_API_TOKEN")
+        self.port: int = int(os.environ.get("VEILRENDER_PORT", "7860"))
+        self.host: str = os.environ.get("VEILRENDER_HOST", "0.0.0.0")
+        self.timeout: int = int(os.environ.get("VEILRENDER_TIMEOUT", "30000"))
+        self.viewport_width: int = int(
+            os.environ.get("VEILRENDER_VIEWPORT_WIDTH", "1280")
+        )
+        self.viewport_height: int = int(
+            os.environ.get("VEILRENDER_VIEWPORT_HEIGHT", "720")
+        )
+        self.max_concurrent: int = int(os.environ.get("VEILRENDER_MAX_CONCURRENT", "3"))
+
+
+settings = Settings()

src/veilrender/models.py

@@ -0,0 +1,109 @@
+"""Request and response data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+WaitUntil = Literal["commit", "domcontentloaded", "load", "networkidle"]
+
+
+@dataclass
+class RenderRequest:
+    """POST /render request body."""
+
+    url: str
+    formats: list[str] = field(
+        default_factory=lambda: ["html", "markdown", "readability"]
+    )
+    wait_until: WaitUntil = "networkidle"
+    timeout: int | None = None  # ms, None = use default
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RenderRequest:
+        """Create from parsed JSON dict."""
+        return cls(
+            url=data["url"],
+            formats=data.get("formats", ["html", "markdown", "readability"]),
+            wait_until=data.get("wait_until", "networkidle"),
+            timeout=data.get("timeout"),
+        )
+
+
+@dataclass
+class ScreenshotRequest:
+    """POST /screenshot request body."""
+
+    url: str
+    full_page: bool = False
+    wait_until: WaitUntil = "networkidle"
+    timeout: int | None = None
+    viewport_width: int | None = None
+    viewport_height: int | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ScreenshotRequest:
+        """Create from parsed JSON dict."""
+        return cls(
+            url=data["url"],
+            full_page=data.get("full_page", False),
+            wait_until=data.get("wait_until", "networkidle"),
+            timeout=data.get("timeout"),
+            viewport_width=data.get("viewport_width"),
+            viewport_height=data.get("viewport_height"),
+        )
+
+
+@dataclass
+class LinkInfo:
+    """Extracted link from a page."""
+
+    url: str
+    text: str
+
+
+@dataclass
+class PageMetadata:
+    """Metadata extracted from a rendered page."""
+
+    title: str
+    url: str
+    status_code: int
+
+
+@dataclass
+class RenderContent:
+    """Rendered content in multiple formats."""
+
+    html: str | None = None
+    markdown: str | None = None
+    readability: str | None = None
+
+
+@dataclass
+class RenderResponse:
+    """POST /render response body."""
+
+    content: RenderContent
+    metadata: PageMetadata
+    links: list[LinkInfo]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to JSON-compatible dict."""
+        return {
+            "content": {
+                k: v
+                for k, v in {
+                    "html": self.content.html,
+                    "markdown": self.content.markdown,
+                    "readability": self.content.readability,
+                }.items()
+                if v is not None
+            },
+            "metadata": {
+                "title": self.metadata.title,
+                "url": self.metadata.url,
+                "status_code": self.metadata.status_code,
+            },
+            "links": [{"url": link.url, "text": link.text} for link in self.links],
+        }

src/veilrender/routes/__init__.py

@@ -0,0 +1 @@
+"""Route handlers."""

src/veilrender/routes/health.py

@@ -0,0 +1,17 @@
+"""Health check endpoint."""
+
+from __future__ import annotations
+
+from veilrender._vendor.httpserver import App, JSONResponse, Request
+
+
+def register(app: App) -> None:
+    """Register health check routes on the app."""
+
+    @app.get("/health")
+    async def health(request: Request) -> JSONResponse:
+        return JSONResponse({"status": "ok"})
+
+    @app.get("/")
+    async def root(request: Request) -> JSONResponse:
+        return JSONResponse({"service": "veilrender", "status": "ok"})

src/veilrender/routes/render.py

@@ -0,0 +1,122 @@
+"""Page rendering endpoint."""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from veilrender._vendor.httpserver import App, JSONResponse, Request
+from veilrender._vendor.readability import extract as readability_extract
+from veilrender._vendor.soup import Soup
+from veilrender.auth import verify_token
+from veilrender.browser import browser_manager
+from veilrender.config import settings
+from veilrender.models import (
+    LinkInfo,
+    PageMetadata,
+    RenderContent,
+    RenderRequest,
+    RenderResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_links(html: str, base_url: str) -> list[LinkInfo]:
+    """Extract links from HTML using zerodep soup."""
+    links: list[LinkInfo] = []
+    try:
+        soup = Soup(html)
+        for a in soup.find_all("a", href=True):
+            href = a.get("href", "")
+            text = a.get_text(strip=True)
+            if href and not href.startswith(("#", "javascript:")):
+                links.append(LinkInfo(url=href, text=text))
+    except Exception:
+        logger.debug("Failed to extract links", exc_info=True)
+    return links
+
+
+def _html_to_markdown(html: str) -> str:
+    """Simple HTML to Markdown conversion using readability text output.
+
+    This is a lightweight conversion: we extract readable content and
+    return the plain-text representation, which is sufficient for LLM
+    consumption. For full-fidelity HTML→Markdown, a dedicated converter
+    (like markdownify) would be needed.
+    """
+    try:
+        result = readability_extract(html)
+        return result.text
+    except Exception:
+        # Fallback: strip tags and return raw text
+        return re.sub(r"<[^>]+>", "", html)
+
+
+def register(app: App) -> None:
+    """Register render routes on the app."""
+
+    @app.post("/render")
+    async def render(request: Request) -> JSONResponse:
+        verify_token(request)
+
+        try:
+            data = request.json()
+        except Exception:
+            return JSONResponse({"error": "Invalid JSON body"}, status_code=400)
+
+        if "url" not in data:
+            return JSONResponse({"error": "Missing 'url' field"}, status_code=400)
+
+        req = RenderRequest.from_dict(data)
+        timeout = req.timeout or settings.timeout
+
+        try:
+            async with browser_manager.get_page() as (ctx, page):
+                response = await page.goto(
+                    req.url,
+                    wait_until=req.wait_until,
+                    timeout=timeout,
+                )
+                status_code = response.status if response else 0
+                title = await page.title()
+                final_url = page.url
+                html = await page.content()
+        except Exception as exc:
+            logger.error("Render failed for %s: %s", req.url, exc)
+            return JSONResponse(
+                {"error": f"Render failed: {exc!s}"},
+                status_code=502,
+            )
+
+        # Build content based on requested formats
+        content = RenderContent()
+
+        if "html" in req.formats:
+            content.html = html
+
+        if "readability" in req.formats:
+            try:
+                rd = readability_extract(html, url=final_url)
+                content.readability = rd.text
+            except Exception:
+                logger.debug("Readability extraction failed", exc_info=True)
+                content.readability = None
+
+        if "markdown" in req.formats:
+            content.markdown = _html_to_markdown(html)
+
+        # Extract links
+        links = _extract_links(html, final_url)
+
+        result = RenderResponse(
+            content=content,
+            metadata=PageMetadata(
+                title=title,
+                url=final_url,
+                status_code=status_code,
+            ),
+            links=links,
+        )
+
+        return JSONResponse(result.to_dict())

src/veilrender/routes/screenshot.py

@@ -0,0 +1,65 @@
+"""Screenshot endpoint."""
+
+from __future__ import annotations
+
+import logging
+
+from veilrender._vendor.httpserver import App, Request, Response
+from veilrender.auth import verify_token
+from veilrender.browser import browser_manager
+from veilrender.config import settings
+from veilrender.models import ScreenshotRequest
+
+logger = logging.getLogger(__name__)
+
+
+def register(app: App) -> None:
+    """Register screenshot routes on the app."""
+
+    @app.post("/screenshot")
+    async def screenshot(request: Request) -> Response:
+        verify_token(request)
+
+        try:
+            data = request.json()
+        except Exception:
+            return Response(
+                body=b'{"error": "Invalid JSON body"}',
+                status_code=400,
+                content_type="application/json",
+            )
+
+        if "url" not in data:
+            return Response(
+                body=b'{"error": "Missing \'url\' field"}',
+                status_code=400,
+                content_type="application/json",
+            )
+
+        req = ScreenshotRequest.from_dict(data)
+        timeout = req.timeout or settings.timeout
+
+        try:
+            async with browser_manager.get_page(
+                viewport_width=req.viewport_width,
+                viewport_height=req.viewport_height,
+            ) as (ctx, page):
+                await page.goto(
+                    req.url,
+                    wait_until=req.wait_until,
+                    timeout=timeout,
+                )
+                png_bytes = await page.screenshot(full_page=req.full_page)
+        except Exception as exc:
+            logger.error("Screenshot failed for %s: %s", req.url, exc)
+            return Response(
+                body=f'{{"error": "Screenshot failed: {exc!s}"}}'.encode(),
+                status_code=502,
+                content_type="application/json",
+            )
+
+        return Response(
+            body=png_bytes,
+            status_code=200,
+            content_type="image/png",
+        )