From 8db94f95559b2ee5b150b95046dadcd2274132a3 Mon Sep 17 00:00:00 2001
From: Yangtse Su <yangtsesu@gmail.com>
Date: Thu, 15 Oct 2026 01:57:21 +0800
Subject: [PATCH 1/2] feat(core): resolve missing text deltas through font
 advances

An OFD text run that declares no `DeltaX` for a scalar is positioned by that
scalar's font advance, which is what the renderer draws. The semantic text
index, however, advanced such scalars by the font size, so page geometry
drifted away from the glyphs: on a 22-character Latin line at size 3 mm the
character boxes spread over 63 mm while the drawn text was 28 mm wide, and a
search rectangle for a match late in the line fell to the right of the text it
belonged to. Consumers that draw from this geometry - search highlights,
selection, caret and hit-testing - therefore looked misplaced on any document
whose producers rely on font metrics instead of explicit deltas.

The core crate still does not touch fonts. `TextAdvanceProvider` lets a caller
supply the per-scalar advances, `Document::from_bytes_with_advances` /
`open_with_advances` carry a provider into the page text index, and without one
the previous font-size footprint stays in place (and stays flagged
conservative). rofd-render implements the provider over exactly the resolution
and advance code the positioner uses, exposing the advance each positioned glyph
contributed so the two layers cannot drift apart. rofd-ffi loads documents with
the default font stack, which is what a renderer created with NULL options uses.

The provider is asked only when a run actually declares no `DeltaX`: an
object whose runs all carry their own deltas never loads a font for its
geometry.

Verified: cargo fmt --all -- --check; cargo clippy -p rofd-core -p rofd-render
-p rofd-ffi --all-targets -- -D warnings; cargo test for the three crates;
crates/rofd-ffi/tests/run_c_tests.sh (symbol list, C/C++ headers, smoke). New
tests cover the provider seam in the core builder (including explicit deltas
staying authoritative and a provider that cannot resolve a font), the
provider/positioner agreement on an embedded subset font, and the ABI's layout
and search rectangles following font metrics.
---
 crates/rofd-core/src/document.rs              |  56 +++++++-
 crates/rofd-core/src/lib.rs                   |   4 +-
 crates/rofd-core/src/semantic.rs              |  59 +++++++-
 crates/rofd-core/tests/semantic_text.rs       | 127 +++++++++++++++++-
 crates/rofd-ffi/include/rofd.h                |   5 +
 crates/rofd-ffi/src/document.rs               |   8 +-
 crates/rofd-ffi/src/renderer.rs               |  20 +++
 crates/rofd-ffi/tests/semantic.rs             |  93 +++++++++++++
 crates/rofd-render/src/fonts.rs               |  79 +++++++++--
 crates/rofd-render/src/lib.rs                 |   4 +-
 crates/rofd-render/tests/fonts.rs             |  61 ++++++++-
 ...-09-poppler-style-c-semantic-api-design.md |   8 ++
 12 files changed, 496 insertions(+), 28 deletions(-)

diff --git a/crates/rofd-core/src/document.rs b/crates/rofd-core/src/document.rs
index 7cee168c..0ac4ac65 100644
--- a/crates/rofd-core/src/document.rs
+++ b/crates/rofd-core/src/document.rs
@@ -123,6 +123,19 @@ struct DocumentInner {
     bookmarks: OnceLock<crate::navigation::BookmarkData>,
     bookmark_initialization: Mutex<()>,
     navigation_warning_state: Mutex<NavigationWarningState>,
+    /// Font-resolved per-scalar advances for runs without explicit deltas, when the
+    /// loader supplied a provider (see [`crate::TextAdvanceProvider`]).
+    text_advances: Option<TextAdvances>,
+}
+
+/// Debug-friendly owner of the optional text advance provider.
+#[derive(Clone)]
+struct TextAdvances(Arc<dyn crate::TextAdvanceProvider>);
+
+impl std::fmt::Debug for TextAdvances {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str("TextAdvances(<provider>)")
+    }
 }
 
 #[derive(Debug, Default)]
@@ -233,10 +246,11 @@ impl Page {
     /// physical-page millimetres, in effective paint order.
     ///
     /// Visible annotation appearances follow the page layers. Distinct nonempty
-    /// text objects are separated by synthesized newlines. Geometry uses only
-    /// validated OFD positioning and font size, without font lookup or shaping.
-    /// The complete result is cached and shared by cloned page handles. Failed
-    /// builds are not cached and may be retried on a later call.
+    /// text objects are separated by synthesized newlines. Geometry uses validated
+    /// OFD positioning; a scalar whose run declares no `DeltaX` uses the advance of a
+    /// provider's font when the document was loaded with one, and the font size
+    /// otherwise. The complete result is cached and shared by cloned page handles.
+    /// Failed builds are not cached and may be retried on a later call.
     pub fn text(&self) -> crate::Result<&crate::PageText> {
         if let Some(text) = self.data.semantic_text.get() {
             return Ok(text);
@@ -247,7 +261,12 @@ impl Page {
         if let Some(text) = self.data.semantic_text.get() {
             return Ok(text);
         }
-        let text = crate::semantic::build_page_text(self)?;
+        let advances = self
+            ._document
+            .text_advances
+            .as_ref()
+            .map(|advances| advances.0.as_ref() as &dyn crate::TextAdvanceProvider);
+        let text = crate::semantic::build_page_text(self, advances)?;
         Ok(self.data.semantic_text.get_or_init(|| text))
     }
 
@@ -339,16 +358,40 @@ impl Page {
 impl Document {
     /// Opens an OFD document from a host file path.
     pub fn open(path: impl AsRef<Path>, options: LoadOptions) -> Result<Self> {
+        Self::open_with_advances(path, options, None)
+    }
+
+    /// Opens an OFD document from a host file path, resolving text advances through
+    /// `advances`.
+    pub fn open_with_advances(
+        path: impl AsRef<Path>,
+        options: LoadOptions,
+        advances: Option<Arc<dyn crate::TextAdvanceProvider>>,
+    ) -> Result<Self> {
         let path = path.as_ref();
         let bytes = fs::read(path).map_err(|source| Error::Io {
             path: path.to_owned(),
             source,
         })?;
-        Self::from_bytes(bytes, options)
+        Self::from_bytes_with_advances(bytes, options, advances)
     }
 
     /// Opens an OFD document from owned bytes.
     pub fn from_bytes(bytes: Vec<u8>, options: LoadOptions) -> Result<Self> {
+        Self::from_bytes_with_advances(bytes, options, None)
+    }
+
+    /// Opens an OFD document from owned bytes, resolving text advances through
+    /// `advances`.
+    ///
+    /// Without a provider, runs that carry no explicit `DeltaX` keep the font-size
+    /// footprint; with one they use the font's advances, which is what a renderer
+    /// draws.
+    pub fn from_bytes_with_advances(
+        bytes: Vec<u8>,
+        options: LoadOptions,
+        advances: Option<Arc<dyn crate::TextAdvanceProvider>>,
+    ) -> Result<Self> {
         let strictness = options.strictness;
         let limits = options.limits;
         let container = Container::from_bytes(bytes, limits.clone())?;
@@ -491,6 +534,7 @@ impl Document {
             container,
             document_path,
             limits,
+            text_advances: advances.map(TextAdvances),
             metadata: Metadata {
                 document_id: info.document_id,
                 title: info.title,
diff --git a/crates/rofd-core/src/lib.rs b/crates/rofd-core/src/lib.rs
index 31d3b5ec..027a3440 100644
--- a/crates/rofd-core/src/lib.rs
+++ b/crates/rofd-core/src/lib.rs
@@ -36,8 +36,8 @@ pub use paint::{Color, LineCap, LineJoin, StrokeStyle};
 pub use path_data::{PathCommand, PathData};
 pub use resources::{FontResource, ImageFormat, ImageResource, ResourceIdentity, ResourceKind};
 pub use semantic::{
-    FindOptions, PageText, SelectionStyle, TextChar, TextCharFlags, TextGeometryPrecision,
-    TextMatch, TextSelection,
+    FindOptions, PageText, SelectionStyle, TextAdvanceProvider, TextChar, TextCharFlags,
+    TextGeometryPrecision, TextMatch, TextSelection,
 };
 pub use signature::{SealPicture, SealPictureKind, StampAnnotation};
 pub use text::{CharacterGlyphMap, GlyphTransform, TextCode, TextObject};
diff --git a/crates/rofd-core/src/semantic.rs b/crates/rofd-core/src/semantic.rs
index 8aaf5c8c..592d3f25 100644
--- a/crates/rofd-core/src/semantic.rs
+++ b/crates/rofd-core/src/semantic.rs
@@ -1,6 +1,24 @@
 use std::ops::Range;
 
-use crate::{Error, PageObject, Point, Rect, ResourceLimits, Result, TextObject, Transform};
+use crate::{Error, Page, PageObject, Point, Rect, Result, TextObject, Transform};
+
+/// Supplies the horizontal advance of one scalar when a text run declares no
+/// `DeltaX` for it.
+///
+/// The OFD text model positions such a scalar by its font's advance, so geometry
+/// that resolves fonts matches what a renderer draws; this crate parses and indexes
+/// text without font access, which is why a provider is injected from outside
+/// (`rofd-render` implements it over the same font stack the renderer uses). A
+/// document loaded without a provider keeps the font-size footprint for those runs,
+/// which stays a valid conservative approximation.
+pub trait TextAdvanceProvider: Send + Sync {
+    /// Returns one advance in millimetres per scalar of `text`, concatenating its
+    /// runs in order, or `None` when the object's font cannot be resolved (the
+    /// builder then keeps the font-size footprint).
+    ///
+    /// Non-finite or negative values are ignored per scalar.
+    fn advances_mm(&self, page: &Page, text: &TextObject, size_mm: f64) -> Option<Vec<f64>>;
+}
 
 /// Options for literal search in canonical page text.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -462,8 +480,11 @@ fn union_rectangles(mut rectangles: impl Iterator<Item = Rect>) -> Result<Option
     })
 }
 
-pub(crate) fn build_page_text(page: &crate::Page) -> Result<PageText> {
-    let mut builder = TextBuilder::new(page.resource_limits());
+pub(crate) fn build_page_text(
+    page: &crate::Page,
+    advances: Option<&dyn TextAdvanceProvider>,
+) -> Result<PageText> {
+    let mut builder = TextBuilder::new(page, advances);
     for layer in page.layers() {
         builder.objects(layer.objects(), Transform::IDENTITY)?;
     }
@@ -475,18 +496,23 @@ pub(crate) fn build_page_text(page: &crate::Page) -> Result<PageText> {
     Ok(builder.text)
 }
 
-struct TextBuilder {
+struct TextBuilder<'a> {
     text: PageText,
+    page: &'a Page,
+    advances: Option<&'a dyn TextAdvanceProvider>,
     source_characters: usize,
     metadata_entries: usize,
     max_source_characters: usize,
     max_metadata_entries: usize,
 }
 
-impl TextBuilder {
-    fn new(limits: &ResourceLimits) -> Self {
+impl<'a> TextBuilder<'a> {
+    fn new(page: &'a Page, advances: Option<&'a dyn TextAdvanceProvider>) -> Self {
+        let limits = page.resource_limits();
         Self {
             text: PageText::default(),
+            page,
+            advances,
             source_characters: 0,
             metadata_entries: 0,
             max_source_characters: limits.max_text_characters_per_page,
@@ -526,14 +552,33 @@ impl TextBuilder {
             self.push_separator()?;
         }
         let size = object.font_size();
+        // One font-resolved advance per scalar of the whole object, in run order;
+        // absent when the provider has no font for it. Explicit deltas stay
+        // authoritative and are never replaced, and they are the only thing this
+        // geometry takes from the provider, so an object whose runs all declare their
+        // own deltas never asks it for a font at all.
+        let needs_advances = object.runs().iter().any(|run| !run.has_explicit_delta_x());
+        let resolved = if needs_advances {
+            self.advances
+                .and_then(|advances| advances.advances_mm(self.page, object, size))
+        } else {
+            None
+        };
+        let mut scalar = 0usize;
         for run in object.runs() {
             let (mut x, mut y) = (run.x(), run.y());
             for (index, character) in run.text().chars().enumerate() {
                 let dx = if run.has_explicit_delta_x() {
                     run.delta_x()[index]
                 } else {
-                    size
+                    resolved
+                        .as_ref()
+                        .and_then(|values| values.get(scalar))
+                        .copied()
+                        .filter(|value| value.is_finite() && *value >= 0.0)
+                        .unwrap_or(size)
                 };
+                scalar += 1;
                 let dy = if run.has_explicit_delta_y() {
                     run.delta_y()[index]
                 } else {
diff --git a/crates/rofd-core/tests/semantic_text.rs b/crates/rofd-core/tests/semantic_text.rs
index a6bd53c8..19e23e51 100644
--- a/crates/rofd-core/tests/semantic_text.rs
+++ b/crates/rofd-core/tests/semantic_text.rs
@@ -1,8 +1,10 @@
 mod support;
 
+use std::sync::Arc;
+
 use rofd_core::{
     Document, Error, FindOptions, LoadOptions, Rect, ResourceLimits, SelectionStyle, TextCharFlags,
-    TextGeometryPrecision, TextSelection,
+    TextGeometryPrecision, TextObject, TextSelection,
 };
 
 fn rect(x: f64, y: f64, width: f64, height: f64) -> Rect {
@@ -396,6 +398,129 @@ fn page_with_text(content: &str) -> rofd_core::Page {
     document_with_page(&page_xml, "", "", &[]).page(0).unwrap()
 }
 
+/// A provider that advances every scalar by half the font size, so the geometry it
+/// produces is distinguishable from both the font-size footprint and explicit deltas.
+struct HalfSizeAdvances {
+    resolution_failure: bool,
+}
+
+impl rofd_core::TextAdvanceProvider for HalfSizeAdvances {
+    fn advances_mm(
+        &self,
+        _page: &rofd_core::Page,
+        text: &TextObject,
+        size_mm: f64,
+    ) -> Option<Vec<f64>> {
+        if self.resolution_failure {
+            return None;
+        }
+        Some(
+            text.runs()
+                .iter()
+                .flat_map(|run| run.text().chars().map(|_| size_mm / 2.0))
+                .collect(),
+        )
+    }
+}
+
+fn document_with_page_and_advances(
+    page_xml: &str,
+    advances: Option<Arc<dyn rofd_core::TextAdvanceProvider>>,
+) -> Document {
+    let document_xml = r#"<ofd:Document xmlns:ofd="http://www.ofdspec.org/2016"><ofd:CommonData>
+<ofd:PageArea><ofd:PhysicalBox>0 0 210 297</ofd:PhysicalBox></ofd:PageArea>
+<ofd:PublicRes>Res.xml</ofd:PublicRes></ofd:CommonData>
+<ofd:Pages><ofd:Page ID="900" BaseLoc="Pages/Page_0/Content.xml"/></ofd:Pages></ofd:Document>"#;
+    let entries = [("Doc_0/Res.xml", FONT_CATALOG.as_bytes())];
+    Document::from_bytes_with_advances(
+        support::ofd_with_document_page_and_entries(document_xml, page_xml, &entries),
+        LoadOptions::default(),
+        advances,
+    )
+    .unwrap()
+}
+
+#[test]
+fn advance_provider_supplies_scalar_steps_where_deltas_are_absent() {
+    let page_xml = format!(
+        r#"<?xml version="1.0" encoding="UTF-8"?>
+<ofd:Page xmlns:ofd="http://www.ofdspec.org/2016">
+  <ofd:Content><ofd:Layer ID="1">{}</ofd:Layer></ofd:Content>
+</ofd:Page>"#,
+        text_object(2, "ABCD")
+    );
+
+    let without = document_with_page_and_advances(&page_xml, None)
+        .page(0)
+        .unwrap()
+        .text()
+        .unwrap()
+        .characters()
+        .to_vec();
+    let with = document_with_page_and_advances(
+        &page_xml,
+        Some(Arc::new(HalfSizeAdvances {
+            resolution_failure: false,
+        })),
+    )
+    .page(0)
+    .unwrap()
+    .text()
+    .unwrap()
+    .characters()
+    .to_vec();
+
+    // The fixture places run X at 1 and uses Size 4, so the second scalar starts at
+    // 5 without a provider and at 3 with one, and the same holds for every step.
+    let first = without[0].rect_mm().unwrap();
+    assert_eq!(without[1].rect_mm().unwrap().x - first.x, 4.0);
+    assert_eq!(with[1].rect_mm().unwrap().x - first.x, 2.0);
+    assert_eq!(with[3].rect_mm().unwrap().x - first.x, 6.0);
+    // The footprint stays conservative: every box is at least Size wide.
+    assert!(with[3].rect_mm().unwrap().width >= 4.0);
+
+    // A provider that cannot resolve a font leaves the font-size footprint alone.
+    let failed = document_with_page_and_advances(
+        &page_xml,
+        Some(Arc::new(HalfSizeAdvances {
+            resolution_failure: true,
+        })),
+    )
+    .page(0)
+    .unwrap()
+    .text()
+    .unwrap()
+    .characters()
+    .to_vec();
+    assert_eq!(failed[1].rect_mm().unwrap().x - first.x, 4.0);
+}
+
+#[test]
+fn explicit_deltas_stay_authoritative_with_a_provider() {
+    let page_xml = format!(
+        r#"<?xml version="1.0" encoding="UTF-8"?>
+<ofd:Page xmlns:ofd="http://www.ofdspec.org/2016">
+  <ofd:Content><ofd:Layer ID="1">{}</ofd:Layer></ofd:Content>
+</ofd:Page>"#,
+        r#"<ofd:TextObject ID="2" Boundary="0 0 20 8" Font="10" Size="4"><ofd:TextCode X="1" Y="5" DeltaX="9 9 9 9">ABCD</ofd:TextCode></ofd:TextObject>"#
+    );
+    let text = document_with_page_and_advances(
+        &page_xml,
+        Some(Arc::new(HalfSizeAdvances {
+            resolution_failure: false,
+        })),
+    )
+    .page(0)
+    .unwrap()
+    .text()
+    .unwrap()
+    .characters()
+    .to_vec();
+
+    let first = text[0].rect_mm().unwrap();
+    assert_eq!(text[1].rect_mm().unwrap().x - first.x, 9.0);
+}
+
 #[test]
 fn page_text_exposes_utf8_ranges_source_ids_and_conservative_geometry() {
     const SYNTHESIZED_SEPARATOR_BITS: u32 = TextCharFlags::SYNTHESIZED_SEPARATOR.bits();
diff --git a/crates/rofd-ffi/include/rofd.h b/crates/rofd-ffi/include/rofd.h
index c5830204..1232beb1 100644
--- a/crates/rofd-ffi/include/rofd.h
+++ b/crates/rofd-ffi/include/rofd.h
@@ -584,6 +584,11 @@ void rofd_string_free(rofd_string_t *text);
 /** Return an independently owned immutable snapshot, one entry per Unicode
  * scalar in canonical page text, including synthesized separators. Free with
  * rofd_text_layout_free. The snapshot survives page and document destruction.
+ * A scalar whose run declares no explicit delta is placed by its font's advance,
+ * resolved through the default font stack (the one a renderer created with NULL
+ * options uses); a renderer configured with other fallback families may draw
+ * slightly different advances. Scalars that cannot be resolved fall back to a
+ * conservative font-size box.
  * page and layout are required; error is optional. All outputs must be aligned,
  * writable, mutually disjoint and disjoint from live page storage. */
 rofd_status_t rofd_page_get_text_layout(const rofd_page_t *page,
diff --git a/crates/rofd-ffi/src/document.rs b/crates/rofd-ffi/src/document.rs
index e0407cbf..64ea3cec 100644
--- a/crates/rofd-ffi/src/document.rs
+++ b/crates/rofd-ffi/src/document.rs
@@ -104,7 +104,13 @@ pub unsafe extern "C" fn rofd_document_open(
                 return Err(FfiError::invalid_argument("path is empty"));
             }
             let options = LoadOptionsInput::from_ffi(options)?;
-            let inner = rofd_core::Document::open(path, options).map_err(FfiError::from)?;
+            // Semantic text geometry resolves font advances through the default font
+            // stack, so search/selection rectangles match the rendered glyphs (see
+            // `text_advance_provider`).
+            let advances: std::sync::Arc<dyn rofd_core::TextAdvanceProvider> =
+                std::sync::Arc::new(crate::renderer::text_advance_provider());
+            let inner = rofd_core::Document::open_with_advances(path, options, Some(advances))
+                .map_err(FfiError::from)?;
             Ok(Box::new(DocumentHandle { inner }))
         })
     }
diff --git a/crates/rofd-ffi/src/renderer.rs b/crates/rofd-ffi/src/renderer.rs
index b1cc3a11..44397a7e 100644
--- a/crates/rofd-ffi/src/renderer.rs
+++ b/crates/rofd-ffi/src/renderer.rs
@@ -16,6 +16,7 @@ use rofd_render::{
 use std::ffi::CStr;
 use std::panic::{catch_unwind, AssertUnwindSafe};
 use std::slice;
+use std::sync::OnceLock;
 
 const MAX_FALLBACK_FAMILIES: usize = 1024;
 const DEFAULT_FALLBACK_FAMILIES: [&str; 3] = ["Noto Sans CJK SC", "Noto Sans", "DejaVu Sans"];
@@ -130,6 +131,25 @@ fn default_fallback_families() -> Vec<String> {
         .collect()
 }
 
+/// Font advances for text runs that carry no explicit `DeltaX`.
+///
+/// Semantic page geometry is resolved with the same font stack a default renderer
+/// uses (`rofd_renderer_new` with NULL options), so the page text layout, search
+/// rectangles and selection regions land on the glyphs that get drawn. The resolver
+/// is created once per process and kept for the life of the library, because the
+/// system font database scan is the expensive part. A renderer created with other
+/// fallback families still chooses its own faces for drawing.
+pub(crate) fn text_advance_provider() -> rofd_render::FontTextAdvances<'static> {
+    static RESOLVER: OnceLock<&'static SystemFontResolver> = OnceLock::new();
+    let resolver = RESOLVER.get_or_init(|| {
+        Box::leak(Box::new(SystemFontResolver::with_system_fonts(
+            default_fallback_families(),
+            64 * 1024 * 1024,
+        )))
+    });
+    rofd_render::FontTextAdvances::new(*resolver)
+}
+
 pub(crate) struct RenderOptionsInput;
 
 impl RenderOptionsInput {
diff --git a/crates/rofd-ffi/tests/semantic.rs b/crates/rofd-ffi/tests/semantic.rs
index 38d964c3..636c530e 100644
--- a/crates/rofd-ffi/tests/semantic.rs
+++ b/crates/rofd-ffi/tests/semantic.rs
@@ -45,6 +45,50 @@ fn page_with_layer(layer: &str) -> *mut rofd_page_t {
     }
 }
 
+/// A page whose text object references an embedded subset font and declares no
+/// `DeltaX`, so its geometry can only come from the font's advances.
+fn page_with_embedded_font() -> *mut rofd_page_t {
+    const LATIN_FONT: &[u8] =
+        include_bytes!("../../rofd-render/tests/fixtures/fonts/phase3-latin-subset.ttf");
+    static NEXT: AtomicUsize = AtomicUsize::new(0);
+    // Most Latin scalars in this subset are full-width, so A/B/Z are the ones that
+    // tell a font advance apart from the font-size footprint.
+    let xml = r#"<ofd:Page xmlns:ofd="http://www.ofdspec.org/2016"><ofd:Content><ofd:Layer ID="1"><ofd:TextObject ID="2" Boundary="0 0 30 10" Font="10" Size="4"><ofd:TextCode X="1" Y="4">ABZ</ofd:TextCode></ofd:TextObject></ofd:Layer></ofd:Content></ofd:Page>"#;
+    let document = r#"<ofd:Document xmlns:ofd="http://www.ofdspec.org/2016"><ofd:CommonData><ofd:PageArea><ofd:PhysicalBox>0 0 210 297</ofd:PhysicalBox></ofd:PageArea><ofd:DocumentRes>Res.xml</ofd:DocumentRes></ofd:CommonData><ofd:Pages><ofd:Page ID="900" BaseLoc="Pages/Page_0/Content.xml"/></ofd:Pages></ofd:Document>"#;
+    let font = br#"<ofd:Res xmlns:ofd="http://www.ofdspec.org/2016"><ofd:Fonts><ofd:Font ID="10" FontName="Fixture"><ofd:FontFile>Fonts/latin.ttf</ofd:FontFile></ofd:Font></ofd:Fonts></ofd:Res>"#;
+    let bytes = support::ofd_with_document_page_and_entries(
+        document,
+        xml,
+        &[
+            ("Doc_0/Res.xml", font),
+            ("Doc_0/Fonts/latin.ttf", LATIN_FONT),
+        ],
+    );
+    let path = std::env::temp_dir().join(format!(
+        "rofd-ffi-semantic-font-{}-{}.ofd",
+        std::process::id(),
+        NEXT.fetch_add(1, Ordering::Relaxed)
+    ));
+    std::fs::write(&path, bytes).unwrap();
+    let cpath = CString::new(path.to_str().unwrap()).unwrap();
+    // SAFETY: All input and output storage is valid and distinct; document is freed once.
+    unsafe {
+        let mut document = ptr::null_mut();
+        let mut page = ptr::null_mut();
+        assert_eq!(
+            rofd_document_open(cpath.as_ptr(), ptr::null(), &mut document, ptr::null_mut()),
+            ROFD_STATUS_OK
+        );
+        std::fs::remove_file(path).unwrap();
+        assert_eq!(
+            rofd_document_get_page(document, 0, &mut page, ptr::null_mut()),
+            ROFD_STATUS_OK
+        );
+        rofd_document_free(document);
+        page
+    }
+}
+
 fn page(two_objects: bool) -> *mut rofd_page_t {
     let tail = if two_objects {
         r#"<ofd:TextObject ID="3" Boundary="10 35 30 8" Font="10" Size="4"><ofd:TextCode X="1" Y="5">尾</ofd:TextCode></ofd:TextObject>"#
@@ -921,3 +965,52 @@ fn search_and_selection_accessors_are_transactional() {
         rofd_page_free(page);
     }
 }
+
+/// Page geometry and search rectangles resolve the advances of the font a renderer
+/// would use, instead of the font-size footprint, so they land on the drawn glyphs.
+#[test]
+fn text_geometry_and_search_rectangles_use_font_advances() {
+    // SAFETY: Every handle is live for its accesses and freed once after all borrows.
+    unsafe {
+        let page = page_with_embedded_font();
+        let mut layout = ptr::null_mut();
+        assert_eq!(
+            rofd_page_get_text_layout(page, &mut layout, ptr::null_mut()),
+            ROFD_STATUS_OK
+        );
+        let mut count = 0;
+        assert_eq!(
+            rofd_text_layout_get_count(layout, &mut count, ptr::null_mut()),
+            ROFD_STATUS_OK
+        );
+        assert_eq!(count, 3);
+
+        let a = character(layout, 0);
+        let b = character(layout, 1);
+        let z = character(layout, 2);
+        assert_eq!(a.rect_mm.x_mm, 1.0);
+        // The subset font's own advances: A 2.432 mm, B 2.628 mm, Z 2.412 mm at
+        // size 4. The font-size footprint would step by 4 mm each time.
+        let ab = b.rect_mm.x_mm - a.rect_mm.x_mm;
+        let bz = z.rect_mm.x_mm - b.rect_mm.x_mm;
+        assert!(
+            (ab - 2.432).abs() < 1e-3 && (bz - 2.628).abs() < 1e-3,
+            "advances {ab} and {bz}"
+        );
+        assert!(a.rect_mm.width_mm >= 4.0, "geometry stays conservative");
+
+        // Search rectangles come from the same geometry.
+        let query = CString::new("BZ").unwrap();
+        let mut search = ptr::null_mut();
+        assert_eq!(
+            rofd_page_find_text(page, query.as_ptr(), &mut search, ptr::null_mut()),
+            ROFD_STATUS_OK
+        );
+        assert_eq!(search_count(search), 1);
+        let matched = text_match(search, 0);
+        assert!((matched.rect_mm.x_mm - (1.0 + 2.432)).abs() < 1e-3);
+        rofd_text_search_free(search);
+        rofd_text_layout_free(layout);
+        rofd_page_free(page);
+    }
+}
diff --git a/crates/rofd-render/src/fonts.rs b/crates/rofd-render/src/fonts.rs
index 67876b06..2ce8f211 100644
--- a/crates/rofd-render/src/fonts.rs
+++ b/crates/rofd-render/src/fonts.rs
@@ -4,7 +4,10 @@ use std::sync::{Arc, Condvar, Mutex};
 
 use fontdb::{Database, Family, Query, Source, ID};
 use freetype::face::LoadFlag;
-use rofd_core::{FontResource, ResourceIdentity, ResourceLimits, TextObject, Transform};
+use rofd_core::{
+    FontResource, Page, ResourceIdentity, ResourceLimits, TextAdvanceProvider, TextObject,
+    Transform,
+};
 
 use crate::{Error, Result};
 
@@ -413,6 +416,7 @@ pub struct PositionedGlyph {
     glyph_id: u32,
     x: f64,
     y: f64,
+    advance: (f64, f64),
     character: Option<char>,
     source_range: Range<usize>,
     scalar_index: usize,
@@ -435,6 +439,15 @@ impl PositionedGlyph {
     pub fn y(&self) -> f64 {
         self.y
     }
+    /// Returns the advance this glyph contributes on each axis, in millimetres.
+    ///
+    /// This is the selected face advance, or the font size when no face was
+    /// available. It is what positions the next glyph, so a caller that needs the
+    /// per-scalar geometry of a run without explicit deltas can sum it instead of
+    /// resolving fonts again.
+    pub fn advance(&self) -> (f64, f64) {
+        self.advance
+    }
     /// Returns the associated source scalar, or `None` for an extra mapped glyph.
     pub fn character(&self) -> Option<char> {
         self.character
@@ -1111,10 +1124,12 @@ pub fn position_glyph_runs(
                         let (offset_x, offset_y) = glyph_transform
                             .map(|t| (t.x(), t.y()))
                             .unwrap_or((0.0, 0.0));
+                        let advance = selected.advance_mm(glyph_id, text.font_size())?;
                         glyphs.push(PositionedGlyph {
                             glyph_id,
                             x: finite_coordinate(text, "glyph x", x + inferred_x + offset_x)?,
                             y: finite_coordinate(text, "glyph y", y + inferred_y + offset_y)?,
+                            advance,
                             character,
                             source_range: start_byte..end_byte,
                             scalar_index,
@@ -1123,7 +1138,6 @@ pub fn position_glyph_runs(
                             font_source: selected.source().clone(),
                             transform: glyph_transform.and_then(|t| t.matrix()),
                         });
-                        let advance = selected.advance_mm(glyph_id, text.font_size())?;
                         inferred_x = finite_coordinate(text, "advance x", inferred_x + advance.0)?;
                         inferred_y = finite_coordinate(text, "advance y", inferred_y + advance.1)?;
                     }
@@ -1183,10 +1197,17 @@ pub fn position_glyph_runs(
                 &requested,
                 &mut diagnostics,
             )?;
+            let advance = selection
+                .font
+                .as_ref()
+                .map(|font| font.advance_mm(selection.glyph_id, text.font_size()))
+                .transpose()?
+                .unwrap_or((text.font_size(), 0.0));
             glyphs.push(PositionedGlyph {
                 glyph_id: selection.glyph_id,
                 x: finite_coordinate(text, "glyph x", x)?,
                 y: finite_coordinate(text, "glyph y", y)?,
+                advance,
                 character: Some(character),
                 source_range: byte_start..byte_end,
                 scalar_index,
@@ -1195,12 +1216,6 @@ pub fn position_glyph_runs(
                 font_source: selection.source,
                 transform: None,
             });
-            let advance = selection
-                .font
-                .as_ref()
-                .map(|font| font.advance_mm(selection.glyph_id, text.font_size()))
-                .transpose()?
-                .unwrap_or((text.font_size(), 0.0));
             let delta_x = if run.has_explicit_delta_x() {
                 run.delta_x()[local]
             } else {
@@ -1229,6 +1244,54 @@ pub fn position_glyph_runs(
     Ok(runs)
 }
 
+/// Per-scalar advances from the same font resolution the renderer positions text with.
+///
+/// This is the [`TextAdvanceProvider`] rofd-core asks for when a text run carries no
+/// explicit `DeltaX`: the answer is the advance of the glyph the positioner selected,
+/// summed per scalar for structured `Glyphs` mappings, so page geometry matches the
+/// rendered glyphs. Resolution failures answer `None`, which keeps rofd-core's
+/// font-size footprint.
+#[derive(Clone, Copy)]
+pub struct FontTextAdvances<'a> {
+    resolver: &'a dyn FontResolver,
+}
+
+impl<'a> FontTextAdvances<'a> {
+    /// Wraps the resolver a renderer would use for the same page.
+    pub fn new(resolver: &'a dyn FontResolver) -> Self {
+        Self { resolver }
+    }
+}
+
+impl TextAdvanceProvider for FontTextAdvances<'_> {
+    fn advances_mm(&self, page: &Page, text: &TextObject, size_mm: f64) -> Option<Vec<f64>> {
+        let resource = page.font_resource(text.font_id()).ok()?;
+        let runs =
+            position_glyph_runs(self.resolver, &resource, text, page.resource_limits()).ok()?;
+        let total = text.runs().iter().try_fold(0usize, |total, run| {
+            total.checked_add(run.text().chars().count())
+        })?;
+        // Glyphs of one structured mapping share the scalar index of the mapped
+        // range, so their advances sum there, exactly as the positioner advances the
+        // mapped run. A scalar without a glyph keeps the size footprint the builder
+        // uses on its own.
+        let mut advances: Vec<Option<f64>> = vec![None; total];
+        for run in &runs {
+            for glyph in run.glyphs() {
+                let slot = advances.get_mut(glyph.scalar_index())?;
+                let (x, _) = glyph.advance();
+                *slot = Some(slot.unwrap_or(0.0) + x);
+            }
+        }
+        Some(
+            advances
+                .into_iter()
+                .map(|advance| advance.unwrap_or(size_mm))
+                .collect(),
+        )
+    }
+}
+
 fn select_character(
     resolver: &dyn FontResolver,
     primary: Option<&ResolvedFont>,
diff --git a/crates/rofd-render/src/lib.rs b/crates/rofd-render/src/lib.rs
index 5cca515a..53375744 100644
--- a/crates/rofd-render/src/lib.rs
+++ b/crates/rofd-render/src/lib.rs
@@ -19,8 +19,8 @@ pub use display_list::{
     ClipPath, Command, DisplayList, DisplayListBuilder, RenderDiagnostic, RenderDiagnosticKind,
 };
 pub use fonts::{
-    position_glyph_runs, FontDiagnostic, FontIdentity, FontResolver, FontSource, GlyphRun,
-    PositionedGlyph, ResolvedFont, SystemFontResolver,
+    position_glyph_runs, FontDiagnostic, FontIdentity, FontResolver, FontSource, FontTextAdvances,
+    GlyphRun, PositionedGlyph, ResolvedFont, SystemFontResolver,
 };
 pub use images::{DecodedImage, ImageDecoder};
 
diff --git a/crates/rofd-render/tests/fonts.rs b/crates/rofd-render/tests/fonts.rs
index bc5838da..d95e8ce1 100644
--- a/crates/rofd-render/tests/fonts.rs
+++ b/crates/rofd-render/tests/fonts.rs
@@ -4,7 +4,7 @@ use std::sync::Arc;
 use std::thread;
 
 use fontdb::Database;
-use rofd_core::{Document, LoadOptions, PageObject, ResourceLimits};
+use rofd_core::{Document, LoadOptions, PageObject, ResourceLimits, TextAdvanceProvider};
 use rofd_render::{
     position_glyph_runs, Error, FontDiagnostic, FontIdentity, FontResolver, FontSource,
     ResolvedFont, SystemFontResolver,
@@ -853,3 +853,62 @@ fn equal_resource_ids_from_distinct_documents_do_not_share_cache_entries() {
         cjk[0].glyphs()[0].glyph_id()
     );
 }
+
+/// The provider rofd-core asks for must answer exactly the advances the positioner
+/// used, so page geometry lands on the glyphs a renderer draws.
+#[test]
+fn font_text_advances_match_the_positioner_and_follow_font_metrics() {
+    // A, B and Z carry proportional advances in the fixture subset; most other
+    // Latin scalars map to a full-width face advance equal to the font size, which
+    // would not distinguish metrics from the size-based fallback.
+    let document = package_named(
+        Some(LATIN_FONT),
+        r#"<ofd:TextCode X="0" Y="4">ABZ</ofd:TextCode>"#,
+        "",
+        "Fixture",
+    );
+    let text = text_object(&document);
+    let page = document.page(0).unwrap();
+    let resource = document.font_resource(text.font_id()).unwrap();
+    let mut database = Database::new();
+    database.load_font_data(LATIN_FONT.to_vec());
+    let resolver = SystemFontResolver::from_database(database, Vec::new(), 1 << 20);
+
+    let runs = position_glyph_runs(&resolver, &resource, &text, page.resource_limits()).unwrap();
+    let provider = rofd_render::FontTextAdvances::new(&resolver);
+    let advances = provider
+        .advances_mm(&page, &text, text.font_size())
+        .expect("embedded font resolves");
+
+    assert!(
+        !runs[0].glyphs()[0].is_synthetic_box(),
+        "the subset font must own these glyphs: {:?}",
+        runs[0].diagnostics()
+    );
+
+    // One advance per scalar, equal to the advance of the glyph that owns it.
+    let positioned: Vec<f64> = runs
+        .iter()
+        .flat_map(|run| run.glyphs())
+        .map(|glyph| glyph.advance().0)
+        .collect();
+    assert_eq!(advances.len(), positioned.len());
+    assert_eq!(advances.len(), 3);
+    for (index, advance) in advances.iter().enumerate() {
+        assert!(
+            (advance - positioned[index]).abs() < 1e-9,
+            "scalar {index}: provider {advance} vs positioner {}",
+            positioned[index]
+        );
+    }
+
+    // Font metrics, not a uniform font-size footprint.
+    assert!(advances[0] < advances[1], "{advances:?}");
+    assert!(advances.iter().all(|advance| *advance < text.font_size()));
+    assert!(advances.iter().all(|advance| *advance > 0.0));
+
+    // Both layers agree on where the run ends.
+    let semantic_end: f64 = advances.iter().sum();
+    let positioned_end: f64 = positioned.iter().sum();
+    assert!((semantic_end - positioned_end).abs() < 1e-9);
+}
diff --git a/docs/superpowers/specs/2026-09-09-poppler-style-c-semantic-api-design.md b/docs/superpowers/specs/2026-09-09-poppler-style-c-semantic-api-design.md
index 475ce6bc..3448607c 100644
--- a/docs/superpowers/specs/2026-09-09-poppler-style-c-semantic-api-design.md
+++ b/docs/superpowers/specs/2026-09-09-poppler-style-c-semantic-api-design.md
@@ -90,6 +90,14 @@ Where OFD data cannot yield an exact glyph box, the API returns a conservative
 finite character box and records its precision in flags instead of pretending
 font-derived accuracy.
 
+A run that declares no delta for a scalar is positioned by its font's advance, so
+the core builder accepts an optional `TextAdvanceProvider` that answers those
+advances without pulling fonts into the core crate: `rofd-render` implements it
+over the same font resolution the renderer positions text with, and `rofd-ffi`
+loads documents with the default font stack so the ABI's rectangles land on the
+glyphs a default renderer draws. Without a provider the builder keeps the
+font-size footprint, and scalars it cannot resolve stay flagged as conservative.
+
 Reading order is deterministic. It starts with effective paint/source order,
 then groups compatible characters into lines using writing direction and
 geometry. Stable source order breaks geometric ties. Whitespace from the OFD

From f0572f2950948c8c77da5b356cca06db21549df9 Mon Sep 17 00:00:00 2001
From: Yangtse Su <yangtsesu@gmail.com>
Date: Thu, 15 Oct 2026 02:15:58 +0800
Subject: [PATCH 2/2] feat(core): size a resolved glyph box by its advance, not
 the font size

The conservative footprint (at least one font size per scalar) exists so a
font-free build still produces usable hit boxes. With a provider that footprint
is no longer needed: it made every box wider than its glyph, so the boxes of a
run overlapped and a match rectangle overhung its text by a fraction of a glyph -
visible as a search highlight that extends past the match into the next letter.
Measured on a 3 mm Latin line: the "on" match box was 4.82 mm wide against a
3.65 mm advance span, and the single-glyph boxes overlapped by 1.25 mm.

A scalar whose advance the provider resolved now gets exactly that advance as its
box width, so the boxes tile the run and the rectangles hug the matched text.
Scalars the provider cannot resolve, and builds without a provider, keep the
font-size footprint (an explicit zero advance still gets a nonempty box).

Verified: cargo fmt --all -- --check; cargo clippy -p rofd-core -p rofd-render
-p rofd-ffi --all-targets -- -D warnings; cargo test for the three crates (the
core and FFI tests now assert the advance width and that adjacent boxes meet);
crates/rofd-ffi/tests/run_c_tests.sh.
---
 crates/rofd-core/src/semantic.rs        | 23 ++++++++++++++---------
 crates/rofd-core/tests/semantic_text.rs |  8 ++++++--
 crates/rofd-ffi/tests/semantic.rs       |  9 ++++++++-
 3 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/crates/rofd-core/src/semantic.rs b/crates/rofd-core/src/semantic.rs
index 592d3f25..c7ee1959 100644
--- a/crates/rofd-core/src/semantic.rs
+++ b/crates/rofd-core/src/semantic.rs
@@ -568,15 +568,15 @@ impl<'a> TextBuilder<'a> {
         for run in object.runs() {
             let (mut x, mut y) = (run.x(), run.y());
             for (index, character) in run.text().chars().enumerate() {
+                let font_advance = resolved
+                    .as_ref()
+                    .and_then(|values| values.get(scalar))
+                    .copied()
+                    .filter(|value| value.is_finite() && *value > 0.0);
                 let dx = if run.has_explicit_delta_x() {
                     run.delta_x()[index]
                 } else {
-                    resolved
-                        .as_ref()
-                        .and_then(|values| values.get(scalar))
-                        .copied()
-                        .filter(|value| value.is_finite() && *value >= 0.0)
-                        .unwrap_or(size)
+                    font_advance.unwrap_or(size)
                 };
                 scalar += 1;
                 let dy = if run.has_explicit_delta_y() {
@@ -586,11 +586,16 @@ impl<'a> TextBuilder<'a> {
                 };
                 let next_x = finite_add(x, dx)?;
                 let next_y = finite_add(y, dy)?;
-                // Bound the horizontal baseline sweep with a direction-independent
-                // font-size footprint. Explicit zero advances still receive
+                // A resolved glyph advance is the box width, so the boxes of a run
+                // tile it and a match rectangle hugs the matched text. Without one,
+                // bound the horizontal baseline sweep with a direction-independent
+                // font-size footprint instead; explicit zero advances still receive
                 // nonempty conservative geometry.
                 let left = x.min(next_x);
-                let right = finite_add(left, dx.abs().max(size))?;
+                let right = finite_add(
+                    left,
+                    font_advance.map_or_else(|| dx.abs().max(size), f64::abs),
+                )?;
                 let top = finite_add(y.min(next_y), -size)?;
                 let bottom = y.max(next_y);
                 let rect = transformed_box(left, top, right, bottom, transform)?;
diff --git a/crates/rofd-core/tests/semantic_text.rs b/crates/rofd-core/tests/semantic_text.rs
index 19e23e51..ee3f300d 100644
--- a/crates/rofd-core/tests/semantic_text.rs
+++ b/crates/rofd-core/tests/semantic_text.rs
@@ -476,8 +476,12 @@ fn advance_provider_supplies_scalar_steps_where_deltas_are_absent() {
     assert_eq!(without[1].rect_mm().unwrap().x - first.x, 4.0);
     assert_eq!(with[1].rect_mm().unwrap().x - first.x, 2.0);
     assert_eq!(with[3].rect_mm().unwrap().x - first.x, 6.0);
-    // The footprint stays conservative: every box is at least Size wide.
-    assert!(with[3].rect_mm().unwrap().width >= 4.0);
+    // A resolved advance is the box width (so the boxes tile the run), while an
+    // unresolved scalar keeps the conservative font-size footprint.
+    assert!((with[3].rect_mm().unwrap().width - 2.0).abs() < 1e-9);
+    assert!(without[3].rect_mm().unwrap().width >= 4.0);
+    let first_end = with[0].rect_mm().unwrap().x + with[0].rect_mm().unwrap().width;
+    assert!((first_end - with[1].rect_mm().unwrap().x).abs() < 1e-9);
 
     // A provider that cannot resolve a font leaves the font-size footprint alone.
     let failed = document_with_page_and_advances(
diff --git a/crates/rofd-ffi/tests/semantic.rs b/crates/rofd-ffi/tests/semantic.rs
index 636c530e..086a2543 100644
--- a/crates/rofd-ffi/tests/semantic.rs
+++ b/crates/rofd-ffi/tests/semantic.rs
@@ -997,7 +997,14 @@ fn text_geometry_and_search_rectangles_use_font_advances() {
             (ab - 2.432).abs() < 1e-3 && (bz - 2.628).abs() < 1e-3,
             "advances {ab} and {bz}"
         );
-        assert!(a.rect_mm.width_mm >= 4.0, "geometry stays conservative");
+        // A resolved advance is the box width, so the boxes tile the run: a match
+        // rectangle then hugs the matched text instead of overhanging it.
+        assert!(
+            (a.rect_mm.width_mm - 2.432).abs() < 1e-3,
+            "width {}",
+            a.rect_mm.width_mm
+        );
+        assert!((a.rect_mm.x_mm + a.rect_mm.width_mm - b.rect_mm.x_mm).abs() < 1e-9);
 
         // Search rectangles come from the same geometry.
         let query = CString::new("BZ").unwrap();