patera-joltui 0.2.0__tar.gz

patera_joltui-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marko Šterk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

patera_joltui-0.2.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: patera-joltui
+Version: 0.2.0
+Summary: JolUI server component integration for Patera
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: patera>=0.122
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# patera-joltui
+
+Install `patera-joltui` (or `patera[joltui]`) and import from `patera.joltui`.
+
+```python
+from html import escape
+from patera import Request
+from patera.injectable import Inject
+from patera.joltui import (
+    ComponentGroup, JoltuiGroupHandler, PateraJoltui,
+    component, group, joltui_request,
+)
+
+@group("default")
+class DefaultGroupHandler(JoltuiGroupHandler):
+    @component("home-page")
+    async def home_page(self, req: Request):
+        return req.res.html_body("<h1>Welcome</h1>")
+
+@group("user-group")
+class UserGroupHandler(JoltuiGroupHandler):
+    @component("user-page")
+    async def user_page(self, req: Request):
+        data = joltui_request(req)
+        user_id = escape(str(data.route_parameters["user_id"]))
+        return req.res.html_body(f"<h1>User {user_id}</h1>")
+
+class JoltuiInterface(PateraJoltui):
+    default_group: ComponentGroup[DefaultGroupHandler]
+    user_group: ComponentGroup[UserGroupHandler]
+```
+
+Register `JoltuiInterface` in your application's `app_extensions`, or inject it
+with `joltui: Inject[JoltuiInterface]`. Set JolUI's `serverComponentsUrl` to
+`/joltui/components` (including Patera's `URL_PREFIX`, if configured).
+Override the endpoint with application configuration:
+`JOLTUI_INTERFACE = {"COMPONENTS_PATH": "/components"}`.
+The extension registers its own controller automatically; no application
+controller or manual dispatch route is needed. `JoltuiConfig.COMPONENTS_PATH`
+defaults to `/joltui/components`.
+
+JolUI sends a JSON POST containing `tagName`, `groupName`, `routeParameters`,
+`queryParameters`, and `attributes`. Omitted/null groups default to `default`;
+omitted/null parameter mappings default to empty dictionaries. Tags are
+trimmed and lowercased, while group names remain case-sensitive.
+
+Handlers receive the original Patera `Request`, retaining cookies, sessions,
+headers, request context, and response helpers. `joltui_request(req)` provides
+validated frontend metadata as `tag_name`, `group_name`, `route_parameters`,
+`query_parameters`, and `attributes`. HTTP URL parameters stay unchanged;
+frontend route parameters are accessed through this metadata. The original
+JSON is also available through `await req.json()`.
+
+Always return a Patera `Response` with content type `text/html` (for example,
+`req.res.html_body(markup)` or `await req.res.html("user.html", ...)`).
+Plain strings and non-HTML responses are rejected. Sync handlers are supported too.
+Malformed requests return 400; unknown groups/components return 404. Handler
+exceptions follow Patera's normal exception pipeline, including 401/403.
+
+Groups are app-scoped and support `Inject[T]` dependencies. Do not store
+per-request data on group instances. Inherited component methods are exposed;
+overriding a method without `@component` removes its registration. Duplicate
+group names or component tags fail at initialization. Only decorated methods
+in explicitly declared groups are callable. Interface annotations may be
+inherited, overridden, or removed with a non-ComponentGroup annotation.
+
+Group handlers are Patera controllers. Use the normal controller and endpoint
+decorators, including group/endpoint `@login_required()` and `@role_required()`,
+`@after_init`, `@before_request`, `@after_request`, `@consumes`, `@produces`,
+`@cors`, `@no_cors`, `@max_content_length`, `@ignore`, and `@development`.
+Authentication decorators require the application's usual authentication
+middleware. For example:
+
+```python
+from patera.auth import login_required, role_required
+from patera.controller import after_request, produces
+from patera import MediaType
+
+@group("user-group")
+@login_required()
+class UserGroupHandler(JoltuiGroupHandler):
+    @after_request
+    def prevent_caching(self, res):
+        res.set_header("Cache-Control", "no-store")
+
+    @component("user-page")
+    @role_required("admin")
+    @produces(MediaType.TEXT_HTML)
+    async def user_page(self, req: Request):
+        return req.res.html_body("<h1>Users</h1>")
+```
+
+Component selection runs before CORS, database, authentication, and application
+middleware. They see the selected bound component as `req.route_handler` and
+its group as `current_request.controller`. Normal controller hooks run once;
+after-request hooks receive the handler's HTML `Response`.
+Decorators such as `@produces` that operate on a response expect handlers to
+return a `Response`, just as on ordinary endpoints. `@consumes` validates the
+original JSON envelope, not just its `attributes` field.
+
+All components share one HTTP POST URL: `@path`/HTTP method decorators do not
+create additional component URLs, and WebSocket transport is not provided by
+this endpoint. OpenAPI metadata can be attached, but individual RPC components
+are not separate OpenAPI routes. OPTIONS preflights have no component body,
+so they use the shared endpoint's global CORS policy; configure it to permit
+the frontend. Component CORS overrides apply to actual POST responses.
+
+The application's body limit protects JSON envelope parsing. Component
+`@max_content_length` limits are additionally enforced after selection and
+cannot bypass that initial envelope limit. Frontend metadata is client input,
+not an authorization source. Escape values inserted into raw HTML, or use
+your application's templates.
+
+
+Handlers may declare an optional third argument annotated with any Pydantic
+model. The extension validates the full JSON body into that model automatically;
+`@consumes` is not required. Model validation failures return 422 before the
+handler runs. Authentication and controller before-request hooks run first.
+
+```python
+from pydantic import BaseModel, Field
+from patera import Response
+
+class UserRoute(BaseModel):
+    user_id: int
+
+class UserPageBody(BaseModel):
+    route_parameters: UserRoute = Field(alias="routeParameters")
+    # tagName and groupName need not be declared in a custom model.
+    # Pydantic's default extra="ignore" ignores undeclared envelope fields.
+
+@group("user-group")
+class UserGroupHandler(JoltuiGroupHandler):
+    @component("user-page")
+    async def user_page(self, req: Request, body: UserPageBody) -> Response:
+        return req.res.html_body(f"<h1>User {body.route_parameters.user_id}</h1>")
+```
+
+For example, the request body is:
+
+```json
+{"tagName": "user-page", "groupName": "user-group", "routeParameters": {"user_id": "42"}}
+```
+
+`body.route_parameters.user_id` is validated and converted to the integer 42.
+The original `Request` and its JSON body remain available. Use `JoltuiRequest`
+as the third argument if its standard fields suffice, or define your own model
+with nested models and aliases as above. `JoltuiRequest.tag_name` defaults to
+`None` and `group_name` to `"default"`, so neither field is required when
+constructing the model. The actual RPC envelope still requires `tagName` to
+select the handler; `groupName` may be omitted to select the default group.
+Custom models receive the original body and follow their own Pydantic defaults,
+coercion, extra-field policy, and validators.

patera_joltui-0.2.0/README.md

@@ -0,0 +1,153 @@
+# patera-joltui
+
+Install `patera-joltui` (or `patera[joltui]`) and import from `patera.joltui`.
+
+```python
+from html import escape
+from patera import Request
+from patera.injectable import Inject
+from patera.joltui import (
+    ComponentGroup, JoltuiGroupHandler, PateraJoltui,
+    component, group, joltui_request,
+)
+
+@group("default")
+class DefaultGroupHandler(JoltuiGroupHandler):
+    @component("home-page")
+    async def home_page(self, req: Request):
+        return req.res.html_body("<h1>Welcome</h1>")
+
+@group("user-group")
+class UserGroupHandler(JoltuiGroupHandler):
+    @component("user-page")
+    async def user_page(self, req: Request):
+        data = joltui_request(req)
+        user_id = escape(str(data.route_parameters["user_id"]))
+        return req.res.html_body(f"<h1>User {user_id}</h1>")
+
+class JoltuiInterface(PateraJoltui):
+    default_group: ComponentGroup[DefaultGroupHandler]
+    user_group: ComponentGroup[UserGroupHandler]
+```
+
+Register `JoltuiInterface` in your application's `app_extensions`, or inject it
+with `joltui: Inject[JoltuiInterface]`. Set JolUI's `serverComponentsUrl` to
+`/joltui/components` (including Patera's `URL_PREFIX`, if configured).
+Override the endpoint with application configuration:
+`JOLTUI_INTERFACE = {"COMPONENTS_PATH": "/components"}`.
+The extension registers its own controller automatically; no application
+controller or manual dispatch route is needed. `JoltuiConfig.COMPONENTS_PATH`
+defaults to `/joltui/components`.
+
+JolUI sends a JSON POST containing `tagName`, `groupName`, `routeParameters`,
+`queryParameters`, and `attributes`. Omitted/null groups default to `default`;
+omitted/null parameter mappings default to empty dictionaries. Tags are
+trimmed and lowercased, while group names remain case-sensitive.
+
+Handlers receive the original Patera `Request`, retaining cookies, sessions,
+headers, request context, and response helpers. `joltui_request(req)` provides
+validated frontend metadata as `tag_name`, `group_name`, `route_parameters`,
+`query_parameters`, and `attributes`. HTTP URL parameters stay unchanged;
+frontend route parameters are accessed through this metadata. The original
+JSON is also available through `await req.json()`.
+
+Always return a Patera `Response` with content type `text/html` (for example,
+`req.res.html_body(markup)` or `await req.res.html("user.html", ...)`).
+Plain strings and non-HTML responses are rejected. Sync handlers are supported too.
+Malformed requests return 400; unknown groups/components return 404. Handler
+exceptions follow Patera's normal exception pipeline, including 401/403.
+
+Groups are app-scoped and support `Inject[T]` dependencies. Do not store
+per-request data on group instances. Inherited component methods are exposed;
+overriding a method without `@component` removes its registration. Duplicate
+group names or component tags fail at initialization. Only decorated methods
+in explicitly declared groups are callable. Interface annotations may be
+inherited, overridden, or removed with a non-ComponentGroup annotation.
+
+Group handlers are Patera controllers. Use the normal controller and endpoint
+decorators, including group/endpoint `@login_required()` and `@role_required()`,
+`@after_init`, `@before_request`, `@after_request`, `@consumes`, `@produces`,
+`@cors`, `@no_cors`, `@max_content_length`, `@ignore`, and `@development`.
+Authentication decorators require the application's usual authentication
+middleware. For example:
+
+```python
+from patera.auth import login_required, role_required
+from patera.controller import after_request, produces
+from patera import MediaType
+
+@group("user-group")
+@login_required()
+class UserGroupHandler(JoltuiGroupHandler):
+    @after_request
+    def prevent_caching(self, res):
+        res.set_header("Cache-Control", "no-store")
+
+    @component("user-page")
+    @role_required("admin")
+    @produces(MediaType.TEXT_HTML)
+    async def user_page(self, req: Request):
+        return req.res.html_body("<h1>Users</h1>")
+```
+
+Component selection runs before CORS, database, authentication, and application
+middleware. They see the selected bound component as `req.route_handler` and
+its group as `current_request.controller`. Normal controller hooks run once;
+after-request hooks receive the handler's HTML `Response`.
+Decorators such as `@produces` that operate on a response expect handlers to
+return a `Response`, just as on ordinary endpoints. `@consumes` validates the
+original JSON envelope, not just its `attributes` field.
+
+All components share one HTTP POST URL: `@path`/HTTP method decorators do not
+create additional component URLs, and WebSocket transport is not provided by
+this endpoint. OpenAPI metadata can be attached, but individual RPC components
+are not separate OpenAPI routes. OPTIONS preflights have no component body,
+so they use the shared endpoint's global CORS policy; configure it to permit
+the frontend. Component CORS overrides apply to actual POST responses.
+
+The application's body limit protects JSON envelope parsing. Component
+`@max_content_length` limits are additionally enforced after selection and
+cannot bypass that initial envelope limit. Frontend metadata is client input,
+not an authorization source. Escape values inserted into raw HTML, or use
+your application's templates.
+
+
+Handlers may declare an optional third argument annotated with any Pydantic
+model. The extension validates the full JSON body into that model automatically;
+`@consumes` is not required. Model validation failures return 422 before the
+handler runs. Authentication and controller before-request hooks run first.
+
+```python
+from pydantic import BaseModel, Field
+from patera import Response
+
+class UserRoute(BaseModel):
+    user_id: int
+
+class UserPageBody(BaseModel):
+    route_parameters: UserRoute = Field(alias="routeParameters")
+    # tagName and groupName need not be declared in a custom model.
+    # Pydantic's default extra="ignore" ignores undeclared envelope fields.
+
+@group("user-group")
+class UserGroupHandler(JoltuiGroupHandler):
+    @component("user-page")
+    async def user_page(self, req: Request, body: UserPageBody) -> Response:
+        return req.res.html_body(f"<h1>User {body.route_parameters.user_id}</h1>")
+```
+
+For example, the request body is:
+
+```json
+{"tagName": "user-page", "groupName": "user-group", "routeParameters": {"user_id": "42"}}
+```
+
+`body.route_parameters.user_id` is validated and converted to the integer 42.
+The original `Request` and its JSON body remain available. Use `JoltuiRequest`
+as the third argument if its standard fields suffice, or define your own model
+with nested models and aliases as above. `JoltuiRequest.tag_name` defaults to
+`None` and `group_name` to `"default"`, so neither field is required when
+constructing the model. The actual RPC envelope still requires `tagName` to
+select the handler; `groupName` may be omitted to select the default group.
+Custom models receive the original body and follow their own Pydantic defaults,
+coercion, extra-field policy, and validators.

patera_joltui-0.2.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "patera-joltui"
+version = "0.2.0"
+description = "JolUI server component integration for Patera"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.13"
+dependencies = ["patera>=0.122"]
+
+[tool.uv.sources]
+patera = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "patera.joltui"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.13.0"]
+build-backend = "uv_build"

patera_joltui-0.2.0/src/patera/joltui/__init__.py

@@ -0,0 +1,23 @@
+"""JolUI server components for Patera."""
+
+from .interface import (
+    ComponentGroup,
+    JoltuiConfig,
+    JoltuiGroupHandler,
+    JoltuiRequest,
+    PateraJoltui,
+    component,
+    group,
+    joltui_request,
+)
+
+__all__ = [
+    "ComponentGroup",
+    "JoltuiConfig",
+    "JoltuiGroupHandler",
+    "JoltuiRequest",
+    "PateraJoltui",
+    "component",
+    "group",
+    "joltui_request",
+]

patera_joltui-0.2.0/src/patera/joltui/interface.py

@@ -0,0 +1,295 @@
+"""Dispatch JolUI's fetchHTML protocol through ordinary Patera requests."""
+
+from __future__ import annotations
+
+import re
+import inspect
+from functools import wraps
+from types import MethodType
+from typing import (
+    Annotated,
+    Any,
+    Callable,
+    TypeAlias,
+    TypeVar,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from patera import BaseExtension, MediaType, Request, Response, run_sync_or_async
+from patera.controller.utilities import _build_model, _unwrap_annotated
+from patera.controller import Controller, path, post
+from patera.exceptions.http_exceptions import (
+    BaseHttpException,
+    InvalidRequestBody,
+    RequestBodyTooLarge,
+)
+from patera.ctx import get_request_context
+from patera.middleware import MiddlewareBase
+from patera.injectable import _own_annotations, _resolve_annotation
+
+T = TypeVar("T", bound="JoltuiGroupHandler")
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class _ComponentGroup:
+    pass
+
+
+ComponentGroup: TypeAlias = Annotated[T, _ComponentGroup()]
+
+
+def _name(value: str, *, tag: bool = False) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("Component and group names must be non-empty strings")
+    return value.strip().lower() if tag else value.strip()
+
+
+def group(name: str) -> Callable[[type[T]], type[T]]:
+    """Name a group; only groups declared on an interface are exposed."""
+    name = _name(name)
+
+    def decorate(cls: type[T]) -> type[T]:
+        if not issubclass(cls, JoltuiGroupHandler):
+            raise TypeError("@group requires a JoltuiGroupHandler subclass")
+        cls.__joltui_group__ = name
+        return cls
+
+    return decorate
+
+
+def component(tag: str) -> Callable[[F], F]:
+    """Expose a handler under a case-insensitive component tag."""
+    tag = _name(tag, tag=True)
+
+    def decorate(func: F) -> F:
+        setattr(func, "__joltui_component__", tag)
+        return func
+
+    return decorate
+
+
+class JoltuiGroupHandler(Controller):
+    """App-scoped controller with normal injection and lifecycle decorators."""
+
+    __joltui_group__: str
+
+    async def __call__(self, method: Callable, req: Request) -> Response:
+        @wraps(method)
+        async def render(request: Request, **kwargs: Any) -> Response:
+            body_parameter = _body_parameter(method)
+            if body_parameter is not None:
+                name, model = body_parameter
+                kwargs[name] = _build_model(model, await request.json())
+            result = await run_sync_or_async(method, request, **kwargs)
+            _require_html_response(result)
+            return result
+
+        result = await super().__call__(render, req)
+        _require_html_response(result)
+        return result
+
+
+def _require_html_response(result: Any) -> None:
+    if not isinstance(result, Response):
+        raise TypeError("JolUI component handlers must return an HTML Response")
+    content_type = result.content_type or result.media_type or ""
+    if content_type.split(";", 1)[0].strip().lower() != MediaType.TEXT_HTML.value:
+        raise TypeError("JolUI component responses must use text/html")
+
+
+def _body_parameter(method: Callable) -> tuple[str, type[BaseModel]] | None:
+    # Bound method parameters are (req, body); wraps preserves the original
+    # signature and annotations through ordinary endpoint decorators.
+    parameters = list(inspect.signature(method).parameters.values())
+    if len(parameters) == 1:
+        return None
+    if len(parameters) != 2 or parameters[1].kind not in (
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+        inspect.Parameter.KEYWORD_ONLY,
+    ):
+        raise TypeError("Component handlers require (self, req[, body: BaseModel])")
+    parameter = parameters[1]
+    model = _unwrap_annotated(
+        get_type_hints(method, include_extras=True).get(parameter.name)
+    )
+    if not isinstance(model, type) or not issubclass(model, BaseModel):
+        raise TypeError("The third component handler argument must be a Pydantic model")
+    return parameter.name, model
+
+
+class _JoltuiDispatchMiddleware(MiddlewareBase):
+    # Resolve before CORS (-101), database sessions (-100), and auth (-99).
+    _order_ = -102
+    _middleware = True
+
+    async def middleware(self, req: Request) -> Response:
+        extension = getattr(req.route_handler, "__joltui_interface__", None)
+        if extension is not None and req.method == "POST":
+            await extension.resolve(req)
+        return await self.next(req)
+
+
+class JoltuiConfig(BaseModel):
+    COMPONENTS_PATH: str = "/joltui/components"
+
+    @field_validator("COMPONENTS_PATH")
+    @classmethod
+    def validate_path(cls, value: str) -> str:
+        if not value.startswith("/") or any(c in value for c in "?#{<"):
+            raise ValueError("COMPONENTS_PATH must be an absolute, literal URL path")
+        return value
+
+
+class JoltuiRequest(BaseModel):
+    """Frontend metadata, separate from the HTTP request's URL parameters."""
+
+    model_config = ConfigDict(strict=True, populate_by_name=True)
+    tag_name: str | None = Field(default=None, alias="tagName", min_length=1)
+    group_name: str = Field(default="default", alias="groupName")
+    route_parameters: dict[str, str | int | float] = Field(
+        default_factory=dict, alias="routeParameters"
+    )
+    query_parameters: dict[str, str] = Field(
+        default_factory=dict, alias="queryParameters"
+    )
+    attributes: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("tag_name")
+    @classmethod
+    def normalize_tag(cls, value: str | None) -> str | None:
+        return _name(value, tag=True) if value is not None else None
+
+    @field_validator("group_name", mode="before")
+    @classmethod
+    def normalize_group(cls, value: Any) -> Any:
+        return (
+            (value.strip() or "default")
+            if isinstance(value, str)
+            else ("default" if value is None else value)
+        )
+
+    @field_validator(
+        "route_parameters", "query_parameters", "attributes", mode="before"
+    )
+    @classmethod
+    def normalize_mapping(cls, value: Any) -> Any:
+        return {} if value is None else value
+
+
+def joltui_request(req: Request) -> JoltuiRequest:
+    """Return metadata during a component dispatch, without replacing Request."""
+    value = req.scope.get("patera.joltui")
+    if not isinstance(value, JoltuiRequest):
+        raise RuntimeError("This request is not a JolUI component request")
+    return value
+
+
+class PateraJoltui(BaseExtension[Any, JoltuiConfig]):
+    """Mount a POST endpoint for declaratively registered component groups."""
+
+    def init(self) -> None:
+        declarations: dict[str, type[JoltuiGroupHandler]] = {}
+        for cls in reversed(type(self).__mro__):
+            for name, raw in _own_annotations(cls).items():
+                declarations.pop(name, None)
+                if isinstance(raw, str):
+                    if not re.search(r"\b(?:ComponentGroup|Annotated)\s*\[", raw):
+                        continue
+                    raw = _resolve_annotation(cls, name, raw)
+                if get_origin(raw) is not Annotated:
+                    continue
+                target, *metadata = get_args(raw)
+                if not any(isinstance(m, _ComponentGroup) for m in metadata):
+                    continue
+                if not isinstance(target, type) or not issubclass(
+                    target, JoltuiGroupHandler
+                ):
+                    raise TypeError(
+                        f"{name}: ComponentGroup requires a JoltuiGroupHandler"
+                    )
+                declarations[name] = target
+
+        self._handlers: dict[tuple[str, str], MethodType] = {}
+        groups: set[str] = set()
+        for name, target in declarations.items():
+            group_name = getattr(target, "__joltui_group__", None)
+            if group_name is None:
+                raise TypeError(f"{target.__name__} needs a @group decorator")
+            if group_name in groups:
+                raise ValueError(f"Duplicate JolUI group: {group_name}")
+            groups.add(group_name)
+            if self._excluded(target):
+                continue
+            handler = self._resolve_dependency(target)
+            setattr(self, name, handler)
+            members: dict[str, Any] = {}
+            for base in reversed(target.__mro__):
+                members.update(vars(base))
+            for method_name, method in members.items():
+                tag = getattr(method, "__joltui_component__", None)
+                if tag is None:
+                    continue
+                if self._excluded(method):
+                    continue
+                key = (group_name, tag)
+                if key in self._handlers:
+                    raise ValueError(f"Duplicate JolUI component: {group_name}/{tag}")
+                self._handlers[key] = getattr(handler, method_name)
+                _body_parameter(self._handlers[key])
+
+        extension = self
+
+        @path(self.configs.COMPONENTS_PATH, open_api_spec=False)
+        class JoltuiComponents(Controller):
+            @post("")
+            async def render_component(self, req: Request) -> Response:
+                return await extension.dispatch(req)
+
+        JoltuiComponents.__name__ = f"{type(self).__name__}Components"
+        setattr(JoltuiComponents.render_component, "__joltui_interface__", self)
+        self.app.register_controller(JoltuiComponents)
+        if _JoltuiDispatchMiddleware not in self.app._middleware_classes.values():
+            self.app.register_middleware(_JoltuiDispatchMiddleware)
+
+    def _excluded(self, target: Any) -> bool:
+        return bool(
+            getattr(target, "_ignore", False)
+            or (
+                getattr(target, "_development", False)
+                and not self.app.get_conf("DEBUG", False)
+            )
+        )
+
+    async def resolve(self, req: Request) -> None:
+        """Select the effective endpoint before ordinary middleware inspects it."""
+        try:
+            payload = JoltuiRequest.model_validate(await req.json())
+        except ValidationError as exc:
+            raise InvalidRequestBody("Invalid JolUI component request") from exc
+        if payload.tag_name is None:
+            raise InvalidRequestBody("tagName is required for component dispatch")
+        handler = self._handlers.get((payload.group_name, payload.tag_name))
+        if handler is None:
+            raise BaseHttpException("Unknown JolUI component", status_code=404)
+        req.scope["patera.joltui"] = payload
+        req._route_handler = handler
+        get_request_context().controller = handler.__self__
+        # The shared endpoint's body limit protects envelope parsing. A smaller
+        # component limit is checked once the envelope identifies the handler.
+        limit = getattr(handler, "_max_content_length", req.max_content_length)
+        req.max_content_length = limit
+        if limit is not None and len(await req.body()) > limit:
+            raise RequestBodyTooLarge(limit)
+
+    async def dispatch(self, req: Request) -> Response:
+        """Fallback for direct invocation of the registered controller."""
+        await self.resolve(req)
+        handler = req.route_handler
+        assert isinstance(handler, MethodType)
+        controller = handler.__self__
+        assert isinstance(controller, JoltuiGroupHandler)
+        return await controller(handler, req)