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/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, [