feat(bindings): expose TextItem.mcid and structure-tree element extraction (#346)

Tagged PDFs carry a structure tree with real heading roles (H1..H6), and
the core already parses it (structure_tree::StructTree) and threads MCIDs
onto TextItem — but neither surfaced through the bindings.

- Expose TextItem.mcid (Option<i64>) through the napi and pyo3 bindings,
  matching the core field added with the marked-content extractor.
- Add StructRole::name(), the inverse of from_name, so roles have a
  stable string form.
- Add extract_structure_elements / extract_structure_elements_mem to the
  core: one (page, mcid, role) entry per marked-content reference, sorted
  by (page, mcid), empty for untagged PDFs. Pages are 1-indexed to match
  TextItem.page, so results join directly against
  extract_text_with_positions output.
- Bind it as extractStructureElements (napi) and
  extract_structure_elements / extract_structure_elements_bytes (pyo3),
  with type-stub updates in pdf_inspector.pyi.
- Cover the join in Rust integration tests, napi test.mjs, and pytest,
  using the existing firecrawl_docs_tagged.pdf fixture (tagged) and
  thermo-freon12.pdf (untagged).

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

napi/src/lib.rs

@@ -89,6 +89,11 @@ pub struct TextItem {
     pub item_type: ItemType,
     /// URL for link items, `None` for other types.
     pub link_url: Option<String>,
+    /// Marked Content ID from the content stream's BDC/BMC operator, `None`
+    /// when the text is not part of marked content. Join with the
+    /// `page`/`mcid` pairs from [`extractStructureElements`] to attach
+    /// structure-tree roles (headings, paragraphs, …) in tagged PDFs.
+    pub mcid: Option<i64>,
 }
 
 /// A page's regions for text extraction: (page_index_0based, bboxes).
@@ -306,12 +311,61 @@ pub fn extract_text_with_positions(
                     is_strikeout: item.is_strikeout,
                     item_type,
                     link_url,
+                    mcid: item.mcid,
                 }
             })
             .collect())
     })
 }
 
+/// One structure-tree element reference from a tagged PDF.
+#[napi(object)]
+pub struct StructureElementJs {
+    /// 1-indexed page number (matches `TextItem.page`).
+    pub page: u32,
+    /// Marked Content ID from the page's content stream (matches
+    /// `TextItem.mcid`).
+    pub mcid: i64,
+    /// Standard structure type name ("H1".."H6", "P", "Table", "TD", …).
+    /// Custom tags are resolved through the document's role map; tags with
+    /// no standard mapping are returned verbatim.
+    pub role: String,
+}
+
+/// Extract structure-tree element references from a tagged PDF.
+///
+/// Parses the document's structure tree (when present) and returns one
+/// entry per marked-content reference, resolved to its 1-indexed page,
+/// MCID, and structure type name. Returns an empty array when the PDF is
+/// not tagged.
+///
+/// Join `(page, mcid)` against the `page`/`mcid` fields from
+/// [`extractTextWithPositions`] to attach heading levels (H1..H6) and other
+/// semantic roles to extracted text.
+///
+/// Pass 1-indexed page numbers (matching `TextItem.page`) to restrict
+/// output; omit `pages` for the whole document. Entries are sorted by
+/// `(page, mcid)`.
+#[napi]
+pub fn extract_structure_elements(
+    buffer: Buffer,
+    pages: Option<Vec<u32>>,
+) -> Result<Vec<StructureElementJs>> {
+    let bytes: Vec<u8> = buffer.to_vec();
+    catch_panic("extract_structure_elements", move || {
+        let elements = pdf_inspector::extract_structure_elements_mem(&bytes, pages.as_deref())
+            .map_err(|e| to_napi_err(e, "extract_structure_elements"))?;
+        Ok(elements
+            .into_iter()
+            .map(|e| StructureElementJs {
+                page: e.page,
+                mcid: e.mcid,
+                role: e.role,
+            })
+            .collect())
+    })
+}
+
 /// Extract text within bounding-box regions from a PDF.
 ///
 /// For hybrid OCR: layout model detects regions in rendered images,

napi/test.mjs

@@ -8,6 +8,7 @@ import {
   classifyPdfAsync,
   extractText,
   extractTextWithPositions,
+  extractStructureElements,
   extractTextInRegions,
   detectVectorGridInRegion,
   extractPagesMarkdown,
@@ -15,6 +16,7 @@ import {
 } from './index.js';
 
 const fixture = readFileSync('../tests/fixtures/thermo-freon12.pdf');
+const taggedFixture = readFileSync('../tests/fixtures/firecrawl_docs_tagged.pdf');
 
 // --- processPdf ---
 console.log('Testing processPdf...');
@@ -82,6 +84,46 @@ assert.ok(page1Items.length > 0);
 assert.ok(page1Items.every(i => i.page === 1));
 console.log('  extractTextWithPositions with pages: OK');
 
+// mcid: undefined on untagged PDFs, numeric on tagged marked content
+assert.ok(items.every(i => i.mcid === undefined || typeof i.mcid === 'number'));
+const taggedItems = extractTextWithPositions(taggedFixture);
+assert.ok(
+  taggedItems.some(i => typeof i.mcid === 'number'),
+  'tagged PDF text items should carry Marked Content IDs',
+);
+console.log('  extractTextWithPositions mcid: OK');
+
+// --- extractStructureElements ---
+console.log('Testing extractStructureElements...');
+const structureElements = extractStructureElements(taggedFixture);
+assert.ok(structureElements.length > 0);
+assert.ok(structureElements.every(e => typeof e.page === 'number'));
+assert.ok(structureElements.every(e => typeof e.mcid === 'number'));
+assert.ok(structureElements.every(e => typeof e.role === 'string' && e.role.length > 0));
+assert.ok(
+  structureElements.some(e => e.role === 'H1'),
+  'tagged fixture should surface H1 heading roles',
+);
+
+// (page, mcid) joins against extractTextWithPositions to recover heading text
+const h1Refs = new Set(
+  structureElements.filter(e => e.role === 'H1').map(e => `${e.page}:${e.mcid}`),
+);
+const h1Text = taggedItems
+  .filter(i => typeof i.mcid === 'number' && h1Refs.has(`${i.page}:${i.mcid}`))
+  .map(i => i.text)
+  .join('');
+assert.ok(h1Text.trim().length > 0, 'H1 join should recover heading text');
+
+// pages filter is 1-indexed, matching TextItem.page
+const page1Elements = extractStructureElements(taggedFixture, [1]);
+assert.ok(page1Elements.length > 0);
+assert.ok(page1Elements.every(e => e.page === 1));
+
+// untagged PDFs yield an empty array
+assert.deepEqual(extractStructureElements(fixture), []);
+console.log('  extractStructureElements: OK');
+
 // --- extractTextInRegions ---
 console.log('Testing extractTextInRegions...');
 const regionResults = extractTextInRegions(fixture, [