Route matching before file resolution, add TemplateRouteTest

Rewrite handleTemplate() to check templateRoute patterns BEFORE trying
to resolve the template file. This avoids exception-based flow control
and makes routes a clean "mounting registration" that takes priority.

Resolution order: templateRoute match → file resolution → fallbackTemplate → 404

TemplateRouteTest: 7 tests with demo/detail.html template that uses
request.pathMatches() to extract path params and render them.
Tests: param extraction, multi-value, edit/view mode via route
specificity, existing file not overridden, fallback chain.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ptrthomas

karate-core/src/main/java/io/karatelabs/http/ServerRequestCycle.java

@@ -187,10 +187,15 @@ private HttpResponse handleTemplate() {
             return forbidden("Invalid path");
         }
 
-        // Convert path to template: /signin -> signin.html, / -> index.html
-        String templatePath = path.equals("/") ? "index.html" : path.substring(1);
-        if (!templatePath.endsWith(".html")) {
-            templatePath = templatePath + ".html";
+        // 1. Check registered template routes first (e.g., /sessions/{id} → session.html)
+        String templatePath = resolveTemplateRoute(path);
+
+        // 2. If no route matched, convert path to template file: /signin → signin.html
+        if (templatePath == null) {
+            templatePath = path.equals("/") ? "index.html" : path.substring(1);
+            if (!templatePath.endsWith(".html")) {
+                templatePath = templatePath + ".html";
+            }
         }
 
         try {
@@ -214,35 +219,35 @@ private HttpResponse handleTemplate() {
             return response;
 
         } catch (ResourceNotFoundException e) {
-            // Try template routes first (pattern → template mapping)
-            String resolvedTemplate = resolveTemplateRoute(path);
-            if (resolvedTemplate == null) {
-                // Then try global fallback
-                resolvedTemplate = config.getFallbackTemplate();
-            }
-            if (resolvedTemplate != null) {
-                try {
-                    context.setTemplateName(resolvedTemplate);
-                    Map<String, Object> vars = context.toVars();
-                    String html = markup.processPath(resolvedTemplate, vars);
-                    if (context.isSwitched()) {
-                        String newTemplate = context.getSwitchTemplate();
-                        context.setTemplateName(newTemplate);
-                        html = markup.processPath(newTemplate, vars);
-                    }
-                    response.setBody(html);
-                    response.setHeader("Content-Type", "text/html; charset=utf-8");
-                    return response;
-                } catch (Exception fallbackError) {
-                    return notFound(path);
-                }
+            // Template file not found — try global fallback
+            String fallback = config.getFallbackTemplate();
+            if (fallback != null) {
+                return renderFallback(fallback, path);
             }
             return notFound(path);
         } catch (Exception e) {
             return handleError(e);
         }
     }
 
+    private HttpResponse renderFallback(String templatePath, String originalPath) {
+        try {
+            context.setTemplateName(templatePath);
+            Map<String, Object> vars = context.toVars();
+            String html = markup.processPath(templatePath, vars);
+            if (context.isSwitched()) {
+                String newTemplate = context.getSwitchTemplate();
+                context.setTemplateName(newTemplate);
+                html = markup.processPath(newTemplate, vars);
+            }
+            response.setBody(html);
+            response.setHeader("Content-Type", "text/html; charset=utf-8");
+            return response;
+        } catch (Exception e) {
+            return notFound(originalPath);
+        }
+    }
+
     private HttpResponse handleError(Exception e) {
         response.setStatus(500);
 
@@ -269,6 +274,7 @@ private HttpResponse handleError(Exception e) {
     /**
      * Check if the request path matches any configured template routes.
      * Uses the same pathMatches() logic as HttpRequest for consistency.
+     * Called BEFORE file resolution — routes take priority over file lookup.
      */
     private String resolveTemplateRoute(String path) {
         java.util.LinkedHashMap<String, String> routes = config.getTemplateRoutes();

karate-core/src/test/java/io/karatelabs/http/TemplateRouteTest.java

@@ -0,0 +1,96 @@
+package io.karatelabs.http;
+
+import io.karatelabs.markup.RootResourceResolver;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Tests for templateRoute() with path parameter extraction in templates.
+ * Verifies that templates can use request.pathMatches() and request.pathParams
+ * when served via route patterns.
+ */
+class TemplateRouteTest {
+
+    static InMemoryTestHarness harness;
+
+    @BeforeAll
+    static void beforeAll() {
+        ServerConfig config = new ServerConfig()
+                .sessionStore(new InMemorySessionStore())
+                .devMode(true)
+                .csrfEnabled(false)
+                .templateRoute("/items/{id}/edit", "detail.html")
+                .templateRoute("/items/{id}", "detail.html")
+                .fallbackTemplate("index.html");
+
+        RootResourceResolver resolver = new RootResourceResolver("classpath:demo");
+        ServerRequestHandler handler = new ServerRequestHandler(config, resolver);
+        harness = new InMemoryTestHarness(handler);
+    }
+
+    @Test
+    void testPathParamExtractedInTemplate() {
+        HttpResponse response = harness.get("/items/42");
+        assertEquals(200, response.getStatus());
+        String body = response.getBodyString();
+        // detail.html should extract itemId=42 via request.pathMatches('/items/{id}')
+        assertTrue(body.contains("Item: 42"), "Template should render path param");
+        assertTrue(body.contains("id=\"item-id\""));
+    }
+
+    @Test
+    void testPathParamWithDifferentValues() {
+        HttpResponse r1 = harness.get("/items/abc-123");
+        assertTrue(r1.getBodyString().contains("Item: abc-123"));
+
+        HttpResponse r2 = harness.get("/items/999");
+        assertTrue(r2.getBodyString().contains("Item: 999"));
+    }
+
+    @Test
+    void testMoreSpecificRouteMatchesFirst() {
+        // /items/42/edit should match the more specific route first
+        HttpResponse response = harness.get("/items/42/edit");
+        assertEquals(200, response.getStatus());
+        String body = response.getBodyString();
+        assertTrue(body.contains("Item: 42"));
+        assertTrue(body.contains("id=\"edit-mode\""), "Should be in edit mode");
+        assertFalse(body.contains("id=\"view-mode\""));
+    }
+
+    @Test
+    void testLessSpecificRouteIsViewMode() {
+        HttpResponse response = harness.get("/items/42");
+        String body = response.getBodyString();
+        assertTrue(body.contains("id=\"view-mode\""), "Should be in view mode");
+        assertFalse(body.contains("id=\"edit-mode\""));
+    }
+
+    @Test
+    void testExistingTemplateNotOverridden() {
+        // /items matches items.html (existing file) — should NOT use the route
+        HttpResponse response = harness.get("/items");
+        assertEquals(200, response.getStatus());
+        assertTrue(response.getBodyString().contains("Items List"),
+                "Existing items.html should render, not detail.html via route");
+    }
+
+    @Test
+    void testFallbackForUnmatchedPaths() {
+        // /unknown doesn't match any file or route → fallbackTemplate (index.html)
+        HttpResponse response = harness.get("/unknown/page");
+        assertEquals(200, response.getStatus());
+        assertTrue(response.getBodyString().contains("Demo App"));
+    }
+
+    @Test
+    void testDirectTemplateFileStillWorks() {
+        // /form matches form.html directly — normal template rendering
+        HttpResponse response = harness.get("/form");
+        assertEquals(200, response.getStatus());
+        assertTrue(response.getBodyString().contains("id=\"main-form\""));
+    }
+
+}

karate-core/src/test/resources/demo/detail.html

@@ -0,0 +1,15 @@
+<script ka:scope="global">
+    _.editMode = false;
+    if (request.pathMatches('/items/{id}/edit')) {
+        _.itemId = request.pathParams.id;
+        _.editMode = true;
+    } else if (request.pathMatches('/items/{id}')) {
+        _.itemId = request.pathParams.id;
+    }
+</script>
+<div id="detail-page">
+    <h1 th:text="'Item: ' + (itemId || 'unknown')">Item</h1>
+    <span id="item-id" th:text="itemId">id</span>
+    <span id="edit-mode" th:if="editMode">EDIT</span>
+    <span id="view-mode" th:unless="editMode">VIEW</span>
+</div>