# pdftract-1x2: StructTree depth-first walker + /RoleMap resolution

## Summary

Implemented the depth-first walker over the PDF structure tree (/StructTreeRoot) with complete /RoleMap resolution support. This is Phase 7.1.1 of the plan.

## Implementation

### Files Modified/Created
- `crates/pdftract-core/src/parser/struct_tree.rs` (new, 1215 lines)
- `crates/pdftract-core/src/parser/mod.rs` (added exports)

### Core Types
- `StructureType`: Enum covering all 40+ PDF 1.7 standard structure types (Document, Part, Art, Sect, Div, P, H1..H6, Table, Figure, etc.)
- `Kid`: Enum for /K array entries (Element, Mcid, Mcr, ObjRef)
- `StructElemNode`: Tree node with resolved type, inherited lang/actual_text, and children
- `StructTreeRoot`: Root container with kids array and RoleMap
- `RoleMap`: Mapping from non-standard to standard types with chain resolution

### Key Features
1. **Depth-first traversal** via /K array handling all four entry types:
   - StructElem dictionary (recursive)
   - Integer MCID (direct marked content reference)
   - MCR dictionary (marked content reference with explicit page)
   - OBJR dictionary (annotation/XObject reference)

2. **RoleMap resolution** with:
   - Chain following (A -> B -> H1)
   - Cycle detection (A -> B -> A → NonStruct with diagnostic)
   - Standard type detection (no lookup needed for "P", "H1", etc.)

3. **Attribute inheritance**:
   - /Lang inherits from parent if not present on node
   - /ActualText inherits from parent (overrides all descendant glyph text)
   - /Alt (alternative text) extracted per-node
   - /ID, /T, /E, /Pg also extracted

## Verification

### Unit Tests (17 tests, all PASS)
```
test parser::struct_tree::tests::test_structure_type_from_name ... ok
test parser::struct_tree::tests::test_structure_type_is_heading ... ok
test parser::struct_tree::tests::test_structure_type_heading_level ... ok
test parser::struct_tree::tests::test_role_map_parse ... ok
test parser::struct_tree::tests::test_role_map_resolve ... ok
test parser::struct_tree::tests::test_role_map_chaining ... ok
test parser::struct_tree::tests::test_role_map_cycle_detection ... ok
test parser::struct_tree::tests::test_role_map_self_mapping ... ok
test parser::struct_tree::tests::test_struct_elem_node_new ... ok
test parser::struct_tree::tests::test_struct_tree_root_new ... ok
test parser::struct_tree::tests::test_struct_tree_root_default ... ok
test parser::struct_tree::tests::test_struct_tree_word_rolemap_integration ... ok
test parser::struct_tree::tests::test_struct_tree_lang_inheritance ... ok
test parser::struct_tree::tests::test_struct_tree_actual_text_scope ... ok
test parser::struct_tree::tests::test_struct_tree_mcr_kid ... ok
test parser::struct_tree::tests::test_struct_tree_objr_kid ... ok
test parser::struct_tree::tests::test_struct_tree_mcid_kid ... ok
```

### Acceptance Criteria Status
- ✓ Walker handles all four /K element kinds (Element, MCID, MCR, OBJR) without crashing
- ✓ /RoleMap chains resolve to a standard type or NonStruct
- ✓ /Lang and /ActualText inherit correctly down the tree
- ✓ Unit tests: fixtures with Word RoleMap (Heading1 -> H1)
- ✓ Unit tests: nested /Lang, /ActualText scope
- ✓ Public type StructElemNode is documented in the core crate

## Commit
- Commit: `d41d47d`
- Message: `feat(pdftract-1x2): implement StructTree depth-first walker with RoleMap resolution`

## Retrospective

### What worked
- The implementation followed the PDF 1.7 spec closely, with clear separation between parsing and type resolution
- Test-driven approach worked well - each kid type, RoleMap feature, and inheritance pattern has dedicated tests
- Using `indexmap::IndexMap` for RoleMap preserves insertion order while providing O(1) lookups

### What didn't
- Initial compilation error: mismatched types in match arms when resolving RoleMap references. Fixed by restructuring the error handling to assign to `root.role_map` directly rather than trying to return `RoleMap::new()` from a `PdfObject`-returning match.

### Surprise
- The RoleMap can map to another non-standard name (chains), not directly to standard types. This required recursive resolution with cycle detection.

### Reusable pattern
- For recursive type resolution through a mapping: track visited keys in a HashSet, emit diagnostic on cycle, return a safe fallback type.
- For inheritance in tree walkers: pass inherited values as `Option<&str>` to recursive calls, use `node.lang = lang.or_else(|| parent_lang.map(|s| s.to_string()))` to prefer local over inherited.

## References
- Plan section 7.1 StructTree Exploitation (lines 2547-2549, 2552-2553)
- PDF 1.7 spec §14.7.4 (Structure Tree) and §14.8.4 (Standard Structure Types)