feat(core): add template rendering with res.render and view integration

Author: GaspardKirira

include/vix/app/App.hpp

@@ -34,6 +34,9 @@
 #include <vix/server/HTTPServer.hpp>
 #include <vix/utils/Logger.hpp>
 #include <vix/utils/ServerPrettyLogs.hpp>
+#include <vix/template/Engine.hpp>
+#include <vix/template/FileSystemLoader.hpp>
+#include <vix/view/TemplateView.hpp>
 
 namespace vix::router
 {
@@ -324,6 +327,44 @@ namespace vix
       return *executor_;
     }
 
+    /**
+     * @brief Configure the application template directory.
+     *
+     * This initializes:
+     * - the file-system template loader
+     * - the template engine
+     * - the HTTP-oriented template view facade
+     *
+     * @param directory Root directory containing template files.
+     * @return App& Current application instance.
+     */
+    App &templates(const std::string &directory);
+
+    /**
+     * @brief Returns whether template rendering is configured.
+     *
+     * @return true if views are available, false otherwise.
+     */
+    [[nodiscard]] bool has_views() const noexcept;
+
+    /**
+     * @brief Returns the template rendering facade.
+     *
+     * @return vix::view::TemplateView& Mutable template view facade.
+     *
+     * @throws std::runtime_error if templates() was not called.
+     */
+    [[nodiscard]] vix::view::TemplateView &views();
+
+    /**
+     * @brief Returns the template rendering facade.
+     *
+     * @return const vix::view::TemplateView& Immutable template view facade.
+     *
+     * @throws std::runtime_error if templates() was not called.
+     */
+    [[nodiscard]] const vix::view::TemplateView &views() const;
+
     /**
      * @brief Indicates whether the server has started.
      *
@@ -762,7 +803,10 @@ namespace vix
       };
 
       using Adapter = vix::vhttp::RequestHandler<decltype(wrapped)>;
-      auto request_handler = std::make_shared<Adapter>(path, std::move(wrapped));
+      auto request_handler = std::make_shared<Adapter>(
+          path,
+          std::move(wrapped),
+          template_view_.get());
 
       router_->add_route(method, path, request_handler, opt);
 
@@ -874,7 +918,10 @@ namespace vix
       };
 
       using Adapter = vix::vhttp::RequestHandler<decltype(wrapped)>;
-      auto request_handler = std::make_shared<Adapter>(path, std::move(wrapped));
+      auto request_handler = std::make_shared<Adapter>(
+          path,
+          std::move(wrapped),
+          template_view_.get());
 
       router_->add_route("OPTIONS", path, request_handler, vix::router::RouteOptions{});
     }
@@ -905,6 +952,21 @@ namespace vix
 
     std::vector<MiddlewareEntry> middlewares_;
     std::atomic<bool> closed_{false};
+
+    /**
+     * @brief Shared template engine used by the application runtime.
+     */
+    std::shared_ptr<vix::template_::Engine> template_engine_{};
+
+    /**
+     * @brief HTTP-oriented template rendering facade.
+     */
+    std::unique_ptr<vix::view::TemplateView> template_view_{};
+
+    /**
+     * @brief Configured template root directory.
+     */
+    std::string templates_directory_{};
   };
 
 } // namespace vix

include/vix/core.hpp

@@ -5,7 +5,7 @@
  *
  * Copyright 2025, Gaspard Kirira. All rights reserved.
  * https://github.com/vixcpp/vix
- * Use of this source code is governed by a MIT license that can be found in the License file.
+ * Use of this source code is governed by a MIT license thatcan be found in the License file.
  *
  * Vix.cpp
  *
@@ -18,9 +18,6 @@
 #include <vector>
 #include <functional>
 
-#include <boost/asio.hpp>
-#include <boost/beast/http.hpp>
-
 #include <vix/console.hpp>
 #include <vix/print.hpp>
 #include <vix/console.hpp>
@@ -35,17 +32,22 @@
 #include <vix/config/Config.hpp>
 #include <vix/http/Status.hpp>
 
-namespace asio = boost::asio;
-namespace beast = boost::beast;
-namespace bhttp = boost::beast::http;
-
 namespace vix
 {
-
   /**
-   * @brief Core type aliases and common includes for Vix.
+   * @brief Public template namespace alias.
+   *
+   * This alias exposes the template module under a shorter and cleaner name.
+   * It allows users to access template-related types such as Context and Engine
+   * without referencing the internal `template_` namespace directly.
+   *
+   * Example:
+   * @code
+   * vix::tmpl::Context ctx;
+   * ctx.set("title", "Home");
+   * @endcode
    */
-  using tcp = asio::ip::tcp;
+  namespace tmpl = vix::template_;
 
   /** @brief Shared pointer to App. */
   using AppPtr = std::shared_ptr<App>;
@@ -58,7 +60,6 @@ namespace vix
 
   /** @brief HTTP response alias. */
   using Response = vix::vhttp::ResponseWrapper;
-
 } // namespace vix
 
 #endif // VIX_CORE_HPP

include/vix/http/RequestHandler.hpp

@@ -221,17 +221,20 @@ namespace vix::vhttp
 
   public:
     /** @brief Create a handler adapter for a route pattern and a user handler. */
-    RequestHandler(std::string route_pattern, Handler handler)
+    RequestHandler(std::string route_pattern,
+                   Handler handler,
+                   vix::view::TemplateView *template_view = nullptr)
         : route_pattern_(std::move(route_pattern)),
-          handler_(std::move(handler))
+          handler_(std::move(handler)),
+          template_view_(template_view)
     {
       static_assert(sizeof(Handler) > 0, "Handler type must be complete here.");
     }
 
     /** @brief Execute the user handler and write the final HTTP response. */
     task<void> handle_request(const Request &incoming_req, Response &res) override
     {
-      ResponseWrapper wrapped{res};
+      ResponseWrapper wrapped{res, template_view_};
 
       auto params = extract_params_from_path(route_pattern_, incoming_req.path());
       auto state = incoming_req.state_ptr()
@@ -318,6 +321,7 @@ namespace vix::vhttp
   private:
     std::string route_pattern_;
     Handler handler_;
+    vix::view::TemplateView *template_view_{nullptr};
 
     static void finalize_response(const Request &req, Response &res)
     {

include/vix/http/ResponseWrapper.hpp

@@ -30,6 +30,8 @@
 #include <vix/http/Response.hpp>
 #include <vix/http/Status.hpp>
 #include <vix/json/Simple.hpp>
+#include <vix/template/Context.hpp>
+#include <vix/view/TemplateView.hpp>
 
 namespace vix::vhttp
 {
@@ -130,10 +132,14 @@ namespace vix::vhttp
   struct ResponseWrapper
   {
     Response &res;
+    vix::view::TemplateView *template_view_{nullptr};
 
     /** @brief Wrap an existing native Vix response and ensure a default status code. */
-    explicit ResponseWrapper(Response &r) noexcept
-        : res(r)
+    explicit ResponseWrapper(
+        Response &r,
+        vix::view::TemplateView *template_view = nullptr) noexcept
+        : res(r),
+          template_view_(template_view)
     {
       if (!is_valid_status(res.status()))
         res.set_status(OK);
@@ -396,6 +402,32 @@ namespace vix::vhttp
       return *this;
     }
 
+    /** @brief Render an HTML template using the configured template view. */
+    ResponseWrapper &render(
+        const std::string &name,
+        const vix::template_::Context &context)
+    {
+      ensure_status();
+
+      const int s = res.status();
+      if (s == NO_CONTENT || s == NOT_MODIFIED)
+        return this->send();
+
+      if (!template_view_)
+      {
+        throw std::runtime_error(
+            "ResponseWrapper::render() called but templates are not configured");
+      }
+
+      const int current_status = res.status();
+
+      auto rendered = template_view_->render_response(name, context);
+      rendered.set_status(current_status);
+
+      res = std::move(rendered);
+      return *this;
+    }
+
     /** @brief Send JSON using nlohmann::json with an auto Content-Type if missing. */
     ResponseWrapper &json(const nlohmann::json &j)
     {

include/vix/view/TemplateView.hpp

@@ -0,0 +1,108 @@
+/**
+ *
+ *  @file TemplateView.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.
+ *  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ *
+ */
+
+#ifndef VIX_VIEW_TEMPLATE_VIEW_HPP
+#define VIX_VIEW_TEMPLATE_VIEW_HPP
+
+#include <memory>
+#include <string>
+
+#include <vix/http/Response.hpp>
+#include <vix/template/Context.hpp>
+#include <vix/template/Engine.hpp>
+
+namespace vix::view
+{
+  /**
+   * @brief HTTP-integrated template rendering facade.
+   *
+   * TemplateView is the bridge between:
+   * - the Vix runtime HTTP layer
+   * - the template engine
+   *
+   * Responsibilities:
+   * - render templates by name
+   * - convert render results into native HTTP responses
+   * - expose streaming rendering for large outputs
+   */
+  class TemplateView
+  {
+  public:
+    /**
+     * @brief Construct a TemplateView from a template engine.
+     *
+     * @param engine Shared template engine instance.
+     */
+    explicit TemplateView(
+        std::shared_ptr<vix::template_::Engine> engine);
+
+    /**
+     * @brief Render a template to a string.
+     *
+     * @param name Template name.
+     * @param context Runtime rendering context.
+     * @return Rendered HTML string.
+     */
+    [[nodiscard]] std::string render(
+        const std::string &name,
+        const vix::template_::Context &context) const;
+
+    /**
+     * @brief Render a template and produce a native HTTP response.
+     *
+     * @param name Template name.
+     * @param context Runtime rendering context.
+     * @return HTTP response containing rendered HTML.
+     */
+    [[nodiscard]] vix::vhttp::Response render_response(
+        const std::string &name,
+        const vix::template_::Context &context) const;
+
+    /**
+     * @brief Render a template in streaming mode.
+     *
+     * @tparam Output Output sink type.
+     * @param name Template name.
+     * @param context Runtime rendering context.
+     * @param out Output sink receiving rendered chunks.
+     */
+    template <typename Output>
+    void render_stream(
+        const std::string &name,
+        const vix::template_::Context &context,
+        Output &out) const
+    {
+      engine_->render_stream(name, context, out);
+    }
+
+    /**
+     * @brief Access the underlying template engine.
+     *
+     * @return Shared engine instance.
+     */
+    [[nodiscard]] const std::shared_ptr<vix::template_::Engine> &
+    engine() const noexcept;
+
+  private:
+    /**
+     * @brief Shared template engine.
+     */
+    std::shared_ptr<vix::template_::Engine> engine_;
+  };
+
+} // namespace vix::view
+
+#endif // VIX_VIEW_TEMPLATE_VIEW_HPP