{"id":44850347,"url":"https://github.com/fsecada01/component-framework","last_synced_at":"2026-07-01T23:01:43.133Z","repository":{"id":338736353,"uuid":"1158928248","full_name":"fsecada01/component-framework","owner":"fsecada01","description":"Framework-agnostic server components with LiveView-style interactivity for Python (FastAPI / Django). HTMX-powered, no JS framework required.","archived":false,"fork":false,"pushed_at":"2026-06-24T20:49:33.000Z","size":1352,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-24T21:19:15.415Z","etag":null,"topics":["django","fastapi","htmx","liveview","pydantic","python","server-components","server-side-rendering","websocket"],"latest_commit_sha":null,"homepage":"https://fsecada01.github.io/component-framework/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fsecada01.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T05:04:32.000Z","updated_at":"2026-06-24T20:47:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fsecada01/component-framework","commit_stats":null,"previous_names":["fsecada01/component-framework"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/fsecada01/component-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fcomponent-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fcomponent-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fcomponent-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fcomponent-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fsecada01","download_url":"https://codeload.github.com/fsecada01/component-framework/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fcomponent-framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35025983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","fastapi","htmx","liveview","pydantic","python","server-components","server-side-rendering","websocket"],"created_at":"2026-02-17T06:18:50.871Z","updated_at":"2026-07-01T23:01:43.126Z","avatar_url":"https://github.com/fsecada01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Component Framework\n\n\u003e **BETA SOFTWARE** — APIs are stabilising. Core features are complete and test-covered. Minor breaking changes may still occur before 1.0.\n\nFramework-agnostic server components with LiveView-style interactivity inspired by Phoenix LiveView and Laravel Livewire.\n\n[![CI](https://github.com/fsecada01/component-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/fsecada01/component-framework/actions/workflows/ci.yml)\n[![Docs](https://github.com/fsecada01/component-framework/actions/workflows/docs.yml/badge.svg)](https://github.com/fsecada01/component-framework/actions/workflows/docs.yml)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Status: Beta](https://img.shields.io/badge/status-beta-blue.svg)](https://fsecada01.github.io/component-framework/)\n\n---\n\n## Development Status\n\n**Current Version:** 0.5.1-beta\n**API Documentation:** [fsecada01.github.io/component-framework](https://fsecada01.github.io/component-framework/)\n\nThe framework has a complete, tested feature set covering the full Beta roadmap. APIs are solidifying — the core lifecycle, permissions, composition, and testing utilities are stable. We welcome feedback before the 1.0 release.\n\n---\n\n## Adapter Support\n\n| Framework | Status | Install extra | Notes |\n|-----------|--------|---------------|-------|\n| **FastAPI** | ✅ Supported | `[fastapi]` | Includes JinjaX renderer and WebSocket adapter |\n| **Django** | ✅ Supported | `[django]` | Includes Channels, Cotton, and template renderer |\n| **Litestar** | ✅ Supported | `[litestar]` | HTTP + WebSocket adapters (0.4.0+) |\n| **Flask** | ✅ Supported | `[flask]` | Jinja2 renderer + HTTP blueprint |\n\n---\n\n## Installation\n\nInstall only what you need — `pydantic` is the only mandatory dependency:\n\n```bash\n# Django projects\npip install \"component-framework[django]\"\n\n# FastAPI projects\npip install \"component-framework[fastapi]\"\n\n# Litestar projects\npip install \"component-framework[litestar]\"\n\n# Flask projects\npip install \"component-framework[flask]\"\n\n# Multiple adapters\npip install \"component-framework[fastapi,django,litestar,flask]\"\n\n# Everything\npip install \"component-framework[all]\"\n```\n\n### Migrating from 0.2.x\n\n\u003e ⚠️ **Breaking change in 0.3.0**: `fastapi`, `uvicorn`, and `jinjax` are no longer\n\u003e installed by default.\n\nIf you were using the FastAPI adapter, add `[fastapi]` to your install command:\n\n```bash\n# Before\npip install component-framework\n\n# After\npip install \"component-framework[fastapi]\"\n```\n\n**CI pipelines** — any workflow step that installs `component-framework` without\nspecifying an extras group will stop receiving FastAPI automatically. Update all\ninstall commands in your GitHub Actions, Dockerfile, tox.ini, Makefile, or other\nCI configuration files.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full list of changes.\n\n---\n\n## Features\n\n### Core\n- **Framework-agnostic** — Works with FastAPI, Django, Litestar, and more\n- **Server-driven UI** — State lives on the server, not the client\n- **Minimal JavaScript** — HTMX handles frontend interactions\n- **Reusable components** — Clean OOP boundaries with lifecycle hooks\n- **Pluggable renderers** — Jinjax, Django templates, or your own\n- **Async event handlers** — `async def on_*` handlers properly awaited via `async_dispatch()`\n- **SSE streaming** — `StreamingComponent` for long-running operations with intermediate renders\n- **State size guard** — Configurable warning (64 KB) and hard limit (512 KB) on serialised state\n\n### Forms \u0026 Validation\n- **Pydantic validation** — Type-safe form handling\n- **Field-level errors** — Live error feedback\n- **Automatic state sync** — Form state synchronised with component state\n\n### Access Control\n- **Permission classes** — `AllowAny`, `IsAuthenticated`, `IsStaff`, `IsSuperuser`, `DjangoModelPermission`\n- **FBV decorators** — `login_required_component`, `permission_required_component`, `staff_required_component` returning JSON 401/403\n- **Component-level control** — `permission_classes` attribute checked by both FBV and CBV automatically\n- **JSON-only responses** — No login redirects for API/HTMX consumers\n\n### Rate Limiting\n- **`RateLimitMixin`** — Per-component, per-user sliding-window rate limiting\n- **Configurable** — Custom limits and windows per component class\n- **429 responses** — Consistent JSON `{\"error\": \"Rate limit exceeded\"}` on breach\n\n### Component Composition\n- **`SlotComponent`** — Named and default slot support\n- **`CompositeComponent`** — Compose components from named child components\n- **Context propagation** — Parent context flows to child components\n\n### Optimistic UI\n- **`OptimisticMixin`** — `get_optimistic_patch()` for instant client-side feedback before server confirmation\n- **Rollback support** — Revert on error\n\n### Django Integration\n- **Model binding** — Direct ORM integration\n- **Query optimisation** — `select_related`, `prefetch_related`\n- **Transaction support** — Safe database updates\n- **Django templates** — Native template rendering\n- **Cotton support** — `django-cotton` integration\n- **CBVs** — Class-based views with auth/permissions, JSON error responses\n\n### Real-Time Updates\n- **WebSocket support** — Real-time component updates\n- **SSE streaming** — `StreamingComponent` with async generator handlers for progressive rendering\n- **Broadcasting** — Multi-client synchronisation\n- **Django Channels** — Full Channels integration\n- **FastAPI WebSocket** — Native FastAPI support\n- **Litestar WebSocket** — Native Litestar support\n\n### Caching\n- **`CacheMixin`** — Configurable per-component render caching\n- **Cache invalidation** — Manual and event-driven invalidation\n- **Django cache backend** — Works with any Django cache backend\n\n### Testing Utilities\n- **`ComponentTestCase`** — Test components without HTTP, without a running server\n- **Event simulation** — `dispatch_event()`, `mount_component()`\n- **State assertions** — `assert_state()`, `assert_rendered()`\n- **pytest fixtures** — Ready-to-use fixtures for common patterns\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\ngit clone https://github.com/fsecada01/component-framework.git\ncd component-framework\n\n# Install with uv (recommended)\nuv pip install -e \".[dev]\"\n```\n\n### FastAPI Example\n\n```bash\npython examples/fastapi_example.py\n# Open http://localhost:8000\n```\n\n#### Sharing an existing JinjaX catalog\n\nMost FastAPI + JinjaX projects already create a `Catalog` at startup — often\nsharing its Jinja environment with `Jinja2Templates` so page templates and\ncomponents see the same custom filters, globals (e.g. `url_for`), and extensions.\n\n**Pass that existing catalog to `JinjaxRenderer`** — do not create a new one:\n\n```python\n# consts.py — your existing setup\nfrom fastapi.templating import Jinja2Templates\nfrom jinjax import Catalog, JinjaX\n\ntemplates = Jinja2Templates(directory=\"templates\")\ntemplates.env.add_extension(JinjaX)              # share one Jinja environment\ntemplates.env.globals[\"url_for\"] = my_url_for    # custom global\ncatalog = Catalog(jinja_env=templates.env)       # catalog reuses that env\ncatalog.add_folder(\"templates/components\")\n\n# Wire the component framework to the SAME catalog\nfrom component_framework.adapters.jinjax_renderer import JinjaxRenderer\nfrom component_framework.core.component import Component\n\nComponent.renderer = JinjaxRenderer(catalog)     # ✅ inherits filters/globals/extensions\n```\n\n\u003e ⚠️ Creating a **fresh** `Catalog()` (as in minimal examples) gives it a *new,\n\u003e empty* Jinja environment. Component templates then silently lose your\n\u003e `url_for`, custom filters, and extensions and render incorrectly. Always hand\n\u003e `JinjaxRenderer` the catalog your app already configured.\n\n### Django Example\n\n```bash\ncd examples/django_example\npython manage.py migrate\npython manage.py runserver\n# Open http://localhost:8000\n```\n\n### Flask Example\n\n```bash\npip install \"component-framework[flask]\"\npython examples/flask_example.py\n# Open http://localhost:5000\n```\n\nWire the endpoint and a shared renderer into your own app:\n\n```python\nfrom flask import Flask\nfrom component_framework.adapters.flask import FlaskRenderer, register_component_routes\nfrom component_framework.core.component import Component\n\napp = Flask(__name__)\nComponent.renderer = FlaskRenderer(app)   # shares app.jinja_env (filters/globals)\nregister_component_routes(app)            # POST /components/\u003cname\u003e\n```\n\n---\n\n## Documentation\n\n**API Reference:** [fsecada01.github.io/component-framework](https://fsecada01.github.io/component-framework/)\n\nGenerated from docstrings by pdoc and deployed to GitHub Pages on every push to `master` and on every `v*` release tag.\n\n| Guide | Description |\n|-------|-------------|\n| [Architecture Overview](docs/server_component_spec.md) | Core design and component lifecycle |\n| [Django Implementation](docs/DJANGO_IMPLEMENTATION.md) | Django adapter setup and patterns |\n| [Class-Based Views](docs/CBV_GUIDE.md) | CBV auth/permission patterns |\n| [State Signing](docs/STATE_SIGNING.md) | HMAC-signed client state: setup per adapter + key rotation |\n| [Locked Fields](docs/LOCKED_FIELDS.md) | Server-trusted state fields the client can never influence (replay/rollback defense) |\n| [E-Commerce Example](docs/examples/ecommerce.md) | Real-time cart + product demo |\n| [Multi-Step Wizard](docs/examples/wizard.md) | FastAPI wizard recipe (enable [state signing](docs/STATE_SIGNING.md) in production) |\n| [CSRF \u0026 CSWSH Guide](docs/SECURITY_CSRF.md) | Per-adapter CSRF coverage audit + WebSocket hijacking guidance |\n\n### AI / LLM Context\n\n- [Project Context](CLAUDE.md) — loaded automatically by Claude Code\n- [Orchestration Workflow](prompts/WORKFLOW.md) — multi-agent routing, model selection, RTK\n\n---\n\n## Example Components\n\n### Simple Counter\n\n```python\nfrom component_framework.core import Component, registry\n\n@registry.register(\"counter\")\nclass Counter(Component):\n    template_name = \"counter.html\"\n\n    def mount(self):\n        self.state[\"count\"] = 0\n\n    def on_increment(self, amount: int = 1):\n        self.state[\"count\"] += amount\n```\n\n### Form with Validation\n\n```python\nfrom pydantic import BaseModel, EmailStr\nfrom component_framework.core import FormComponent\n\nclass ContactSchema(BaseModel):\n    name: str\n    email: EmailStr\n    message: str\n\n@registry.register(\"contact_form\")\nclass ContactForm(FormComponent):\n    schema = ContactSchema\n\n    def on_submit(self):\n        send_email(self.validated_data)\n```\n\n### Component with Permissions \u0026 Rate Limiting\n\n```python\nfrom component_framework.core.permissions import IsAuthenticated\nfrom component_framework.adapters.django_ratelimit import RateLimitMixin\n\n@registry.register(\"order_actions\")\nclass OrderActions(RateLimitMixin, Component):\n    permission_classes = [IsAuthenticated]\n    rate_limit = 10          # requests\n    rate_limit_window = 60   # seconds\n\n    def on_submit_order(self):\n        ...\n```\n\n### Component Composition\n\n```python\nfrom component_framework.core.composition import SlotComponent, CompositeComponent\n\n@registry.register(\"card\")\nclass Card(SlotComponent):\n    template_name = \"card.html\"\n    slots = [\"header\", \"body\", \"footer\"]\n\n@registry.register(\"product_page\")\nclass ProductPage(CompositeComponent):\n    components = {\n        \"card\": Card,\n        \"cart\": CartComponent,\n    }\n```\n\n### Django Model Component\n\n```python\nfrom component_framework.adapters.django_model import DjangoModelComponent\n\n@registry.register(\"order_editor\")\nclass OrderEditor(DjangoModelComponent):\n    model = Order\n    state_fields = [\"status\", \"notes\", \"total\"]\n    select_related = [\"customer\"]\n\n    def on_update_status(self, status: str):\n        self.instance.status = status\n        self.save_instance()\n```\n\n### Testing with ComponentTestCase\n\n```python\nfrom component_framework.testing import ComponentTestCase\n\nclass TestCounter(ComponentTestCase):\n    def test_increment(self):\n        component = self.mount_component(\"counter\")\n        self.assert_state(component, count=0)\n        self.dispatch_event(component, \"increment\", amount=5)\n        self.assert_state(component, count=5)\n```\n\n---\n\n## Architecture\n\n```\nBrowser (HTMX/WebSocket/SSE)\n        |\nFramework Adapter  (FastAPI / Django / Litestar)\n        |\nComponent Framework Core\n  - Component lifecycle  (mount → hydrate → handle_event → render → dehydrate)\n  - Event routing        (convention-based on_\u003cevent\u003e handlers, sync + async)\n  - State management     (server-owned JSON state with size guards)\n  - Streaming            (StreamingComponent for SSE progressive rendering)\n  - Permissions          (per-component permission_classes)\n  - Composition          (SlotComponent, CompositeComponent)\n        |\nBackend (Database / Services)\n```\n\n---\n\n## Project Structure\n\n```\ncomponent-framework/\n├── src/component_framework/\n│   ├── core/                        # Framework-agnostic core\n│   │   ├── component.py             # Base Component class + lifecycle\n│   │   ├── form.py                  # Pydantic form validation\n│   │   ├── websocket.py             # WebSocket manager\n│   │   ├── registry.py              # Component registration\n│   │   ├── renderer.py              # Renderer interface\n│   │   ├── state.py                 # State storage\n│   │   ├── streaming.py             # StreamingComponent + SSE support\n│   │   ├── permissions.py           # Permission classes (Beta)\n│   │   └── composition.py           # Slot + composite components (Beta)\n│   │\n│   ├── adapters/                    # Framework adapters\n│   │   ├── fastapi.py               # FastAPI integration\n│   │   ├── fastapi_websocket.py     # FastAPI WebSocket\n│   │   ├── django_views.py          # Django views (FBV + CBV)\n│   │   ├── django_model.py          # Django model binding\n│   │   ├── django_renderer.py       # Django template rendering\n│   │   ├── django_websocket.py      # Django Channels\n│   │   ├── django_permissions.py    # FBV permission decorators (Beta)\n│   │   ├── django_ratelimit.py      # Rate limiting mixin (Beta)\n│   │   ├── jinjax_renderer.py       # Jinjax rendering\n│   │   ├── litestar.py              # Litestar HTTP + SSE adapter\n│   │   └── litestar_websocket.py    # Litestar WebSocket adapter\n│   │\n│   ├── testing.py                   # ComponentTestCase + fixtures (Beta)\n│   ├── components/                  # Example components\n│   └── templatetags/components.py   # Django template tags\n│\n├── examples/\n│   ├── fastapi_example.py           # FastAPI demo\n│   ├── fastapi_wizard_example.py    # Multi-step wizard demo\n│   ├── litestar_example.py          # Litestar demo\n│   └── django_example/              # Complete Django app\n│\n├── tests/                           # 23 test modules, 404 tests\n│   ├── test_component.py            # Core component + async dispatch tests\n│   ├── test_form.py                 # Form validation tests\n│   ├── test_registry.py             # Registry tests\n│   ├── test_state.py                # State storage tests\n│   ├── test_streaming.py            # StreamingComponent + SSE tests\n│   ├── test_websocket.py            # WebSocket manager tests\n│   ├── test_fastapi_adapter.py      # FastAPI adapter tests\n│   ├── test_fastapi_sse.py          # FastAPI SSE endpoint tests\n│   ├── test_fastapi_websocket.py    # FastAPI WebSocket tests\n│   ├── test_litestar_adapter.py     # Litestar adapter tests\n│   ├── test_litestar_sse.py         # Litestar SSE endpoint tests\n│   ├── test_django_views.py         # Django views tests\n│   ├── test_django_model.py         # Django model binding tests\n│   ├── test_django_renderer.py      # Django renderer tests\n│   ├── test_django_websocket.py     # Django Channels tests\n│   ├── test_templatetags.py         # Template tags tests\n│   ├── test_permissions.py          # Permission class tests (Beta)\n│   ├── test_composition.py          # Composition tests (Beta)\n│   ├── test_testing_utils.py        # Testing utility tests (Beta)\n│   ├── test_caching.py              # Cache mixin tests (Beta)\n│   ├── test_ratelimit.py            # Rate limit tests (Beta)\n│   ├── test_optimistic.py           # Optimistic UI tests (Beta)\n│   └── test_optional_extras.py      # Optional extras isolation tests\n│\n├── docs/                            # Documentation\n│   ├── make.py                      # pdoc build script\n│   ├── docs_settings.py             # Minimal Django settings for pdoc\n│   ├── pdoc_templates/              # Custom pdoc templates (terminal brutalism)\n│   ├── update_gh_pages.py           # CI helper: versions.json + root index\n│   └── examples/\n│       ├── ecommerce.md             # Real-time e-commerce walkthrough\n│       └── wizard.md                # Multi-step wizard recipe (FastAPI)\n│\n├── .github/workflows/\n│   ├── ci.yml                       # Tests, lint, type check (Python 3.11–3.14)\n│   └── docs.yml                     # pdoc build + versioned GitHub Pages deploy\n│\n├── justfile                         # Task runner\n├── .pre-commit-config.yaml          # ruff + ty hooks\n└── pyproject.toml\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite\njust test\n\n# Verbose output\njust test-verbose\n\n# Core tests only\njust test-core\n\n# Adapter tests only\njust test-adapters\n\n# Or pytest directly\npytest tests/ -q --tb=short\n```\n\nCI runs against Python 3.11, 3.12, 3.13, and 3.14 on every push and pull request.\n\n---\n\n## Development\n\n### Setup\n\n```bash\njust install                # Install all deps (just: https://github.com/casey/just)\n\n# Or manually\nuv pip install -e \".[dev]\"\n\njust pre-commit-install     # Install ruff + ty pre-commit hooks\n```\n\n### Common Commands\n\n```bash\njust format          # Format code with ruff\njust lint            # Lint with ruff\njust lint-fix        # Lint and auto-fix\njust check           # lint + format-check + tests\n\njust docs-build      # Build API docs -\u003e docs/site/\njust docs-serve      # Start pdoc dev server (localhost:8000)\njust docs-check      # Verify pdoc is installed and show config\njust docs-clean      # Remove docs/site/\n\njust clean           # Remove build artifacts\njust build           # Build the package\n```\n\n### Claude Code Development\n\n```bash\njust claude                          # Interactive Claude Code\njust claude-unsafe                   # Skip permission prompts (trusted env only)\njust claude-prompt                   # Append CLAUDE.md as system prompt\njust claude-unsafe-prompt            # System prompt + skip permissions\njust claude-orchestrate              # Full orchestration workflow\n\n# Override prompt file\njust claude-prompt PROMPT_FILE=prompts/WORKFLOW.md\n```\n\n| Prompt file | Purpose |\n|------------|---------|\n| `CLAUDE.md` | Project architecture, conventions, guidelines (default) |\n| `prompts/WORKFLOW.md` | Multi-agent orchestration, model selection, RTK token efficiency |\n\n### Code Quality\n\n- **[ruff](https://docs.astral.sh/ruff/)** — Linting and formatting (line length: 100)\n- **[ty](https://github.com/astral-sh/ty)** — Type checking (Astral's Rust-based)\n- **pre-commit** — Git hooks: trailing whitespace, YAML, merge conflicts, ruff, ty\n\n### Contributing\n\n1. Open an issue first to discuss major changes\n2. Follow existing code style (ruff)\n3. Add tests for new features\n4. Update docstrings (used for API docs)\n5. Keep PRs focused and small\n\n---\n\n## Roadmap\n\n### Alpha (Complete)\n- [x] Core component framework\n- [x] FastAPI adapter\n- [x] Django adapter\n- [x] Form validation\n- [x] Model binding\n- [x] WebSocket support\n- [x] Class-based views\n- [x] CI pipeline (GitHub Actions)\n- [x] Pre-commit hooks (ruff + ty)\n- [x] Comprehensive test suite\n\n### Beta (Complete)\n- [x] Permission classes and FBV decorators\n- [x] Rate limiting (`RateLimitMixin`)\n- [x] Component caching (`CacheMixin`)\n- [x] Optimistic UI (`OptimisticMixin`)\n- [x] Component composition (slots, composite)\n- [x] Testing utilities (`ComponentTestCase`)\n- [x] Versioned API documentation (GitHub Pages + pdoc)\n- [x] Optional extras — FastAPI/Uvicorn/JinjaX no longer mandatory (`[fastapi]`, `[django]`, `[all]`)\n\n### 0.4.0 (Complete)\n- [x] Litestar adapter — HTTP, WebSocket, SSE (`[litestar]` extra)\n- [x] Async event handlers — `async_dispatch()` / `async_handle_event()`\n- [x] SSE streaming — `StreamingComponent` with async generator handlers\n- [x] State size guard — configurable warning (64 KB) and hard limit (512 KB)\n- [x] JS double-serialisation fix in `component-client.js`\n\n### 0.5.0 (Complete)\n- [x] Flask adapter — `FlaskRenderer` + HTTP blueprint (`[flask]` extra)\n- [x] Optimistic UI patching in the client (`component-client.js` + `component-framework.css`)\n- [x] JinjaX catalog sharing guidance (reuse the host app's `Catalog`)\n\n### Path to 1.0 (Planned)\n\nThe road to a **production-grade** 1.0 is scoped into milestones, derived from a\n[market \u0026 gap analysis](claudedocs/research_liveview_market_2026-06-24.md) against\nPhoenix LiveView, Livewire, and Hotwire. Full work breakdown (epics, dependencies,\neffort) is in the [development plan](claudedocs/dev_plan_production_grade_2026-06-24.md)\nand tracked via [GitHub milestones](https://github.com/fsecada01/component-framework/milestones)\nand [epic issues](https://github.com/fsecada01/component-framework/issues?q=is%3Aissue+label%3Aepic).\n\n\u003e The two critical-path enablers are **signed state** (security gate — component state\n\u003e currently round-trips to the client unsigned) and **DOM morphing** (today the client\n\u003e does a full `innerHTML` replace, which unblocks navigation, forms fidelity, and\n\u003e optimistic UI once it lands).\n\n**0.6.0b — Hardening Foundation** *(Tier 0: security \u0026 rendering fidelity)*\n- [x] Signed / tamper-proof state (HMAC) — *security gate* — see [State Signing](docs/STATE_SIGNING.md)\n- [ ] DOM morphing — preserve focus / scroll / in-flight input; stable list keys\n- [ ] CSRF coverage for FastAPI / Litestar / Flask HTTP paths (today Django-only)\n- [ ] 422 re-render on form-validation failure (adapters currently return 200)\n- [ ] Cross-adapter request-parse hardening\n\n**0.7.0b — Real-App Features** *(Tier 1: table-stakes app capabilities)*\n- [ ] Live SPA navigation — history / back-button, loading indicator, scroll restore\n- [ ] File uploads — progress, multiple files, size/type constraints\n- [ ] On-blur / real-time partial validation\n- [ ] WebSocket reconnection + automatic state resync\n- [ ] Flask WebSocket / SSE parity\n- [ ] Unified Redis pub/sub fan-out across adapters\n\n**0.8.0b — Mindshare** *(Tier 2: observability \u0026 DX)*\n- [ ] Telemetry / observability — lifecycle spans + timing hooks\n- [ ] Published benchmarks (latency, payload, memory/connection, concurrency)\n- [ ] Declarative optimistic-JS command DSL; JS interop hooks with lifecycle\n- [ ] Latency simulation; offline detection + visibility-throttled polling\n\n**1.0.0 — Stable**\n- [ ] Frozen, documented public API\n- [ ] Full narrative user guide and tutorials\n- [ ] Deployment guide (ASGI workers, load balancer, sticky sessions, WS termination)\n- [ ] Devtools / inspector\n\n**Post-1.0 (deferred):** server-side change-tracked diffing, CRDT-style presence,\ndirect-to-cloud (S3) uploads, request batching, component marketplace.\n\n---\n\n## Performance\n\nCurrent benchmarks (local development):\n- Component dispatch: \u003c 1ms\n- State serialisation: \u003c 1ms\n- Full HTTP cycle: ~10–20ms\n- WebSocket latency: \u003c 10ms\n\n---\n\n## Requirements\n\n- Python 3.11+\n- Pydantic 2.0+ *(only mandatory runtime dependency)*\n\nOptional extras:\n- `[fastapi]` — FastAPI 0.109+, Uvicorn, JinjaX 0.41+\n- `[django]` — Django 4.2+, Django Channels 4.0+, channels-redis 4.1+, django-cotton 0.9+\n- `[litestar]` — Litestar 2.0+, Jinja2 3.1+\n- `[flask]` — Flask 3.0+\n- `[websockets]` — websockets 12.0+\n- `[all]` — all of the above\n\n---\n\n## Known Limitations\n\n- State must be JSON-serialisable\n- WebSocket scaling requires a Redis channel layer\n- CSRF handling for WebSockets is manual\n- SSE streaming requires ASGI deployment (Django) or any async framework (FastAPI/Litestar)\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE) for details.\n\n---\n\n## Acknowledgments\n\nInspired by:\n- [Phoenix LiveView](https://hexdocs.pm/phoenix_live_view/)\n- [Laravel Livewire](https://laravel-livewire.com/)\n- [Hotwire/Turbo](https://turbo.hotwired.dev/)\n- [HTMX](https://htmx.org/)\n\n---\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/fsecada01/component-framework/issues)\n- Discussions: [GitHub Discussions](https://github.com/fsecada01/component-framework/discussions)\n- Docs: [fsecada01.github.io/component-framework](https://fsecada01.github.io/component-framework/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsecada01%2Fcomponent-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffsecada01%2Fcomponent-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsecada01%2Fcomponent-framework/lists"}