Enforce explicit accessor pattern across core APIs (remove macro/inline accessors)

doc/project-doc/contributors/components/model-and-dom.md

@@ -36,11 +36,11 @@ All nodes can carry:
 
 `DocraftDocument` offers utility APIs to query and mutate the graph:
 
-- `get_by_name`, `get_first_by_name`, `get_last_by_name`,
-- `get_by_type<T>()`,
+- readonly: `find_by_name`, `find_first_by_name`, `find_last_by_name`, `find_by_type<T>()`,
+- mutable: `take_by_name`, `take_first_by_name`, `take_last_by_name`, `take_by_type<T>()`,
 - `traverse_dom(callback)`.
 
-Because nodes are mutable shared pointers, these APIs are used both by internal stages and by application code for runtime customization.
+Readonly methods return pointers to const nodes; use `edit_*` methods when runtime customization is required.
 
 ## 5. Clone behavior
 

doc/project-doc/users/craft-language.md

@@ -48,7 +48,7 @@ int main() {
 - `DocraftDocument::set_document_path(...)`
   - to choose output folder while keeping `title` as file name.
 - DOM APIs on `DocraftDocument`
-  - to modify parsed content before render (`get_by_name`, `get_by_type`, `traverse_dom`, `add_node`).
+  - to modify parsed content before render (`find_by_name`, `find_by_type`, `traverse_dom`, `add_node`).
 
 Custom backend example:
 
@@ -230,7 +230,7 @@ A common pattern is: parse `.craft`, then modify nodes programmatically before r
 
 ```cpp
 auto title_node = std::dynamic_pointer_cast<docraft::model::DocraftText>(
-    document->get_first_by_name("report_title"));
+    document->take_first_by_name("report_title"));
 if (title_node) {
     title_node->set_text("Q1 2026 - Final Version");
 }
@@ -239,7 +239,7 @@ if (title_node) {
 ### 6.2 Find nodes by type
 
 ```cpp
-auto texts = document->get_by_type<docraft::model::DocraftText>();
+auto texts = document->take_by_type<docraft::model::DocraftText>();
 for (const auto &text : texts) {
     if (text->text().empty()) {
         text->set_visible(false);

docraft/CMakeLists.txt

@@ -18,6 +18,8 @@ set(DOCRAFT_SOURCES
         include/docraft/model/docraft_new_page.h
         src/docraft/docraft_document.cc
         include/docraft/docraft_document.h
+        src/docraft/docraft_document_metadata.cc
+        include/docraft/docraft_document_metadata.h
         src/docraft/docraft_document_context.cc
         include/docraft/docraft_document_context.h
         src/docraft/docraft_cursor.cc
@@ -149,11 +151,20 @@ set(DOCRAFT_SOURCES
         src/docraft/model/docraft_foreach.cc
         include/docraft/model/docraft_foreach.h
         src/docraft/craft/parser/docraft_foreach_parser.cc
+        src/docraft/management/docraft_document_section_manager.cc
+        include/docraft/management/docraft_document_section_manager.h
+        src/docraft/management/docraft_backend_cache.cc
+        include/docraft/management/docraft_backend_cache.h
+        src/docraft/management/docraft_document_query.cc
+        include/docraft/management/docraft_document_query.h
+        include/docraft/management/docraft_document_query.hpp
+        src/docraft/management/docraft_document_config.cc
+        include/docraft/management/docraft_document_config.h
 )
 set(DOCRAFT_LIBRARY_TYPE STATIC)
-if(BUILD_SHARED_LIBS)
+if (BUILD_SHARED_LIBS)
     set(DOCRAFT_LIBRARY_TYPE SHARED)
-endif()
+endif ()
 add_library(docraft ${DOCRAFT_LIBRARY_TYPE}
         ${DOCRAFT_SOURCES}
 )
@@ -167,23 +178,23 @@ target_compile_definitions(docraft PUBLIC
         $<$<CONFIG:Debug>:docraft_debugf>
 )
 
-if(BUILD_SHARED_LIBS)
+if (BUILD_SHARED_LIBS)
     target_compile_definitions(docraft PRIVATE DOCRAFT_BUILD_SHARED_LIBS)#define the macro to build the shared lib
     target_compile_definitions(docraft INTERFACE DOCRAFT_USE_SHARED_LIB)#define the macro to use the shared lib
-endif()
+endif ()
 
 generate_docraft_fonts(docraft "${CMAKE_CURRENT_SOURCE_DIR}/fonts.json")
 add_executable(docraft_tool src/docraft/main.cpp)
 #declare define in the c++ code to export version
 target_compile_definitions(docraft_tool PRIVATE DOCRAFT_VERSION="${DOCRAFT_LIBRARY_VERSION}")
 configure_artifact_version(docraft_tool ${PROJECT_VERSION})
-if(TARGET pugixml::static)
+if (TARGET pugixml::static)
     set(PUGIXML_TARGET pugixml::static)
-elseif(TARGET pugixml::pugixml)
+elseif (TARGET pugixml::pugixml)
     set(PUGIXML_TARGET pugixml::pugixml)
-else()
+else ()
     message(FATAL_ERROR "No pugixml CMake target found")
-endif()
+endif ()
 
 target_link_libraries(docraft PUBLIC ${PUGIXML_TARGET} nlohmann_json::nlohmann_json ${LIBHARU_TARGET} fmt::fmt)
 target_link_libraries(docraft_tool PRIVATE docraft)

docraft/include/docraft/craft/docraft_craft_language_parser.h

@@ -57,7 +57,8 @@ namespace docraft::craft {
          * @brief Returns the parsed document.
          * @return Parsed document or nullptr if not parsed.
          */
-        std::shared_ptr<DocraftDocument> get_document() const;
+        [[nodiscard]] std::shared_ptr<const DocraftDocument> get_document() const;
+        [[nodiscard]] std::shared_ptr<DocraftDocument> edit_document();
 
         /**
          * @brief Parses a single XML node into a Docraft node.

docraft/include/docraft/docraft_backend_cache.h

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2026 Matteo Cadoni (https://github.com/cadons)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "docraft/docraft_lib.h"
+#include <memory>
+
+namespace docraft::backend {
+    class IDocraftRenderingBackend;
+    class IDocraftLineRenderingBackend;
+    class IDocraftShapeRenderingBackend;
+    class IDocraftTextRenderingBackend;
+    class IDocraftImageRenderingBackend;
+    class IDocraftPageRenderingBackend;
+}
+
+namespace docraft {
+    /**
+     * @brief Manages cached rendering backend interfaces.
+     *
+     * Provides access to specific backend interfaces (line, shape, text, image, page)
+     * derived from the main rendering backend. These are cached for performance.
+     */
+    class DOCRAFT_LIB DocraftBackendCache {
+    public:
+        /**
+         * @brief Initializes the backend cache from a main rendering backend.
+         * @param backend The main rendering backend.
+         */
+        void initialize_from_backend(const std::shared_ptr<backend::IDocraftRenderingBackend> &backend);
+
+        /**
+         * @brief Returns the line backend (cached).
+         * @return Line rendering backend.
+         */
+        [[nodiscard]] std::shared_ptr<const backend::IDocraftLineRenderingBackend> line_backend() const;
+
+        [[nodiscard]] std::shared_ptr<backend::IDocraftLineRenderingBackend> edit_line_backend();
+
+        /**
+         * @brief Returns the shape backend (cached).
+         * @return Shape rendering backend.
+         */
+        [[nodiscard]] std::shared_ptr<const backend::IDocraftShapeRenderingBackend> shape_backend() const;
+
+        [[nodiscard]] std::shared_ptr<backend::IDocraftShapeRenderingBackend> edit_shape_backend();
+
+        /**
+         * @brief Returns the text backend (cached).
+         * @return Text rendering backend.
+         */
+        [[nodiscard]] std::shared_ptr<const backend::IDocraftTextRenderingBackend> text_backend() const;
+
+        [[nodiscard]] std::shared_ptr<backend::IDocraftTextRenderingBackend> edit_text_backend();
+
+        /**
+         * @brief Returns the image backend (cached).
+         * @return Image rendering backend.
+         */
+        [[nodiscard]] std::shared_ptr<const backend::IDocraftImageRenderingBackend> image_backend() const;
+
+        [[nodiscard]] std::shared_ptr<backend::IDocraftImageRenderingBackend> edit_image_backend();
+
+        /**
+         * @brief Returns the page backend (cached).
+         * @return Page rendering backend.
+         */
+        [[nodiscard]] std::shared_ptr<const backend::IDocraftPageRenderingBackend> page_backend() const;
+
+        [[nodiscard]] std::shared_ptr<backend::IDocraftPageRenderingBackend> edit_page_backend();
+
+    private:
+        friend class DocraftDocumentContext;
+
+        /**
+         * @brief Refreshes all cached backend interfaces (called internally).
+         * @param backend The main rendering backend.
+         */
+        void refresh_caches(const std::shared_ptr<backend::IDocraftRenderingBackend> &backend);
+
+        std::shared_ptr<backend::IDocraftLineRenderingBackend> line_backend_;
+        std::shared_ptr<backend::IDocraftShapeRenderingBackend> shape_backend_;
+        std::shared_ptr<backend::IDocraftTextRenderingBackend> text_backend_;
+        std::shared_ptr<backend::IDocraftImageRenderingBackend> image_backend_;
+        std::shared_ptr<backend::IDocraftPageRenderingBackend> page_backend_;
+    };
+}
+

docraft/include/docraft/docraft_color.h

@@ -18,6 +18,7 @@
 
 #include "docraft/docraft_lib.h"
 #include <string>
+#include <cmath>
 
 namespace docraft {
     /**
@@ -49,11 +50,11 @@ namespace docraft {
          */
         std::string to_hex() const {
             auto clamp_byte = [](int v) -> int { return v < 0 ? 0 : (v > 255 ? 255 : v); };
-            int r_int = clamp_byte(static_cast<int>(r * 255.0F + 0.5F));//convert float to int between 0-255
-            int g_int = clamp_byte(static_cast<int>(g * 255.0F + 0.5F));
-            int b_int = clamp_byte(static_cast<int>(b * 255.0F + 0.5F));
-            int a_int = clamp_byte(static_cast<int>(a * 255.0F + 0.5F));
 
+            int r_int = clamp_byte(static_cast<int>(std::lround(static_cast<double>(r) * 255.0)));
+            int g_int = clamp_byte(static_cast<int>(std::lround(static_cast<double>(g) * 255.0)));
+            int b_int = clamp_byte(static_cast<int>(std::lround(static_cast<double>(b) * 255.0)));
+            int a_int = clamp_byte(static_cast<int>(std::lround(static_cast<double>(a) * 255.0)));
             char buf[10]; // "#RRGGBBAA" + null
             std::snprintf(buf, sizeof(buf), "#%02X%02X%02X%02X", r_int, g_int, b_int, a_int);//print the string in the buffer
             return std::string(buf);