react-native-enriched-markdown-scaffold 0.7.4-scaffold.9 → 1.0.2-scaffold.2

package/android/src/main/jni/react/renderer/components/EnrichedMarkdownTextSpec/MarkdownContainerShadowNode.cpp

@@ -12,6 +12,16 @@ void MarkdownContainerShadowNode::setMeasurementsManager(
   measurementsManager_ = measurementsManager;
 }
 
+void MarkdownContainerShadowNode::dirtyLayoutIfNeeded() {
+  const auto state = this->getStateData();
+  const auto counter = state.getForceHeightRecalculationCounter();
+
+  if (forceHeightRecalculationCounter_ != counter) {
+    forceHeightRecalculationCounter_ = counter;
+    dirtyLayout();
+  }
+}
+
 Size MarkdownContainerShadowNode::measureContent(const LayoutContext &layoutContext,
                                                  const LayoutConstraints &layoutConstraints) const {
   return measurementsManager_->measure(getSurfaceId(), getTag(), getConcreteProps(), layoutConstraints);

package/android/src/main/jni/react/renderer/components/EnrichedMarkdownTextSpec/MarkdownContainerShadowNode.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "MarkdownContainerMeasurementManager.h"
+#include "MarkdownTextState.h"
 
 #include <react/renderer/components/EnrichedMarkdownTextSpec/EventEmitters.h>
 #include <react/renderer/components/EnrichedMarkdownTextSpec/Props.h>
@@ -11,11 +12,16 @@ namespace facebook::react {
 JSI_EXPORT extern const char MarkdownContainerComponentName[];
 
 class MarkdownContainerShadowNode final
-    : public ConcreteViewShadowNode<MarkdownContainerComponentName, EnrichedMarkdownProps,
-                                    EnrichedMarkdownEventEmitter> {
+    : public ConcreteViewShadowNode<MarkdownContainerComponentName, EnrichedMarkdownProps, EnrichedMarkdownEventEmitter,
+                                    MarkdownTextState> {
 public:
   using ConcreteViewShadowNode::ConcreteViewShadowNode;
 
+  MarkdownContainerShadowNode(ShadowNode const &sourceShadowNode, ShadowNodeFragment const &fragment)
+      : ConcreteViewShadowNode(sourceShadowNode, fragment) {
+    dirtyLayoutIfNeeded();
+  }
+
   static ShadowNodeTraits BaseTraits() {
     auto traits = ConcreteViewShadowNode::BaseTraits();
     traits.set(ShadowNodeTraits::Trait::LeafYogaNode);
@@ -25,9 +31,12 @@ public:
 
   void setMeasurementsManager(const std::shared_ptr<MarkdownContainerMeasurementManager> &measurementsManager);
 
+  void dirtyLayoutIfNeeded();
+
   Size measureContent(const LayoutContext &layoutContext, const LayoutConstraints &layoutConstraints) const override;
 
 private:
+  int forceHeightRecalculationCounter_{0};
   std::shared_ptr<MarkdownContainerMeasurementManager> measurementsManager_;
 };
 

package/android/src/main/jni/react/renderer/components/EnrichedMarkdownTextSpec/MarkdownTextShadowNode.cpp

@@ -12,6 +12,16 @@ void MarkdownTextShadowNode::setMeasurementsManager(
   measurementsManager_ = measurementsManager;
 }
 
+void MarkdownTextShadowNode::dirtyLayoutIfNeeded() {
+  const auto state = this->getStateData();
+  const auto counter = state.getForceHeightRecalculationCounter();
+
+  if (forceHeightRecalculationCounter_ != counter) {
+    forceHeightRecalculationCounter_ = counter;
+    dirtyLayout();
+  }
+}
+
 Size MarkdownTextShadowNode::measureContent(const LayoutContext &layoutContext,
                                             const LayoutConstraints &layoutConstraints) const {
   return measurementsManager_->measure(getSurfaceId(), getTag(), getConcreteProps(), layoutConstraints);

package/android/src/main/jni/react/renderer/components/EnrichedMarkdownTextSpec/MarkdownTextShadowNode.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "MarkdownTextMeasurementManager.h"
+#include "MarkdownTextState.h"
 
 #include <react/renderer/components/EnrichedMarkdownTextSpec/EventEmitters.h>
 #include <react/renderer/components/EnrichedMarkdownTextSpec/Props.h>
@@ -13,11 +14,17 @@ JSI_EXPORT extern const char MarkdownTextComponentName[];
 /*
  * `ShadowNode` for <EnrichedMarkdownText> component.
  */
-class MarkdownTextShadowNode final : public ConcreteViewShadowNode<MarkdownTextComponentName, EnrichedMarkdownTextProps,
-                                                                   EnrichedMarkdownTextEventEmitter> {
+class MarkdownTextShadowNode final
+    : public ConcreteViewShadowNode<MarkdownTextComponentName, EnrichedMarkdownTextProps,
+                                    EnrichedMarkdownTextEventEmitter, MarkdownTextState> {
 public:
   using ConcreteViewShadowNode::ConcreteViewShadowNode;
 
+  MarkdownTextShadowNode(ShadowNode const &sourceShadowNode, ShadowNodeFragment const &fragment)
+      : ConcreteViewShadowNode(sourceShadowNode, fragment) {
+    dirtyLayoutIfNeeded();
+  }
+
   static ShadowNodeTraits BaseTraits() {
     auto traits = ConcreteViewShadowNode::BaseTraits();
     traits.set(ShadowNodeTraits::Trait::LeafYogaNode);
@@ -28,9 +35,12 @@ public:
   // Associates a shared `MarkdownTextMeasurementManager` with the node.
   void setMeasurementsManager(const std::shared_ptr<MarkdownTextMeasurementManager> &measurementsManager);
 
+  void dirtyLayoutIfNeeded();
+
   Size measureContent(const LayoutContext &layoutContext, const LayoutConstraints &layoutConstraints) const override;
 
 private:
+  int forceHeightRecalculationCounter_{0};
   std::shared_ptr<MarkdownTextMeasurementManager> measurementsManager_;
 };
 

package/android/src/main/jni/react/renderer/components/EnrichedMarkdownTextSpec/MarkdownTextState.cpp

@@ -0,0 +1,9 @@
+#include "MarkdownTextState.h"
+
+namespace facebook::react {
+
+int MarkdownTextState::getForceHeightRecalculationCounter() const {
+  return forceHeightRecalculationCounter_;
+}
+
+} // namespace facebook::react

package/android/src/main/jni/react/renderer/components/EnrichedMarkdownTextSpec/MarkdownTextState.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#include <folly/dynamic.h>
+
+namespace facebook::react {
+
+class MarkdownTextState {
+public:
+  MarkdownTextState() : forceHeightRecalculationCounter_(0) {}
+
+  MarkdownTextState(MarkdownTextState const &previousState, folly::dynamic data)
+      : forceHeightRecalculationCounter_((int)data["forceHeightRecalculationCounter"].getInt()) {}
+
+  folly::dynamic getDynamic() const {
+    return {};
+  }
+
+  int getForceHeightRecalculationCounter() const;
+
+private:
+  const int forceHeightRecalculationCounter_{};
+};
+
+} // namespace facebook::react

package/android/src/main/jni/react/renderer/components/EnrichedMarkdownTextSpec/conversions.h

@@ -12,9 +12,17 @@ inline folly::dynamic toDynamic(const EnrichedMarkdownTextProps &props) {
   serializedProps["markdown"] = props.markdown;
   serializedProps["markdownStyle"] = toDynamic(props.markdownStyle);
   serializedProps["md4cFlags"] = toDynamic(props.md4cFlags);
+  serializedProps["allowFontScaling"] = props.allowFontScaling;
+  serializedProps["maxFontSizeMultiplier"] = props.maxFontSizeMultiplier;
   serializedProps["allowTrailingMargin"] = props.allowTrailingMargin;
   serializedProps["streamingAnimation"] = props.streamingAnimation;
 
+  folly::dynamic imageRequestHeaders = folly::dynamic::array();
+  for (const auto &header : props.imageRequestHeaders) {
+    imageRequestHeaders.push_back(toDynamic(header));
+  }
+  serializedProps["imageRequestHeaders"] = std::move(imageRequestHeaders);
+
   return serializedProps;
 }
 
@@ -23,9 +31,17 @@ inline folly::dynamic toDynamic(const EnrichedMarkdownProps &props) {
   serializedProps["markdown"] = props.markdown;
   serializedProps["markdownStyle"] = toDynamic(props.markdownStyle);
   serializedProps["md4cFlags"] = toDynamic(props.md4cFlags);
+  serializedProps["allowFontScaling"] = props.allowFontScaling;
+  serializedProps["maxFontSizeMultiplier"] = props.maxFontSizeMultiplier;
   serializedProps["allowTrailingMargin"] = props.allowTrailingMargin;
   serializedProps["streamingAnimation"] = props.streamingAnimation;
 
+  folly::dynamic imageRequestHeaders = folly::dynamic::array();
+  for (const auto &header : props.imageRequestHeaders) {
+    imageRequestHeaders.push_back(toDynamic(header));
+  }
+  serializedProps["imageRequestHeaders"] = std::move(imageRequestHeaders);
+
   return serializedProps;
 }
 

package/android/src/math/java/com/swmansion/enriched/markdown/input/math/MathChipControllerImpl.kt

@@ -195,11 +195,28 @@ class MathChipControllerImpl(
   ) {
     if (!displayMode) return
     val blockStyle = style as? MathBlockStyle ?: return
-    if (blockStyle.alignment == Layout.Alignment.ALIGN_NORMAL) return
+    if (blockStyle.textAlign == Layout.Alignment.ALIGN_NORMAL) return
+
+    // An AlignmentSpan is paragraph-scoped, and SpannableStringBuilder *throws* unless a
+    // SPAN_PARAGRAPH span starts at a paragraph boundary and ends just past one — its end
+    // check is `charAt(end - 1) == '\n' || end == length`. A bare (position, position + 1)
+    // span therefore crashes for every chip that is not the buffer's last character, so
+    // the span has to cover the chip's whole paragraph, trailing newline included.
+    var start = position
+    while (start > 0 && editable[start - 1] != '\n') start--
+    var end = position + 1
+    while (end < editable.length && editable[end - 1] != '\n') end++
+
+    // Align only a paragraph the chip owns. Display math can also arrive from the middle
+    // of a paragraph ("text $$x$$ more", upstream #537); aligning that whole paragraph
+    // because of one formula would move the surrounding prose too.
+    val glyphCount = (start until end).count { editable[it] != '\n' }
+    if (glyphCount != 1) return
+
     editable.setSpan(
-      AlignmentSpan.Standard(blockStyle.alignment),
-      position,
-      position + 1,
+      AlignmentSpan.Standard(blockStyle.textAlign),
+      start,
+      end,
       Spanned.SPAN_PARAGRAPH,
     )
   }

package/android/src/math/java/com/swmansion/enriched/markdown/renderer/MathInlineRenderer.kt

@@ -43,7 +43,12 @@ class MathInlineRenderer(
   }
 
   private fun extractLatex(node: MarkdownASTNode): String {
-    if (!node.content.isNullOrEmpty()) return node.content!!
-    return node.children.mapNotNull { it.content }.joinToString("")
+    if (node.content.isNotEmpty()) return node.content
+    return node.children.joinToString("") { child ->
+      when (child.type) {
+        MarkdownASTNode.NodeType.SoftBreak, MarkdownASTNode.NodeType.LineBreak -> " "
+        else -> child.content
+      }
+    }
   }
 }

package/android/src/math/java/com/swmansion/enriched/markdown/spans/MathChipSpan.kt

@@ -185,7 +185,7 @@ class MathChipSpan(
         if (blockStyle != null && totalWidth > intrinsicWidth) {
           val slack = totalWidth - formulaWidth - style.paddingHorizontal * 2f
           val offset =
-            when (blockStyle.alignment) {
+            when (blockStyle.textAlign) {
               Layout.Alignment.ALIGN_CENTER -> slack / 2f
               Layout.Alignment.ALIGN_OPPOSITE -> slack
               else -> 0f

package/android/src/math/java/com/swmansion/enriched/markdown/views/MathContainerView.kt

@@ -41,6 +41,8 @@ class MathContainerView(
   // Set reflectively by EnrichedMarkdown (math is an optional module).
   var copyLabel: String = ""
   var copyAsMarkdownLabel: String = ""
+  var contextMenuHidden: Boolean = false
+  var menuOptions: BlockMenuOptions = BlockMenuOptions()
 
   override val segmentMarginTop: Int get() = mathStyle.marginTop.toInt()
   override val segmentMarginBottom: Int get() = mathStyle.marginBottom.toInt()
@@ -117,14 +119,14 @@ class MathContainerView(
   }
 
   private fun showContextMenu(anchor: View) {
+    if (contextMenuHidden) return
     val clipboard = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
     ContextMenuPopup.show(anchor, this) {
-      item(ContextMenuPopup.Icon.COPY, copyLabel) {
+      blockCopyItems(menuOptions, copyLabel, copyAsMarkdownLabel, copyRaw = {
         clipboard.setPrimaryClip(ClipData.newPlainText("Math", cachedLatex))
-      }
-      item(ContextMenuPopup.Icon.DOCUMENT, copyAsMarkdownLabel) {
+      }, copyMarkdown = {
         clipboard.setPrimaryClip(ClipData.newPlainText("Math", "$$\n$cachedLatex\n$$"))
-      }
+      })
     }
   }
 

package/cpp/highlight/CodeBlockHighlighter.cpp

@@ -0,0 +1,284 @@
+#include "CodeBlockHighlighter.hpp"
+
+// Stub compiled when the syntax highlighting module is disabled. The real
+// implementation defines the same symbol under ENRICHED_MARKDOWN_CODE_HIGHLIGHT,
+// so exactly one definition exists in any build configuration.
+
+#if !defined(ENRICHED_MARKDOWN_CODE_HIGHLIGHT)
+
+namespace Markdown {
+
+std::vector<HighlightToken> highlightCode(const std::string & /*code*/, const std::string & /*language*/) {
+  return {};
+}
+
+} // namespace Markdown
+
+#else
+
+#include "CodeBlockLanguages.hpp"
+#include "HighlightGrammars.hpp"
+
+#include <tree_sitter/api.h>
+
+#include <algorithm>
+#include <cstring>
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+
+namespace Markdown {
+
+namespace {
+
+// Bounds the synchronous main-thread parse against pathological inputs. Typical
+// blocks parse in sub-millisecond to low-millisecond time; anything past these
+// caps falls back to plain rendering instead of risking a frame hang.
+constexpr size_t kMaxBytes = 50u * 1024u;
+constexpr size_t kMaxLines = 2000u;
+
+// tree-sitter highlight capture names, flattened to their leading dotted
+// prefix. The longest matching prefix wins, so "variable.member" resolves to
+// Property while a bare "variable" resolves to Variable. Names with no entry
+// (for example "spell", "none") are skipped and leave their bytes uncolored.
+struct CaptureMapping {
+  const char *prefix;
+  HighlightTokenType type;
+};
+
+constexpr CaptureMapping kCaptureMappings[] = {
+    {"keyword", HighlightTokenType::Keyword},
+    {"operator", HighlightTokenType::Operator},
+    {"punctuation", HighlightTokenType::Punctuation},
+    {"string", HighlightTokenType::String},
+    {"escape", HighlightTokenType::String},
+    {"character", HighlightTokenType::String},
+    {"number", HighlightTokenType::Number},
+    {"float", HighlightTokenType::Number},
+    {"boolean", HighlightTokenType::Constant},
+    {"constant", HighlightTokenType::Constant},
+    {"comment", HighlightTokenType::Comment},
+    {"function", HighlightTokenType::Function},
+    {"method", HighlightTokenType::Function},
+    {"constructor", HighlightTokenType::Type},
+    {"type", HighlightTokenType::Type},
+    {"module", HighlightTokenType::Type},
+    {"namespace", HighlightTokenType::Type},
+    {"variable", HighlightTokenType::Variable},
+    {"parameter", HighlightTokenType::Variable},
+    {"variable.member", HighlightTokenType::Property},
+    {"property", HighlightTokenType::Property},
+    {"field", HighlightTokenType::Property},
+    {"tag", HighlightTokenType::Tag},
+    {"attribute", HighlightTokenType::Attribute},
+    {"embedded", HighlightTokenType::Embedded},
+    {"injection", HighlightTokenType::Embedded},
+};
+
+// A capture name matches a prefix only on dotted boundaries so "type" never
+// swallows "typename"-style names. Returns false when nothing maps.
+bool mapCaptureName(const char *name, uint32_t length, HighlightTokenType &out) {
+  size_t best = 0;
+  bool found = false;
+  for (const CaptureMapping &m : kCaptureMappings) {
+    size_t plen = std::strlen(m.prefix);
+    if (plen > length || plen < best) {
+      continue;
+    }
+    if (std::strncmp(name, m.prefix, plen) != 0) {
+      continue;
+    }
+    if (plen != length && name[plen] != '.') {
+      continue;
+    }
+    best = plen;
+    out = m.type;
+    found = true;
+  }
+  return found;
+}
+
+// Compiled queries are immutable after creation and reused across calls. Access
+// is serialized on the main thread today; the mutex is cheap insurance should
+// highlighting ever move off-main. A cached nullptr marks a query that failed to
+// compile so it is not retried.
+TSQuery *queryForLanguage(const TSLanguage *language, const char *source) {
+  static std::mutex mutex;
+  static std::unordered_map<const TSLanguage *, TSQuery *> cache;
+
+  std::lock_guard<std::mutex> lock(mutex);
+  auto it = cache.find(language);
+  if (it != cache.end()) {
+    return it->second;
+  }
+
+  uint32_t errorOffset = 0;
+  TSQueryError errorType = TSQueryErrorNone;
+  TSQuery *query = ts_query_new(language, source, static_cast<uint32_t>(std::strlen(source)), &errorOffset, &errorType);
+  cache.emplace(language, query);
+  return query;
+}
+
+// Precomputes, for every byte offset that starts a code point, the number of
+// UTF-16 code units preceding it. Token boundaries always land on code-point
+// boundaries, so mapping a byte offset is a single lookup. Astral code points
+// (4-byte UTF-8) contribute a surrogate pair (+2).
+std::vector<uint32_t> buildUtf16PrefixMap(const std::string &code) {
+  const size_t n = code.size();
+  std::vector<uint32_t> prefix(n + 1, 0);
+  uint32_t units = 0;
+  size_t i = 0;
+  while (i < n) {
+    unsigned char c = static_cast<unsigned char>(code[i]);
+    size_t len;
+    uint32_t width;
+    if (c < 0x80) {
+      len = 1;
+      width = 1;
+    } else if ((c >> 5) == 0x6) {
+      len = 2;
+      width = 1;
+    } else if ((c >> 4) == 0xE) {
+      len = 3;
+      width = 1;
+    } else if ((c >> 3) == 0x1E) {
+      len = 4;
+      width = 2;
+    } else {
+      len = 1;
+      width = 1;
+    }
+    units += width;
+    for (size_t k = 1; k <= len && i + k <= n; ++k) {
+      prefix[i + k] = units;
+    }
+    i += len;
+  }
+  return prefix;
+}
+
+using ParserPtr = std::unique_ptr<TSParser, decltype(&ts_parser_delete)>;
+using TreePtr = std::unique_ptr<TSTree, decltype(&ts_tree_delete)>;
+using CursorPtr = std::unique_ptr<TSQueryCursor, decltype(&ts_query_cursor_delete)>;
+
+} // namespace
+
+// Resolves the language to a compiled grammar, parses the code, runs the
+// grammar's highlight query, resolves overlapping captures (innermost span
+// wins per byte), and returns coalesced foreground-only tokens with UTF-16
+// offsets. Any failure along the way degrades to an empty vector (plain
+// rendering).
+std::vector<HighlightToken> highlightCode(const std::string &code, const std::string &language) {
+  try {
+    if (code.empty()) {
+      return {};
+    }
+
+    std::string grammarId = canonicalGrammarId(language);
+    if (grammarId.empty()) {
+      return {};
+    }
+    const GrammarEntry *grammar = findGrammar(grammarId.c_str());
+    if (grammar == nullptr) {
+      return {};
+    }
+
+    if (code.size() > kMaxBytes) {
+      return {};
+    }
+    size_t lines = 1;
+    for (char c : code) {
+      if (c == '\n' && ++lines > kMaxLines) {
+        return {};
+      }
+    }
+
+    ParserPtr parser(ts_parser_new(), ts_parser_delete);
+    if (!parser) {
+      return {};
+    }
+    const TSLanguage *tsLanguage = grammar->language();
+    if (tsLanguage == nullptr || !ts_parser_set_language(parser.get(), tsLanguage)) {
+      return {};
+    }
+
+    TSQuery *query = queryForLanguage(tsLanguage, grammar->highlightsQuery);
+    if (query == nullptr) {
+      return {};
+    }
+
+    TreePtr tree(ts_parser_parse_string(parser.get(), nullptr, code.c_str(), static_cast<uint32_t>(code.size())),
+                 ts_tree_delete);
+    if (!tree) {
+      return {};
+    }
+
+    CursorPtr cursor(ts_query_cursor_new(), ts_query_cursor_delete);
+    if (!cursor) {
+      return {};
+    }
+    ts_query_cursor_exec(cursor.get(), query, ts_tree_root_node(tree.get()));
+
+    // Innermost-wins overlap resolution: paint each capture's byte range,
+    // widest span first, so tighter captures overwrite. A -1 byte is uncolored.
+    struct Capture {
+      uint32_t start;
+      uint32_t end;
+      HighlightTokenType type;
+    };
+    std::vector<Capture> captures;
+    TSQueryMatch match;
+    uint32_t captureIndex = 0;
+    while (ts_query_cursor_next_capture(cursor.get(), &match, &captureIndex)) {
+      const TSQueryCapture &capture = match.captures[captureIndex];
+      uint32_t nameLength = 0;
+      const char *name = ts_query_capture_name_for_id(query, capture.index, &nameLength);
+      HighlightTokenType type;
+      if (name == nullptr || !mapCaptureName(name, nameLength, type)) {
+        continue;
+      }
+      uint32_t start = ts_node_start_byte(capture.node);
+      uint32_t end = ts_node_end_byte(capture.node);
+      if (end > start && end <= code.size()) {
+        captures.push_back({start, end, type});
+      }
+    }
+    if (captures.empty()) {
+      return {};
+    }
+
+    std::stable_sort(captures.begin(), captures.end(),
+                     [](const Capture &a, const Capture &b) { return (a.end - a.start) > (b.end - b.start); });
+
+    std::vector<int8_t> byteType(code.size(), -1);
+    for (const Capture &capture : captures) {
+      for (uint32_t b = capture.start; b < capture.end; ++b) {
+        byteType[b] = static_cast<int8_t>(capture.type);
+      }
+    }
+
+    std::vector<uint32_t> u16 = buildUtf16PrefixMap(code);
+    std::vector<HighlightToken> tokens;
+    size_t b = 0;
+    const size_t n = code.size();
+    while (b < n) {
+      if (byteType[b] < 0) {
+        ++b;
+        continue;
+      }
+      int8_t type = byteType[b];
+      size_t runStart = b;
+      while (b < n && byteType[b] == type) {
+        ++b;
+      }
+      tokens.push_back({u16[runStart], u16[b], static_cast<HighlightTokenType>(type)});
+    }
+    return tokens;
+  } catch (...) {
+    return {};
+  }
+}
+
+} // namespace Markdown
+
+#endif

package/cpp/highlight/CodeBlockHighlighter.hpp

@@ -0,0 +1,66 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+// Shared seam for optional syntax highlighting of fenced code blocks.
+//
+// The real implementation is compiled only when ENRICHED_MARKDOWN_CODE_HIGHLIGHT
+// is defined by the build. Without the flag the stub in CodeBlockHighlighter.cpp
+// returns no tokens and platform callers keep the plain uncolored rendering, so
+// the absent module degrades to the default code block appearance. The same
+// fallback applies at runtime when a language has no compiled grammar or
+// highlighting fails.
+//
+// The seam returns semantic tokens instead of a platform text type on
+// purpose. Platform adapters map token types to foreground colors and apply
+// them to their attributed string. Since foreground color never affects text
+// metrics, the block height measured from the plain string is guaranteed to
+// match the drawn height regardless of what an implementation returns.
+//
+// Token offsets are UTF-16 code units into the code string, because both
+// Android (Spannable) and iOS (NSAttributedString) address text in UTF-16.
+// Implementations are responsible for converting tree-sitter byte offsets.
+//
+// Token types follow tree-sitter's standard highlight capture names,
+// flattened to one level. Values are explicit because they cross the JNI
+// boundary as plain integers.
+//
+// Both markdown flavors call this seam: the github flavor highlights the code
+// string in its container view, and the commonmark renderers
+// (CodeBlockRenderer.kt / CodeBlockRenderer.m) apply the tokens to their
+// content range through the platform adapters.
+
+namespace Markdown {
+
+enum class HighlightTokenType : uint8_t {
+    Keyword = 0,
+    Operator = 1,
+    Punctuation = 2,
+    String = 3,
+    Number = 4,
+    Constant = 5,
+    Comment = 6,
+    Function = 7,
+    Type = 8,
+    Variable = 9,
+    Property = 10,
+    Tag = 11,
+    Attribute = 12,
+    Embedded = 13,
+};
+
+struct HighlightToken {
+    uint32_t start;
+    uint32_t end;
+    HighlightTokenType type;
+};
+
+// code is the UTF-8 code block content without the fence lines; language is
+// the fence info string (for example "python"), empty when absent. Returns an
+// empty vector whenever highlighting is unavailable (module compiled out,
+// unknown language, parse failure).
+std::vector<HighlightToken> highlightCode(const std::string& code, const std::string& language);
+
+} // namespace Markdown