fix

engine/include/pdfengine/pdf_document.hpp

@@ -53,6 +53,39 @@ struct GlyphBounds {
     double fontSize;
 };
 
+/**
+ * @struct FontInfo
+ * @brief Represents diagnostics and introspection details of a PDF font.
+ * 
+ * ### Thread-Safety Contract:
+ * All getFonts() calls on PdfPage and PdfDocument implementations are fully thread-safe
+ * and support concurrent reads. Document-level implementations use thread-safe lazy caching
+ * protected by internal mutex locks, allowing safe multi-threaded introspection.
+ */
+struct FontInfo {
+    std::string fontName;
+    std::string type;              // "TrueType", "Type1", "CIDFontType0", "CIDFontType2"
+    bool isEmbedded = false;
+    bool isSubset = false;
+    bool isVertical = false;
+
+    // Advanced Introspection & Diagnostics
+    std::string encoding;          // "WinAnsiEncoding", "MacRomanEncoding", "Identity-H", "Identity-V", "Symbol", "Custom", "None"
+    bool hasToUnicode = false;     // True if font has an active /ToUnicode map
+    std::string cmapName;          // e.g. "Identity-H", "Identity-V", "UniJIS-UTF16-H"
+    std::string cidSystemInfo;     // e.g. "Adobe-Japan1", "Adobe-GB1", "Adobe-Korea1"
+    std::string subsetTag;         // e.g. "ABCDEE" (6-character uppercase tag)
+    std::string sourceType;        // "Embedded", "SystemFallback", "Substituted"
+    std::string substitutedFrom;   // e.g. "Helvetica" (Original requested font)
+    std::string substitutedTo;     // e.g. "Liberation Sans" (Actual fallback font used)
+    std::string normalizedFamily;  // e.g. "Arial" (Normalized family grouping name)
+    std::string internalFontId;    // Unique stable identifier for internal tracking
+    uint32_t flags = 0;            // PDF font descriptor flags
+    double ascent = 0.0;           // Font descriptor Ascent metric
+    double descent = 0.0;          // Font descriptor Descent metric
+    double capHeight = 0.0;        // Font descriptor CapHeight metric
+};
+
 class PdfPage {
 public:
     virtual ~PdfPage() = default;
@@ -66,6 +99,8 @@ public:
 
     [[nodiscard]] virtual std::expected<std::vector<GlyphBounds>, EngineError> extractTextWithBounds() const = 0;
 
+    [[nodiscard]] virtual std::expected<std::vector<FontInfo>, EngineError> getFonts() const = 0;
+
     [[nodiscard]] virtual DevicePoint pageToDevice(const Point2D& pagePoint, int deviceWidth, int deviceHeight, int rotate = 0) const noexcept = 0;
     [[nodiscard]] virtual Point2D deviceToPage(const DevicePoint& devicePoint, int deviceWidth, int deviceHeight, int rotate = 0) const noexcept = 0;
 };
@@ -86,6 +121,9 @@ public:
     [[nodiscard]] virtual std::expected<std::shared_ptr<PdfPage>, EngineError> 
     getPage(int pageIndex) = 0;
 
+    [[nodiscard]] virtual std::expected<std::vector<FontInfo>, EngineError> 
+    getFonts(int startPage = 0, int endPage = -1) const = 0;
+
     virtual std::expected<void, EngineError> applyEdits(const std::string& editsJson) = 0;
 
     [[nodiscard]] virtual std::expected<std::vector<uint8_t>, EngineError>