As HTMX becomes the industry standard for building modern, reactive Single Page Applications (SPAs) without heavy JavaScript frameworks, Jooby developers need a first-class way to handle HTMX's unique response lifecycle. Currently, managing HX-Request headers, Out-Of-Band (OOB) swaps, Javascript triggers, and partial vs. full-page layout rendering requires significant boilerplate and repetitive try/catch logic in every controller.

Introduce `jooby-htmx`, a dedicated module providing both a **Declarative Annotation API** (via APT generation) and a memory-safe **Imperative Builder API** to orchestrate HTMX responses seamlessly. This allows developers to write 100% pure "Happy Path" business logic while the framework handles the UI state.

**1. The Interceptor Pipeline (`HtmxModule` & `HtmxMessageEncoder`)**
* Registers directly into Jooby's `MessageEncoder` chain ahead of standard template engines.
* Intercepts `HtmxModelAndView` payloads and safely drives the underlying template engine (e.g., Handlebars) in a loop to concatenate the primary view and multiple OOB templates into a single HTTP response.

**2. The Imperative API (`HtmxResponse`)**
* A fluent builder for scenarios lacking a primary view (e.g., `HTTP 204 No Content` for drag-and-drop reordering or delete operations).
* Easily chains multiple `.addOob()` and `.trigger()` events.

**3. The Declarative API (APT Code Generation)**
* `@HxView(value = "partial.hbs", layout = "base.hbs")`: Automatically serves the partial for HTMX AJAX requests, but smartly wraps it in the layout for direct browser navigation or `F5` refreshes.
* `@HxOob("counter.hbs")` & `@HxTrigger("itemAdded")`: Automatically injects the necessary headers and models into the response.
* `@HxError("error.hbs")`: The "UI Janitor". Automatically catches Bean Validation (`@Valid`) `ConstraintViolationException`s to render scoped inline errors (HTTP 422). Crucially, it **automatically appends an empty OOB swap on success** to instantly clear the UI of previous errors.

**4. Global Error Resilience**
* Allows passing an `HtmxErrorHandler` directly into `install(new HtmxModule(errorHandler))`.
* Safely intercepts global `500` server crashes and translates them into OOB Toast notifications, preventing raw HTML stack traces from breaking the client's DOM.

The resulting controller is entirely decoupled from HTTP headers and serialization logic:

```java
@post("/tasks")
@HxView("task_row.hbs")
@HxOob("task_counter.hbs")
@HxOob("toast.hbs")
@HxTrigger("taskAdded")
@Hxerror("task_error.hbs") // Automatically renders errors on failure, and clears them on success!
public Map<String, Object> addTask(@FormParam @Valid TaskDto dto) {
    var newTask = db.save(dto);

    return Map.of(
        "id", newTask.id(),
        "title", newTask.title(),
        "activeCount", db.getActiveCount(),
        "message", "Task added successfully!"
    );
}

fix #3936

Author: jknack

jooby/src/main/java/io/jooby/Jooby.java

@@ -776,6 +776,11 @@ public ServiceRegistry getServices() {
     return this.router.getServices();
   }
 
+  @Override
+  public List<TemplateEngine> getTemplateEngines() {
+    return this.router.getTemplateEngines();
+  }
+
   /**
    * Get base application package. This is the package from where application was initialized or the
    * package of a Jooby application sub-class.

jooby/src/main/java/io/jooby/ModelAndView.java

@@ -88,12 +88,13 @@ public static MapModelAndView map(String view, Map<String, Object> model) {
    *     any other object.
    * @return A {@code ModelAndView} instance corresponding to the specified view and model.
    */
-  public static ModelAndView<Map<String, Object>> of(String view, Object model) {
+  @SuppressWarnings({"unchecked", "rawtypes"})
+  public static <T> ModelAndView<T> of(String view, @Nullable Object model) {
     if (model == null) {
-      return map(view);
+      return (ModelAndView<T>) map(view);
     }
     if (model instanceof Map mapModel) {
-      return map(view, mapModel);
+      return (ModelAndView<T>) map(view, mapModel);
     }
     return new ModelAndView(view, model);
   }

jooby/src/main/java/io/jooby/Router.java

@@ -879,6 +879,13 @@ default Executor executor(String name) {
    */
   ValueFactory getValueFactory();
 
+  /**
+   * Retrieves a list of available template engines.
+   *
+   * @return a list of TemplateEngine objects representing the available template engines.
+   */
+  List<TemplateEngine> getTemplateEngines();
+
   /**
    * Set value factory, useful for custom value factory.
    *

jooby/src/main/java/io/jooby/internal/HttpMessageEncoder.java

@@ -106,4 +106,8 @@ public Output encode(Context ctx, Object value) throws Exception {
       return MessageEncoder.TO_STRING.encode(ctx, value);
     }
   }
+
+  public List<TemplateEngine> getTemplateEngines() {
+    return templateEngineList;
+  }
 }

jooby/src/main/java/io/jooby/internal/RouterImpl.java

@@ -816,6 +816,10 @@ public Router setCurrentUser(Function<Context, Object> provider) {
     return this;
   }
 
+  public List<TemplateEngine> getTemplateEngines() {
+    return Collections.unmodifiableList(encoder.getTemplateEngines());
+  }
+
   @Override
   public String toString() {
     StringBuilder buff = new StringBuilder();

jooby/src/main/java/io/jooby/internal/ValidationExceptionChain.java

@@ -78,7 +78,7 @@ public ValidationExceptionChain add(ValidationExceptionMapper mapper) {
     // Assume is a client error, provide a default result
     return new ValidationResult(
         "Validation failed",
-        suggestedCode.value(),
+        StatusCode.UNPROCESSABLE_ENTITY.value(),
         List.of(
             new ValidationResult.Error(
                 null,

jooby/src/test/java/io/jooby/internal/ValidationExceptionChainTest.java

@@ -63,7 +63,7 @@ void shouldReturnDefaultResultWhenNoMapperHandlesItAndStatusCodeIsClientError()
 
     assertNotNull(result);
     assertEquals("Validation failed", result.getTitle());
-    assertEquals(400, result.getStatus());
+    assertEquals(422, result.getStatus());
 
     assertEquals(1, result.getErrors().size());
     ValidationResult.Error error = result.getErrors().get(0);
@@ -82,7 +82,7 @@ void shouldReturnDefaultResultUsingClassNameWhenExceptionHasNoMessage() {
 
     assertNotNull(result);
     assertEquals("Validation failed", result.getTitle());
-    assertEquals(400, result.getStatus());
+    assertEquals(422, result.getStatus());
 
     assertEquals(1, result.getErrors().size());
     ValidationResult.Error error = result.getErrors().get(0);

modules/jooby-apt/pom.xml

@@ -45,6 +45,13 @@
       <scope>test</scope>
     </dependency>
 
+    <dependency>
+      <groupId>io.jooby</groupId>
+      <artifactId>jooby-htmx</artifactId>
+      <version>${jooby.version}</version>
+      <scope>test</scope>
+    </dependency>
+
     <dependency>
       <groupId>io.jooby</groupId>
       <artifactId>jooby-jsonrpc</artifactId>

modules/jooby-apt/src/main/java/io/jooby/apt/JoobyProcessor.java

@@ -130,17 +130,20 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
         context.getRouters().forEach(it -> context.debug("  %s", it.getGeneratedType()));
         return false;
       } else {
-        // Discover all unique Controller classes
         var controllers = findControllers(annotations, roundEnv);
-
-        // Factory Pattern: Build specific routers for each class based on method annotations
         List<WebRouter<?>> activeRouters = new ArrayList<>();
+
         for (var controller : controllers) {
           if (controller.getModifiers().contains(Modifier.ABSTRACT)) continue;
 
-          var restRouter = RestRouter.parse(context, controller);
-          if (!restRouter.isEmpty()) {
-            activeRouters.add(restRouter);
+          // --- PASS 1: Specialized Routers & Claim Gathering ---
+          Set<String> masterClaimedRoutes = new HashSet<>();
+
+          // Parse HTMX first to claim route paths
+          var htmxRouter = io.jooby.internal.apt.htmx.HtmxRouter.parse(context, controller);
+          if (!htmxRouter.isEmpty()) {
+            activeRouters.add(htmxRouter);
+            masterClaimedRoutes.addAll(htmxRouter.getClaimedRoutes());
           }
 
           var jsonRpcRouter = JsonRpcRouter.parse(context, controller);
@@ -162,6 +165,13 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
           if (!wsRouter.isEmpty()) {
             activeRouters.add(wsRouter);
           }
+
+          // --- PASS 2: Standard Rest Router (Fallback) ---
+          // Pass the claimed routes to RestRouter so it knows what to skip
+          var restRouter = RestRouter.parse(context, controller, masterClaimedRoutes);
+          if (!restRouter.isEmpty()) {
+            activeRouters.add(restRouter);
+          }
         }
 
         verifyBeanValidationDependency(activeRouters);
@@ -288,6 +298,20 @@ public Set<String> getSupportedAnnotationTypes() {
     supportedTypes.add("io.jooby.annotation.ws.OnClose");
     supportedTypes.add("io.jooby.annotation.ws.OnMessage");
     supportedTypes.add("io.jooby.annotation.ws.OnError");
+    // Add Htmx Annotations
+    supportedTypes.addAll(
+        Set.of(
+            "io.jooby.annotation.htmx.HxView",
+            "io.jooby.annotation.htmx.HxError",
+            "io.jooby.annotation.htmx.HxOob",
+            "io.jooby.annotation.htmx.HxOobs",
+            "io.jooby.annotation.htmx.HxPushUrl",
+            "io.jooby.annotation.htmx.HxRedirect",
+            "io.jooby.annotation.htmx.HxRefresh",
+            "io.jooby.annotation.htmx.HxSwap",
+            "io.jooby.annotation.htmx.HxTarget",
+            "io.jooby.annotation.htmx.HxTrigger",
+            "io.jooby.annotation.htmx.HxTriggers"));
     return supportedTypes;
   }
 

modules/jooby-apt/src/main/java/io/jooby/internal/apt/RestRouter.java

@@ -8,6 +8,7 @@
 import static io.jooby.internal.apt.CodeBlock.*;
 
 import java.io.IOException;
+import java.util.Set;
 import java.util.stream.Collectors;
 
 import javax.lang.model.element.ElementKind;
@@ -19,7 +20,8 @@ public RestRouter(MvcContext context, TypeElement clazz) {
     super(context, clazz);
   }
 
-  public static RestRouter parse(MvcContext context, TypeElement controller) {
+  public static RestRouter parse(
+      MvcContext context, TypeElement controller, Set<String> claimedRoutes) {
     var router = new RestRouter(context, controller);
 
     for (var type : context.superTypes(controller)) {
@@ -36,6 +38,21 @@ public static RestRouter parse(MvcContext context, TypeElement controller) {
             var annoElement = (TypeElement) annoMirror.getAnnotationType().asElement();
 
             if (HttpMethod.hasAnnotation(annoElement)) {
+              // Check if the current route is claimed by a specialized router (e.g., HTMX)
+              var httpMethod =
+                  HttpMethod.findByAnnotationName(annoElement.getQualifiedName().toString());
+              var paths = context.path(controller, method, annoElement);
+
+              boolean isClaimed =
+                  paths.stream()
+                      .map(path -> httpMethod + WebRoute.leadingSlash(path))
+                      .anyMatch(claimedRoutes::contains);
+
+              // If HTMX claimed it, skip generating a REST route for it!
+              if (isClaimed) {
+                continue;
+              }
+
               var route = new RestRoute(router, method, annoElement);
               var uniqueKey = method.toString() + annoElement.getSimpleName();
               router.routes.putIfAbsent(uniqueKey, route);