rpdfium 0.4.1

data/CHANGELOG.md

@@ -0,0 +1,1870 @@
+# Changelog
+
+Tutte le modifiche notevoli a questo progetto.
+Il formato segue [Keep a Changelog](https://keepachangelog.com/it/1.1.0/).
+
+## [0.4.1] - 2026-05-26
+
+### Corretto
+
+- **Caricamento su Linux con `rpdfium-binary`**: `rpdfium.rb` ora esegue
+  `require "rpdfium/binary"` prima di `raw.rb`. In precedenza `ffi_lib`
+  veniva chiamato prima che `Rpdfium::Binary` fosse definito, causando
+  un fallback ai nomi di sistema (`pdfium`, `libpdfium.so`) e un
+  `LoadError` su ambienti senza PDFium installato globalmente.
+
+## [0.4.0] - refactor verso primitive componibili
+
+### ⚠️ Breaking changes
+
+`Page#label_value_pairs` torna a essere una **primitiva minimale**:
+ritorna `Array<Hash>` con pair grezzi senza opzioni di merging
+applicativo. Le opzioni `merge_adjacent:`, `as_hash:`, `boxed_layout:`
+sono **rimosse** (erano logica di dominio incollata sulla primitiva
+di estrazione).
+
+Per chi usava queste opzioni:
+- `merge_adjacent: :smart` → componi a mano con `Util::WordMerger`
+- `as_hash: true` → converti il risultato nel chiamante
+- `boxed_layout: true` → passa direttamente `x_tolerance: 15.0,
+  inject_spaces: false` + crea `LabelMatcher.new(row_max_dx: 400.0)`
+
+Gli **adapter applicativi specifici** per moduli AE (Modello 770,
+Comunicazione IVA) sono ora forniti come **esempi esterni** in
+`examples/adapters/` (vedi sotto), non come parte della gem.
+
+### Aggiunto: `Util::WordMerger`
+
+Primitiva di merging configurabile, con tre strategie esplicite:
+
+```ruby
+merger = Rpdfium::Util::WordMerger.new(x_gap: 20.0, y_tol: 3.0)
+
+# Fonde tutte le word adiacenti
+merger.merge_by_proximity(words)
+
+# Fonde solo word con stessa label (mapping word → label fornito dal chiamante)
+merger.merge_by_label(words, labels_by_word)
+
+# Fonde solo word con label nil (orfane)
+merger.merge_unlabeled(words, labels_by_word)
+```
+
+### Aggiunto: `Util::ColumnInference`
+
+Primitiva di inferenza di colonne dati su PDF non-tabellari (form
+prestampati, layout con valori allineati per posizione ma senza
+linee). Algoritmo in 3 passi:
+
+1. Cluster per coordinata X (x0 left-align O x1 right-align)
+2. Spezza per gap verticali anomali
+3. Filtra per densità (coefficiente di variazione dei gap)
+
+```ruby
+inference = Rpdfium::Util::ColumnInference.new(
+  x_tolerance: 3.0,     # tolleranza cluster X
+  min_size: 3,          # almeno 3 valori per colonna
+  cv_threshold: 0.15    # gap regolari
+)
+
+columns = inference.infer(words)
+# => [[word1, word2, ...], [word1, word2, ...]]
+```
+
+### `Util::LabelMatcher` ora compone con `ColumnInference`
+
+```ruby
+# Senza riassegnazione (comportamento 0.3.15)
+matcher = Rpdfium::Util::LabelMatcher.new
+
+# Con riassegnazione per colonne ripetitive (ex repeat_headers)
+matcher = Rpdfium::Util::LabelMatcher.new(
+  column_inference: Rpdfium::Util::ColumnInference.new
+)
+```
+
+Il flag `repeat_headers:` non esiste più — si passa direttamente un
+oggetto `ColumnInference` configurato (o `nil` per disabilitare).
+
+### Adapter applicativi (esempi esterni)
+
+Distribuiti in `examples/adapters/`, NON parte della gem. Mostrano
+come comporre le primitive per casi specifici:
+
+- **`Modello770Reader`** (per Dichiarazione sostituti d'imposta)
+- **`LiquidazioneIVAReader`** (per Comunicazione Liquidazioni IVA)
+
+Ognuno è uno script Ruby standalone con classe ~100 righe. Da
+copiare nel proprio progetto e adattare se serve.
+
+### Filosofia
+
+La gem rpdfium fornisce primitive generaliste per leggere PDF. La
+**logica applicativa specifica per un modulo** (sapere che il 770 ha
+Quadro ST/SV/SX, che l'IVA ha caselline a cifre singole con virgola
+graficamente dipinta) appartiene al **codice del consumatore**, non
+alla gem.
+
+Le primitive `WordMerger`, `ColumnInference`, `LabelMatcher` sono
+**componibili**: ogni caso d'uso compone una pipeline specifica.
+
+### Non-regressione
+
+✅ Tutti i test core passano. F24, busta_paga, cu.pdf, complex,
+sample invariati. Le primitive nuove sono testate con assert
+dedicati.
+
+### Migration guide da 0.3.19
+
+```ruby
+# Prima (0.3.19):
+page.label_value_pairs(
+  data_font: "Courier",
+  merge_adjacent: :smart,
+  as_hash: true
+)
+
+# Dopo (0.4.0): usa l'adapter Modello770Reader (vedi examples/) o
+# componi a mano:
+matcher = Rpdfium::Util::LabelMatcher.new(
+  column_inference: Rpdfium::Util::ColumnInference.new
+)
+pairs = page.label_value_pairs(data_font: "Courier", matcher: matcher)
+# poi merge custom + hash conversion nel tuo codice
+```
+
+## [0.3.19] - estrazione su moduli a caselline (boxed_layout)
+
+### Aggiunto: `label_value_pairs(boxed_layout: true)`
+
+Alcuni moduli prestampati italiani (Comunicazione Liquidazioni
+Periodiche IVA, Modello Redditi quadri specifici) hanno un layout a
+**caselline separate per ogni cifra**: la partita IVA `01234567890`
+viene stampata come 11 caselline, l'importo `15.357,78` viene scritto
+come `15.357 7 8` con la parte intera, la virgola dipinta dal template,
+e le 2 cifre decimali in caselle ciascuna a ~10pt di distanza.
+
+Il default `label_value_pairs` non riconosceva questi numeri come
+singoli valori: spezzava `15.357,78` in 3 word separate (`15.357`, `7`,
+`8`) perché PDFium inseriva automaticamente uno spazio "generato" tra
+le caselline (gap > 5pt → trattato come separatore di parole).
+
+### Soluzione: flag `boxed_layout: true`
+
+Configura automaticamente i parametri adatti:
+
+- **`inject_spaces: false`** sui char (no spazi PDFium-generated
+  che spezzano le caselline)
+- **`x_tolerance: 15.0`** (gap tipico tra caselline ~10-13pt)
+- **`row_max_dx: 400.0`** sul LabelMatcher (le label sui moduli VP
+  sono a sinistra e i valori in colonna DEBITI/CREDITI sono a 250+pt
+  di distanza)
+
+```ruby
+Rpdfium.open("iva.pdf") do |doc|
+  doc.page(1).label_value_pairs(
+    data_font: "Helvetica",
+    merge_adjacent: :smart,
+    as_hash: true,
+    boxed_layout: true        # ← nuova opzione
+  )
+end
+```
+
+### Risultato sul modulo IVA — Pagina 2 (Quadro VP)
+
+**Prima (0.3.18)**:
+
+```ruby
+{
+  "CODICE FISCALE" => "0 2 0 9",                # spezzato per le caselline
+  "Operazioni straordinarie" => "5.455 8",      # label sbagliata, numero spezzato
+  "," => ["2", "1"],                             # virgola del template come label
+  "IVA esigibile" => "3.378 7 2",               # spezzato
+  "CREDITI" => "1.132 7",                       # label è il sub-header, non semantica
+  ...
+}
+```
+
+**Adesso (0.3.19) con `boxed_layout: true`**:
+
+```ruby
+{
+  "CODICE FISCALE" => "01234567890",                              # ✓
+  "Mod. N." => "01",                                              # ✓
+  "PERIODO DI RIFERIMENTO" => "04",                               # mese aprile
+  "VP2 Totale operazioni attive (al netto dell'IVA)" => "15.35778",   # € 15.357,78
+  "VP3 Totale operazioni passive (al netto dell'IVA)" => "5.45582",   # € 5.455,82
+  "VP4 IVA esigibile" => "3.37872",                                   # € 3.378,72
+  "VP5 IVA detratta" => "1.13271",                                    # € 1.132,71
+  "VP6 IVA dovuta" => "2.24601",                                      # € 2.246,01
+  "VP14 IVA da versare" => "2.24601"                                  # € 2.246,01
+}
+```
+
+I valori numerici sono concatenati senza virgola decimale (la virgola
+è grafica nel template, non parte del data layer). Il consumatore può
+formatterla con post-processing: gli ultimi 2 caratteri sono i
+decimali, il resto è la parte intera.
+
+```ruby
+def parse_eur_amount(s)
+  s.match(/\A(.*)(\d{2})\z/) { |m| "#{m[1]},#{m[2]}" }
+end
+parse_eur_amount("15.35778")  # => "15.357,78"
+parse_eur_amount("2.24601")   # => "2.246,01"
+```
+
+### Quando usarlo
+
+Attiva `boxed_layout: true` quando il modulo presenta:
+- Codici fiscali / partite IVA con cifre in caselline visibili
+- Importi con virgola decimale grafica e caselle per ogni cifra
+- Date in formato GG MM AAAA con caselle separate
+- Generalmente: PDF Agenzia delle Entrate con sfondo a celle
+
+Lascia il default `false` per:
+- F24 stampato (Courier compatto senza caselle)
+- Modello 770 quadri ST/SV (testo libero compatto)
+- Buste paga / cedolini con tabelle standard
+- Tutti i casi dove i char sono già contigui
+
+### Non-regressione
+
+✅ 15/15 test passano. Il default `boxed_layout: false` mantiene il
+comportamento 0.3.18 byte-per-byte.
+
+### API compatibility
+
+Nessuna breaking change. Puoi passare `inject_spaces:`, `x_tolerance:`
+e altri kwargs separatamente per controllo fine, oppure usare la
+combinazione `boxed_layout: true` come scorciatoia.
+
+## [0.3.18] - propagazione intestazioni su tabelle ripetitive
+
+### Fixato: intestazioni di colonna non propagate alle righe successive
+
+Su moduli con **tabelle ripetitive** (Quadro ST/SV del 770, sezioni
+Erario/INPS/Regioni di F24 multi-riga, ecc.) le intestazioni di
+colonna sono stampate **una sola volta** in cima alla tabella e
+sottintese per tutte le righe successive (ST2, ST3, ..., ST13).
+
+Nelle versioni precedenti `label_value_pairs` limitava il matching
+label→valore a `col_max_dy=80pt`: bastava per la prima riga (ST2) ma
+le righe successive (oltre 80pt dall'header) finivano sotto label
+sbagliate o spurie (es. `ST5: [04 2021, 455,46]` invece di
+`Periodo di riferimento: 04 2021` + `Importo versato: 455,46`).
+
+### Soluzione: pass di riassegnazione per colonne
+
+Il `LabelMatcher` ora ha una terza fase **`reassign_by_columns`**:
+
+1. **Identifica le colonne dati**: clustera i valori per coordinata
+   `x0` (left-aligned, es. codici tributo) **e** `x1` (right-aligned,
+   es. importi numerici "1.227,70" e "499,81" hanno x0 diversi ma x1
+   uguale). I valori sui moduli prestampati sono spesso allineati a
+   destra; servono entrambi gli allineamenti per coprire tutti i casi.
+
+2. **Spezza colonne per gap verticali**: se due valori consecutivi
+   nello stesso x-cluster hanno un gap verticale > 3× la mediana dei
+   gap (o > 40pt), li separa in colonne distinte. Risolve casi tipo
+   "codice fiscale in alto pagina + tabella sotto" che condividono
+   la stessa x ma sono sezioni distinte.
+
+3. **Filtra per densità**: una colonna "vera" di tabella ripetitiva
+   ha valori regolarmente equispaziati. Misura il coefficiente di
+   variazione dei gap (`CV = std_dev/mean`). Soglia stretta: `CV <
+   0.15` (spacing molto regolare). Esclude falsi positivi come i 5
+   saldi del F24 right-aligned (SALDO A-B, C-D, E-F, G-H, M-N: stessa
+   x1 ma sezioni diverse, CV = 0.26).
+
+4. **Trova l'header canonico**: per ogni colonna dati identificata,
+   cerca la label di template **subito sopra** il `col_top` (il top
+   del primo valore della colonna). Quella label è l'intestazione
+   canonica.
+
+5. **Propaga**: assegna l'header canonico a TUTTI i valori della
+   colonna, anche quelli oltre `col_max_dy` dall'header originale.
+
+### Risultato sul 770 Quadro ST
+
+Pagina 4 prima (0.3.17):
+
+```ruby
+{
+  "Periodo di riferimento mese anno" => "01 2021",
+  "Ritenute operate" => "394,13",   # solo ST2
+  "Importo versato" => "394,13",
+  "Codice tributo 11" => ["1001", "443,73", "1001", "405,96"],  # mescolato
+  "ST5" => ["04 2021", "455,46"],    # label spuria
+  "ST6" => ["05 2021", "407,40"],
+  "ST7" => ["06 2021", "1.227,70"],
+  # ...
+  "ST13" => ["12 2021", "32,46"]
+}
+```
+
+Adesso (0.3.18):
+
+```ruby
+{
+  "Periodo di riferimento mese anno" => [
+    "01 2021", "02 2021", "03 2021", "04 2021", "05 2021", "06 2021",
+    "07 2021", "08 2021", "09 2021", "10 2021", "11 2021", "12 2021"
+  ],
+  "Ritenute operate" => [
+    "394,13", "443,73", "405,96", "455,46", "407,40", "1.227,70",
+    "367,74", "520,00", "463,37", "451,32", "499,81", "32,46"
+  ],
+  "Importo versato" => [...stessi 12 importi...],
+  "Codice tributo 11" => ["1001", "1001", ..., "1001", "1712"],  # 12 codici
+  "Data di versamento giorno mese anno 14" => [
+    "16 02 2021", "16 03 2021", ..., "16 12 2021"
+  ]
+  # NO più label spurie ST5/ST7/ST13
+}
+```
+
+### Parametri configurabili
+
+`Rpdfium::Util::LabelMatcher.new` accetta tre nuovi parametri:
+
+- `repeat_headers:` (default `true`) — attiva/disattiva la
+  riassegnazione per colonne. Passa `false` per ripristinare il
+  comportamento 0.3.17.
+- `column_x_tolerance:` (default `3.0`) — tolleranza X per
+  considerare due valori "in stessa colonna".
+- `min_column_size:` (default `3`) — numero minimo di valori per
+  riconoscere una colonna come ripetitiva.
+
+```ruby
+matcher = Rpdfium::Util::LabelMatcher.new(
+  repeat_headers: true,
+  column_x_tolerance: 2.0,    # cluster più stretto
+  min_column_size: 5           # solo colonne con 5+ righe
+)
+page.label_value_pairs(data_font: "Courier", matcher: matcher, ...)
+```
+
+### Non-regressione
+
+✅ 15/15 test passano:
+- busta_paga, cu.pdf rotation 90°, sample, complex
+- F24 499,81 → "importi a debito versati"
+- F24 1.615,90 → "SALDO (M-N) +/–" (saldo finale, non confuso coi
+  saldi di sezione SALDO A-B / C-D)
+- F24 532,27 → "importi a debito versati" (TOTALE A)
+- 770 p2 "Cognome o Denominazione" → "Azienda S.R.L."
+- 770 p4 12 codici tributo + 12 importi + 12 date + 12 mesi
+- 770 p4 NO label spurie ST5/ST13
+- 770 p4 CODICE FISCALE → solo il singolo codice (non l'intera colonna)
+
+### API compatibility
+
+Nessuna breaking change. `repeat_headers: false` ripristina il
+comportamento 0.3.17 per chi preferisce.
+
+## [0.3.17] - precisione label-value su moduli a colonne strette
+
+### Fixato: valori "wide" attraversano label sbagliate
+
+Su moduli prestampati con colonne template strette adiacenti (caso
+classico: 770 pagina 2 con "Cognome o Denominazione" / "Nome" /
+"Dichiarazione integrativa" / "Protocollo dichiarazione inviata"
+disposte sulla stessa riga), un valore che semanticamente appartiene
+al primo campo ma che si estende graficamente oltre il suo box
+(es. "Azienda S.R.L." scritto su tutta la riga) veniva spezzato in
+3 entry sotto label diverse.
+
+`Page#label_value_pairs(merge_adjacent: :smart, ...)` ora:
+
+1. **Tight-merge passo finale**: dopo i passaggi by_label e
+   by_proximity esistenti, un terzo passo unisce le word con gap
+   orizzontale ≤ 10pt e stessa riga esatta (top differiscono di <1pt)
+   anche se cadono sotto label di colonna diverse. La soglia è
+   inferiore al gap inter-colonna tipico (>15pt) ma maggiore del
+   kerning intra-word (<5pt), così si riconoscono solo stringhe
+   "naturalmente unite".
+
+2. **Label per wide values usa left-edge**: il `LabelMatcher` ora,
+   per valori più larghi di 60pt (tipico di stringhe merged), cerca
+   la label di colonna usando il **left edge** del valore (con piccolo
+   offset di 5pt) invece del midpoint. Così una denominazione che
+   inizia sotto "Cognome o Denominazione" mantiene quella label anche
+   se si estende oltre.
+
+Risultato sul 770 pagina 2:
+
+```ruby
+# Prima (0.3.16):
+{
+  "Cognome o Denominazione" => "Azienda",         # spezzata
+  "Dichiarazione integrativa" => "CONSULTING",       # sbagliata
+  "Protocollo dichiarazione inviata" => "S.R.L."     # sbagliata
+}
+
+# Adesso (0.3.17):
+{
+  "Cognome o Denominazione" => "Azienda S.R.L."  # ✓
+}
+```
+
+I tre passaggi sono configurabili separatamente:
+- `merge_x_gap:` (default 20.0) — gap by_label e by_proximity
+- `merge_tight_x_gap:` (default 10.0) — gap del tight-merge
+
+### Fixato: marcatori grafici di colonna catturati come label
+
+Su Quadro ST/SV del 770, il template stampa numerini "11", "14", "15",
+"16" come marcatori grafici delle colonne (indici delle posizioni nel
+form). Venivano catturati come label semantiche del LabelMatcher,
+producendo entry inutili come `"16" => ["443,73", "405,96", ...]`.
+
+`Util::LabelMatcher` ora ignora di default le label che matchano
+`/\A\d{1,3}\z|\A[IVX]{1,5}\z/` — numeri brevi e numeri romani brevi,
+tipici marcatori di colonna. Configurabile via
+`LabelMatcher.new(ignore_label_pattern: ...)`. Passa `nil` per
+disattivare il filtro, o una propria Regexp per pattern custom.
+
+Default:
+
+```ruby
+matcher = Rpdfium::Util::LabelMatcher.new
+# ignore_label_pattern: /\A\d{1,3}\z|\A[IVX]{1,5}\z/
+
+matcher = Rpdfium::Util::LabelMatcher.new(ignore_label_pattern: nil)
+# nessun filtro, comportamento 0.3.16
+
+matcher = Rpdfium::Util::LabelMatcher.new(ignore_label_pattern: /\AXX\z/)
+# filtro custom
+```
+
+### Risultato finale sul 770
+
+Confronto pagine principali prima/dopo:
+
+| Pagina | Prima (0.3.16) | Adesso (0.3.17) |
+| --- | --- | --- |
+| 2 | "Cognome": "Azienda" + 2 entry sbagliate | "Cognome o Denominazione": "Azienda S.R.L." |
+| 4 (Quadro ST) | "16": [443,73, 405,96, ...] (marcatore) | "Sospensione COVID Importo sospeso": [...] (label vera) |
+| 4 | "14": [16, 16, 17, ...] (marcatore) | "Data di versamento giorno mese anno": [16 02 2021, ...] |
+| 4 | "11": [1001, 443,73, ...] (marcatore) | "Codice tributo": [1001, ...] (label vera) |
+
+### Non-regressione
+
+✅ 16/16 test passano (busta_paga, F24, cu.pdf rotation 90°, cu.pdf
+small font, sample, complex, e tutti i nuovi assert su 770).
+
+### API compatibility
+
+Nessuna breaking change. I parametri nuovi (`merge_tight_x_gap`,
+`ignore_label_pattern`) hanno default sensati. Disattivare il filtro
+con `ignore_label_pattern: nil` ripristina il comportamento 0.3.16.
+
+## [0.3.16] - estrazione strutturata su moduli multi-pagina
+
+### Aggiunto: `label_value_pairs(merge_adjacent:, as_hash:)`
+
+Due nuove opzioni a `Page#label_value_pairs` che trasformano l'output da
+"lista di pair grezza" a **mappa strutturata `{label => valore}` pronta
+da consumare**, gestendo correttamente sia campi puntuali (checkbox,
+codici) che testo libero multi-word (denominazioni, indirizzi, header).
+
+### `merge_adjacent` — 3 strategie selezionabili
+
+- **`false` (default)**: nessuna unione. Una word PDF = una entry.
+  Comportamento 0.3.15.
+
+- **`true` o `:by_label`**: fonde solo word adiacenti con la **stessa
+  label col**. Conserva checkbox sotto label distinte (es. su 770 le
+  X dei quadri compilati ST/SV/SX restano separate perché ognuna ha
+  la sua label).
+
+- **`:by_proximity`**: fonde tutte le word adiacenti indipendentemente
+  dalla label. Per header con testo libero (es. "Soggetto: Azienda
+  S.R.L. ( 01234567890 )" diventa una entry sola).
+
+- **`:smart` (raccomandato per moduli complessi)**: combina i due —
+  by_label per word con label, by_proximity per word **orfane** senza
+  label. Funziona automaticamente su moduli che mescolano header
+  testuali (Soggetto), tabelle con checkbox (ST/SV/SX) e campi singoli
+  (codice fiscale, codice attività).
+
+### `as_hash: true` — output strutturato
+
+Trasforma `Array<Hash>` in `Hash` chiavi-valore:
+
+```ruby
+Rpdfium.open("770.pdf") do |doc|
+  doc.page(1).label_value_pairs(
+    data_font: "Courier",
+    merge_adjacent: :smart,
+    as_hash: true
+  )
+end
+
+# => {
+#   "Codice fiscale" => "01234567890",
+#   "Codice attività" => "999999",
+#   "Indirizzo di posta elettronica/PEC" => "AZIENDA@PEC.IT",
+#   "Stato (tab. SA)" => "1",
+#   "Situazione (tab. SC)" => "6",
+#   "ST" => "X",
+#   "SV" => "X",
+#   "SX" => "X",
+#   "Dipendente" => "X",
+#   "Tipologia invio" => "2",
+#   ...
+# }
+```
+
+Quando la label è la stessa per più valori, l'output diventa un Array:
+`"Codice fiscale" => ["01234567890", "01234567890"]`.
+
+Le word senza label associabile (es. header in alto pagina senza
+template di riferimento) confluiscono sotto la chiave `"_unlabeled"`
+come Array di stringhe.
+
+### Esempio: estrazione completa di un Modello 770
+
+```ruby
+Rpdfium.open("770.pdf") do |doc|
+  doc.each_with_index do |page, i|
+    inv = page.font_inventory
+    data_font = inv.find { |g| g[:font]&.match?(/courier/i) }&.dig(:font)
+    next unless data_font
+
+    h = page.label_value_pairs(
+      data_font: data_font,
+      merge_adjacent: :smart,
+      as_hash: true
+    )
+    puts "=== Pagina #{i + 1} ==="
+    h.each { |k, v| puts "  #{k}: #{v.inspect}" }
+  end
+end
+```
+
+Output reale su modello 770 (3 prime pagine):
+
+```
+=== Pagina 1 ===
+  _unlabeled: ["Soggetto: Azienda S.R.L. ( 01234567890 )",
+               "Identificativo dichiarazione: 11111111111 - 0000002 del 22/10/2022"]
+
+=== Pagina 2 ===
+  Codice fiscale: ["01234567890", "01234567890"]
+  Codice attività: "999999"
+  Indirizzo di posta elettronica/PEC: "AZIENDA@PEC.IT"
+  Stato (tab. SA): "1"
+  Situazione (tab. SC): "6"
+  ST: "X"
+  SV: "X"
+  SX: "X"
+  Dipendente: "X"
+  Tipologia invio: "2"
+  GESTIONE SEPARATA Dipendente Autonomo: "X"
+
+=== Pagina 3 ===
+  Codice fiscale: "01234567890"
+  Codice fiscale dell'incaricato: "01877150696"
+  giorno mese: "01 10"
+  anno: "2022"
+  _unlabeled: ["2", "Firma Presente"]
+```
+
+### `merge_x_gap` per tarare il merge
+
+Parametro `merge_x_gap:` controlla il gap massimo (in punti) tra word
+adiacenti per essere considerate "unite". Default 20.0. Aumentalo per
+moduli con campi molto spaziati (header centrati su pagina).
+
+### Heuristica `best_label_for` (interna)
+
+Quando il valore ha sia `col` che `row` label, la scelta automatica
+preferisce:
+- `row` se è una label breve identificatrice ("ST", "Codice fiscale")
+- `col` quando è più descrittiva ("importi a debito versati")
+
+Per controllo fine, usa la API base senza `as_hash: true` e leggi
+direttamente `p[:labels][:col]` e `p[:labels][:row]`.
+
+### Non-regressione
+
+✅ busta_paga.pdf, cu.pdf p1, cu.pdf p199, sample, complex, F24, IVA
+— tutti i test invariati.
+
+✅ Il default di `merge_adjacent: false` mantiene il comportamento
+0.3.15 byte-per-byte. La 0.3.16 è purely additiva.
+
+### API compatibility
+
+Nessuna breaking change.
+
+## [0.3.15] - associazione label-valore su moduli compilati
+
+### Aggiunto: `Page#label_value_pairs` e `Util::LabelMatcher`
+
+Su PDF di "moduli compilati" (F24, comunicazioni IVA, modelli 770,
+dichiarazioni dei redditi) le 3 API introdotte nella 0.3.14
+(`font_inventory`, `chars_where`, `lines`) permettono di **separare**
+il layer template dai dati. La 0.3.15 va oltre: **associa
+semanticamente** ogni valore inserito alla sua etichetta nel template,
+così l'utente non deve sapere a priori la geometria del modulo.
+
+### Come funziona
+
+L'algoritmo opera in tre step:
+
+1. **Cluster del template in label coerenti** — parole del modello
+   geometricamente vicine (stessa riga adiacenti, o righe successive
+   sovrapposte in x) vengono unite in un'unica label. Esempio:
+   "importi", "a", "debito", "versati" → label unica `"importi a
+   debito versati"`.
+
+2. **Per ogni valore inserito, cerca due tipi di label**:
+   - `col` — label SOPRA nella stessa colonna (x sovrapposto col
+     valore, bottom < value top, scelta la più vicina verticalmente).
+     Ruolo tipico: nome del campo/colonna.
+   - `row` — label A SINISTRA nella stessa riga (y sovrapposto, x1 <
+     value x0, scelta la più vicina orizzontalmente). Ruolo tipico:
+     identificatore di riga ("TOTALE A", "SALDO").
+
+3. **Ritorna** una mappatura `{ value:, labels: { col:, row: }, geometry: }`
+   per ogni valore.
+
+### Esempio: F24
+
+```ruby
+Rpdfium.open("f24.pdf") do |doc|
+  page = doc.page(0)
+  pairs = page.label_value_pairs(
+    data_font: "Courier",
+    template_font: /^Futura/,
+    data_filter: ->(t) { t.match?(/^[\d.,]+$/) }
+  )
+  pairs.each do |p|
+    puts "#{p[:value]} → col: #{p[:labels][:col]}, row: #{p[:labels][:row]}"
+  end
+end
+```
+
+Output:
+
+```
+499,81    → col: "importi a debito versati"
+0,00      → col: "importi a credito compensati"
+1001      → col: "codice tributo"
+2021      → col: "anno di riferimento"
+532,27    → col: "importi a debito versati", row: "A"     (TOTALE A)
+236,38    → col: "SALDO (A-B) +/–",          row: "B"
+1.253,00  → col: "importi a debito versati"               (sezione INPS)
+1.341,00  → col: "SALDO (C-D) +/–",          row: "D"
+1.615,90  → col: "SALDO (M-N) +/–",          row: "EURO +"   (saldo finale)
+```
+
+### Esempio: Modello 770 Quadro ST
+
+```ruby
+Rpdfium.open("770.pdf") do |doc|
+  doc.page(3).label_value_pairs(
+    data_font: "Courier",
+    data_filter: ->(t) { t.match?(/^[\d.,]+$/) }
+  )
+end
+# 394,13 → col: "Ritenute operate"
+# 394,13 → col: "Importo versato"
+# 1001   → col: "Codice tributo"
+# 16     → col: "Data di versamento giorno mese anno"
+```
+
+### `Util::LabelMatcher` come classe autonoma
+
+Per casi avanzati (es. matching su un sottoinsieme di pagina, con
+soglie tarate, o riusato su più pagine) la logica è esposta come
+classe separata:
+
+```ruby
+matcher = Rpdfium::Util::LabelMatcher.new(
+  col_max_dy: 50.0,           # max distanza label sopra -> valore
+  row_max_dx: 150.0,          # max distanza label sinistra -> valore
+  col_x_tolerance: 5.0,       # overlap x richiesto per label "sopra"
+  row_y_tolerance: 1.0,       # overlap y richiesto per label "sinistra"
+  cluster_same_row_dy: 4.0,   # tolleranza cluster word stessa riga
+  cluster_same_row_dx: 12.0,
+  cluster_adj_row_dy: 4.0     # tolleranza cluster word righe adiacenti
+)
+
+data_words = Rpdfium::Util::WordExtractor.new.extract_words(page.chars_where(font: "Courier"))
+anchor_words = Rpdfium::Util::WordExtractor.new.extract_words(page.chars_where(font: /^Futura/))
+
+pairs = matcher.match(data_words, anchor_words)
+
+# Bonus: ispeziona quali label il matcher costruisce
+labels = matcher.cluster_anchors(anchor_words)
+```
+
+### Limitazioni note
+
+- **Caselline separate per cifre**: su moduli con campi tipo codice
+  fiscale o numeri italiani spezzati su caselle separate
+  (`0 2 0 9 8 1 2 0 6 8 2`, `15.357 , 7 8`) il word extractor non
+  unisce le cifre. Aumentare `x_tolerance` aiuta, ma è tradeoff: il
+  fix definitivo richiede post-elaborazione consumer-side.
+- **Label troppo larghe**: a volte il cluster unisce label adiacenti
+  che sarebbero meglio distinte. Le soglie default funzionano sulla
+  maggior parte dei moduli italiani Agenzia delle Entrate/INPS; per
+  layout diversi tara i parametri di `LabelMatcher`.
+- **Label "abbondanti"**: per valori molto vicini al margine, le label
+  trovate sono ovvie ma poco informative. Filtrare i pair per
+  `data_filter` selettivo aiuta (esempio: solo numeri con virgola).
+
+### Non-regressione
+
+✅ busta_paga.pdf, cu.pdf p1, cu.pdf p199, sample, complex — tutti
+i test invariati.
+
+### API compatibility
+
+Nessuna breaking change. Le API 0.3.14 (`font_inventory`,
+`chars_where`, `lines`) restano invariate. `Util::LabelMatcher` è
+una nuova classe additiva.
+
+## [0.3.14] - estrazione form-aware tramite font filtering
+
+### Aggiunto: `Page#font_inventory`, `Page#chars_where`, `Page#lines`
+
+Tre nuove API per estrarre dati da PDF di "moduli compilati" — F24,
+comunicazioni IVA, modelli 770, dichiarazioni dei redditi e in generale
+qualsiasi PDF di output da gestionali in cui il template grafico del
+modulo e i dati inseriti dall'utente coesistono come testo statico
+(nessun AcroForm, nessun tag PDF/UA).
+
+Su questi PDF il pipeline `Table::Extractor` produce molto rumore
+perché vede il modulo intero (etichette del template + dati) come una
+griglia di tabelle. La soluzione semantica è separare i char per
+"ruolo" usando il font/altezza: tipicamente il template usa font
+proporzionali (Futura, Helvetica, Times) mentre i dati inseriti dal
+gestionale usano un singolo font (di solito Courier o Helvetica a una
+size specifica).
+
+### `Page#font_inventory`
+
+Distribuzione dei char per `(font, altezza, weight)`, ordinata per
+count decrescente. Utile per scoprire empiricamente quale font usano
+i dati su un modulo sconosciuto:
+
+```ruby
+page.font_inventory.first(5).each do |g|
+  puts "#{g[:font].ljust(20)} h=#{g[:height]} w=#{g[:weight]} | #{g[:count]} char | #{g[:sample][0,40]}"
+end
+# Futura-Light          h=8.3   w=225  |   946 char | "cognome, denominazione o ragione sociale"
+# Courier               h=10.5  w=0    |   365 char | "01234567890Azienda S.R.L.P"
+# Futura-Bold           h=10.4  w=868  |   249 char | "CODICE FISCALEDATI ANAGRAFICIDOMICILIO F"
+# Futura-Light          h=8.9   w=225  |   194 char | "PROV.CODICE BANCA/POSTE/AGENTE DELLA RIS"
+# Futura-Bold           h=11.7  w=868  |   169 char | "CONTRIBUENTESEZIONE ERARIOSEZIONE INPSSE"
+```
+
+`height` è l'altezza visiva del char in punti (più affidabile di
+`fontsize` che PDFium normalizza a 1.0 quando la dimensione reale è
+nella matrice CTM, caso frequente sui moduli scalati).
+
+### `Page#chars_where(font:, height:, weight:, bbox:, where:)`
+
+Filtro generico sui char. Tutti i parametri sono opzionali e
+combinabili in AND:
+
+- `font:` String esatto, Array di String, o Regexp
+- `height:` Float (con tolleranza 0.1pt), Range, o Array
+- `weight:` Integer o Range
+- `bbox:` `[left, top, right, bottom]` in coord top-down
+- `where:` block per filtri arbitrari
+
+```ruby
+data_chars = page.chars_where(font: "Courier")
+# oppure
+data_chars = page.chars_where(font: /courier/i, height: 8.0..12.0)
+# oppure con bbox
+sezione_erario = page.chars_where(font: "Courier", bbox: [0, 250, 595, 400])
+```
+
+### `Page#lines(font:, ...)`
+
+Helper di alto livello che combina `chars_where` + WordExtractor +
+clustering per riga. Ritorna un Array di stringhe, una per riga
+(top-to-bottom, char dentro la riga left-to-right):
+
+```ruby
+# F24
+Rpdfium.open("f24.pdf") do |doc|
+  doc.page(0).lines(font: "Courier")
+end
+# => [
+#   "Soggetto:  Azienda  S.R.L.  ( 01234567890 )",
+#   "0  1  2  3  4  5  6  7  8  9  0",
+#   "Azienda  S.R.L.",
+#   "CITTA  XX  VIA  ESEMPIO  1",
+#   "1001  11  2021  499,81  0,00",
+#   "1712  12  2021  32,46  0,00",
+#   "1701  11  2021  0,00  295,89",
+#   "532,27  295,89  236,38",
+#   "1900  DM10  9999999999  11  2021  1.253,00  0,00",
+#   ...
+#   "1.615,90"
+# ]
+```
+
+Funziona ugualmente bene su:
+- **F24**: codici tributo, importi a debito/credito, sezioni separate
+- **Comunicazione IVA**: importi del Quadro VP (operazioni attive/passive,
+  IVA esigibile/detratta, dovuta/credito)
+- **Modello 770**: ritenute mese per mese con codici tributo e date di
+  versamento
+- **Dichiarazione redditi (SP, PF, SC)**: dati anagrafici e quadri
+
+### Tradeoff e limitazioni
+
+`Page#lines` ritorna righe **leggibili**, non già strutturate. Su
+moduli con caselle separate per cifra (es. il codice fiscale `0 2 0 9
+8 1 2 0 6 8 2`, o numeri italiani con casella decimali separata
+`15.357,78` → `15.357 7 8`), i gap visivi tra caselline superano
+`x_tolerance` di default e le righe risultano "spaziate". Soluzioni:
+
+1. Aumentare `x_tolerance` per quei filtri specifici (es. 8.0)
+2. Post-elaborare le righe per riconoscere il pattern del modulo
+   (specifico per ogni modello)
+
+La libreria fornisce le primitive composable; l'interpretazione del
+modulo specifico resta al chiamante perché ogni modello ha layout
+diverso.
+
+### Non-regressione
+
+✅ busta_paga.pdf: `1.993,00`, `COGNOME E NOME`, `NETTO BUSTA`
+✅ cu.pdf p1 rotation 90°: `BANCA NAZIONALE`, `Categoria`
+✅ cu.pdf p199 small font: `Categoria` (no `iCategora`)
+✅ sample.pdf, complex.pdf
+
+### API compatibility
+
+Nessuna breaking change. Le tre nuove API sono additive. Il pipeline
+`Table::Extractor` esistente continua a funzionare invariato per chi
+ha tabelle "vere" con bordi.
+
+## [0.3.13] - `Page#struct_tree`: struttura semantica dei PDF tagged
+
+### Aggiunto: lettura del PDF Structure Tree
+
+Nuova API `Page#struct_tree` che espone la struttura logica dei PDF
+tagged (PDF/UA, esport accessibility-friendly da Word/LibreOffice/InDesign).
+
+Per documenti tagged offre un accesso al contenuto **completamente
+indipendente dalla geometria**: per ogni element del tree è possibile
+sapere il suo tipo strutturale (`P`, `H1`, `Table`, `TR`, `TH`, `TD`,
+`Figure`, ecc.), il testo che lo compone, gli attributi PDF strutturali
+e i collegamenti via Marked Content ID al contenuto della pagina.
+
+### Esempio: estrazione tabella zero-geometria
+
+```ruby
+page.struct_tree do |tree|
+  tree.tables.each do |table|
+    rows = table.children.select { |c| c.type == "TR" }
+    rows.each do |row|
+      cells = row.children.select { |c| c.type == "TH" || c.type == "TD" }
+      texts = cells.map(&:text).map(&:strip)
+      puts texts.inspect
+    end
+  end
+end
+# → ["Region", "Revenue", "Growth"]      (TH — riga header)
+# → ["Italy", "1.250.000", "+12%"]       (TD — riga dati)
+# → ["France", "980.000", "+8%"]
+# → ["Germany", "2.100.000", "+15%"]
+```
+
+Vantaggi rispetto al pipeline geometrico `Table::Extractor`:
+
+- distingue header (`TH`) da data (`TD`) — info che il pipeline
+  geometrico perde
+- funziona su tabelle **senza linee** (text-only) o con linee parziali
+- riconosce row/col span via `<TD>.attributes` (`RowSpan`, `ColSpan`)
+- zero euristica di clustering
+
+Limitazione: richiede PDF tagged. La maggior parte dei PDF da gestionali
+italiani (TeamSystem, Zucchetti, banche italiane) NON sono tagged. Per
+quelli il pipeline geometrico esistente resta l'unica strada.
+
+### API completa
+
+```ruby
+tree = page.struct_tree     # → Tree o nil
+tree.empty?                 # true se il tree è strutturalmente vuoto
+tree.roots                  # → [Element, ...] root del tree (di solito 1 "Document")
+tree.walk { |el| ... }      # itera depth-first
+tree.walk.to_a              # Enumerator
+tree.find_all(type: "P")    # filter by type
+tree.tables                 # shortcut per find_all(type: "Table")
+
+element.type                # "P", "Table", "TR", "TD", ...
+element.children            # → [Element, ...]
+element.parent              # → Element o nil
+element.text                # ricostruisce testo da MCID + ActualText
+element.actual_text         # /ActualText attribute (override per legature, math)
+element.alt_text            # /Alt (per Figure/Formula)
+element.lang                # "it-IT", "en-US", ecc.
+element.marked_content_ids  # → [Integer]
+element.attributes          # → { name => value } (RowSpan, ColSpan, ...)
+element.walk { |el| ... }   # depth-first del sub-tree
+element.leaves              # foglie (elements senza children)
+```
+
+### Lifecycle
+
+Il tree è "owning" — chiamare `FPDF_StructTree_Close` lo dealloca.
+
+- **Lifecycle implicito (zero-config)**: non chiudere mai esplicitamente.
+  PDFium dealloca il tree alla chiusura del documento. Il tree resta in
+  memoria fino a quel momento (può essere ~MB su PDF grossi, ma niente
+  perdita persistente).
+- **Lifecycle deterministico**: usa il blocco
+  `page.struct_tree do |tree| ... end`. All'uscita dal blocco il tree
+  viene chiuso, anche in caso di eccezione.
+
+**Scelta progettuale**: non usiamo `ObjectSpace.define_finalizer` per il
+tree. Il documento può essere chiuso prima del tree (es. dentro un
+blocco `Rpdfium.open do |doc| ... end`), e il finalizer GC chiamerebbe
+`FPDF_StructTree_Close` su memoria già liberata → use-after-free →
+segfault. Lasciare la cleanup al `FPDF_CloseDocument` è sempre sicuro;
+la cleanup esplicita tramite `tree.close` o blocco è sicura purché il
+documento sia ancora vivo.
+
+### 24 binding C-level mancanti aggiunti
+
+Oltre agli 8 binding di base (già presenti):
+
+- `FPDF_StructElement_GetParent`, `GetID`, `GetLang`, `GetObjType`
+- `FPDF_StructElement_GetActualText`, `GetAltText`, `GetExpansion`
+- `FPDF_StructElement_GetMarkedContentID`, `GetMarkedContentIdCount`,
+  `GetMarkedContentIdAtIndex`, `GetChildMarkedContentID`
+- `FPDF_StructElement_GetAttributeCount`, `GetAttributeAtIndex`,
+  `GetStringAttribute`
+- `FPDF_StructElement_Attr_GetCount`, `GetName`, `GetValue`, `GetType`,
+  `GetBooleanValue`, `GetNumberValue`, `GetStringValue`, `GetBlobValue`,
+  `CountChildren`, `GetChildAtIndex`
+
+Tutte esposte via `Rpdfium::Raw.FPDF_*` per chi vuole bypassare i
+wrapper.
+
+### Tre stati possibili di `page.struct_tree`
+
+| Caso | `page.struct_tree` ritorna |
+| --- | --- |
+| PDF non tagged | `nil` |
+| PDF tagged ma vuoto (es. CR Banca d'Italia, 717 placeholder) | Tree con `empty? == true` |
+| PDF tagged correttamente (Word/LibreOffice export) | Tree navigabile |
+
+Verificato sui 4 PDF di test: busta_paga/sample/complex → nil; cu.pdf
+p1 → empty; PDF generato via `soffice --convert-to pdf` → tree completo
+con `<Document>` → `<P>`/`<Table>`/`<TR>`/`<TH>`/`<TD>` annidati.
+
+### Non-regressione
+
+Tutti i casi di test esistenti continuano a funzionare:
+
+- ✅ busta_paga.pdf: `1.993,00`, `COGNOME E NOME`, `NETTO BUSTA`
+- ✅ cu.pdf rotation 90° p1: `BANCA NAZIONALE`, `Categoria`
+- ✅ cu.pdf p199: `Categoria` (no `iCategora`)
+- ✅ sample/complex.pdf
+
+## [0.3.12] - ottimizzazioni performance estrazione tabelle
+
+(vedi note di rilascio precedenti)
+
+## [0.3.11] - opzione `cell_padding` per char fuori bordo cella
+
+### Aggiunto: `Table#extract(cell_padding: N)` per recuperare char border-line
+
+Su alcuni PDF (CR Banca d'Italia, header tabelle) il primo char di una
+cella è disegnato **leggermente fuori** dal bordo della cella stessa.
+Esempio: la `I` maiuscola di "Intermediario:" ha `x0=24.0` ma la
+cella inizia a `x=25.6` (la `I` sporge di 1.6 punti a sinistra del
+bordo). Il filtro midpoint (identico a pdfplumber) calcola `h_mid =
+25.25` e esclude la `I` perché < 25.6, producendo `"ntermediario:"`.
+
+Pdfplumber ha **esattamente lo stesso problema** (verificato sul PDF):
+il midpoint filter è una decisione di design comune. Però noi possiamo
+offrire una via di mezzo.
+
+### Nuova API
+
+```ruby
+table.extract                       # default: pdfplumber-compat
+table.extract(cell_padding: 2.0)    # recupera char che sporgono fino
+                                    # a 2pt fuori dai bordi sinistro/alto
+```
+
+`cell_padding` estende il bbox di ogni cella verso **sinistra** e
+verso l'**alto** di N punti prima di applicare il filtro midpoint.
+Default 0.0 = comportamento identico a prima (e a pdfplumber).
+
+Il padding è asimmetrico (solo bordi sinistro/alto, non destro/basso)
+per evitare di catturare char condivisi con celle adiacenti: se
+entrambe le celle vicine espandessero su tutti i lati, un char tra
+loro finirebbe in entrambe. Limitando il padding ai bordi "interno-
+sinistro" e "interno-alto" un char fuori-bordo-sinistro finisce solo
+nella cella alla sua destra, dove probabilmente appartiene.
+
+### Risultato sul PDF problematico
+
+```
+ext = Rpdfium::Table::Extractor.new(page, ...)
+ext.tables.first.extract                       # → ["ntermediario:", "BANCA NAZIONALE..."]
+ext.tables.first.extract(cell_padding: 2.0)    # → ["Intermediario:", "BANCA NAZIONALE..."]
+```
+
+### Test di non-regressione
+
+Tutti i PDF di test continuano a funzionare correttamente con cell_padding
+default (0.0):
+
+- ✅ busta_paga.pdf (numeri, parole con spazi, NETTO BUSTA)
+- ✅ cu.pdf pag. 1 (rotation 90°): Categoria, RISCHI AUTOLIQUIDANTI, 172.136
+- ✅ cu.pdf pag. 199 (rotation 0°, font piccolo): Categoria, Tipo Attività
+- ✅ sample.pdf (Lorem ipsum) + complex.pdf (>200k char)
+
+Con `cell_padding: 2.0` su cu.pdf pag. 1:
+- ✅ "Intermediario:" recuperato per intero
+- ✅ Nessun valore numerico duplicato (172.136 appare 3 volte come atteso)
+
+## [0.3.10] - bugfix: ordine char nelle celle con `top` quasi-uguale
+
+### Risolto: parole scrambled tipo `iCategora` invece di `Categoria`
+
+Su alcuni PDF (esempio: CR Banca d'Italia, pag. 199+ con font piccolo)
+le celle delle tabelle uscivano con char riordinati in modo errato:
+
+| Atteso        | Output errato        |
+| ------------- | -------------------- |
+| `Categoria`   | `iCategora`          |
+| `Localizzazione` | `iLoca li zzazone i` |
+| `Tipo Attività` | `iTpo i Attvt i i à` |
+
+Pattern: il char `i` (e occasionalmente altri con `x-height` sottile)
+veniva spostato all'inizio della parola o disperso.
+
+### Causa
+
+Regressione dell'ottimizzazione 0.3.9 in `WordExtractor#extract_words`.
+
+L'ottimizzazione partiva dal presupposto che, dopo `chars.sort_by { |c|
+[c[:top], c[:x0]] }` + `Cluster.cluster_objects(:top)`, ogni cluster
+"riga" fosse già ordinato internamente per x0 — quindi il `row.sort_by
+{ |c| c[:x0] }` interno era eliminato come ridondante.
+
+Il presupposto è **falso** quando due char della stessa riga visiva hanno
+`top` leggermente diversi (es. la `i` minuscola di `Categoria` ha
+`top=414.9789`, le altre lettere `top=414.9869`, differenza 0.008pt).
+PDFium spesso assegna alle bbox di char ascender/descender top
+leggermente diversi per ragioni di hinting/anti-aliasing. La
+differenza è invisibile graficamente ma rilevante per il sort.
+
+Effetto: il sort globale `[top, x0]` mette la `i` (top minore) **prima
+di tutte le altre lettere** della parola, indipendentemente da x0. Il
+`cluster_objects` poi raggruppa tutti i char nella stessa riga (entro
+y_tolerance=3.0), ma non riordina internamente. Quindi all'iterazione
+della riga, la `i` viene letta per prima e finisce all'inizio.
+
+### Fix
+
+Ripristinato il `row_sorted = row.sort_by { |c| c[:x0] }` dentro il
+loop delle righe. L'ottimizzazione 0.3.9 era valida solo per il caso
+di top perfettamente identici; non lo è in generale.
+
+Il costo computazionale aggiunto è marginale: un sort O(n log n) su
+righe corte (~50 char), dominato dall'overhead dell'FFI roundtrip per
+char nella fase precedente. Verificato empiricamente: tempo
+`extract_text` su 20 pagine di complex.pdf invariato (~80ms).
+
+### Test di non-regressione
+
+Tutti i PDF di test continuano a funzionare correttamente:
+
+- ✅ busta_paga.pdf: numeri (`1.993,00`, `2.895,26`), spazi parole (`COGNOME E NOME`, `NETTO BUSTA`)
+- ✅ sample.pdf: Lorem ipsum (2913 char)
+- ✅ complex.pdf (85 pag): 224.645 char totali
+- ✅ cu.pdf pag. 1 (rotation 90°): `BANCA NAZIONALE DEL LAVORO`, `Categoria`, valori numerici
+- ✅ **cu.pdf pag. 199** (rotation 0°, font piccolo): `Categoria`, `Localizzazione`, `Tipo Attività`, `Accordato Operativo` — tutti integri
+
+## [0.3.8] - supporto pagine ruotate (90°, 180°, 270°)
+
+### Risolto: estrazione completamente errata su PDF con `Page#rotation != 0`
+
+Su PDF con pagine ruotate (esempio: CU Banca d'Italia, certificate
+ruotate 90° CW per essere visualizzate landscape ma "logicamente"
+portrait), `Page#chars` ritornava bbox nel sistema **raw** PDFium
+(pre-rotazione), mentre PDFium stesso esponeva `width`/`height`
+**post-rotazione**. Il mismatch causava:
+
+- `top` dei char tutti uguali nella stessa colonna ma `top` diverso
+  tra char della stessa parola (perché il testo era "verticale" nel
+  sistema raw)
+- L'estrazione tabelle produceva celle illeggibili: testo letto
+  carattere per carattere a rovescio (`.A/.P/.S/O/R/O/V/A/L/L/E/D/E/L/A`
+  invece di `BANCA NAZIONALE DEL LAVORO S.P.A.`)
+- I segmenti di linea (`line_segments`) erano nel sistema raw, mentre
+  i char erano (parzialmente) nel sistema post-rotation, rendendo
+  impossibile il match cellule/contenuti
+
+### Fix
+
+Tre interventi simmetrici per uniformare il sistema di coordinate:
+
+1. **`compute_chars`**: applica la rotazione della pagina a ogni bbox di
+   char (e all'origin point) prima di restituirli. Le coord sono ora
+   sempre top-down nel sistema della pagina post-rotazione, allineate
+   col rendering visivo. Coerente con pdfplumber.
+
+2. **`line_segments`**: stesso trattamento agli endpoint dei segmenti.
+   Il `build_segment` ora riceve un `rotation_ctx` invece del solo
+   `page_h`, e trasforma entrambi i punti del segmento.
+
+3. **Helper `apply_page_rotation_to_char` e `apply_page_rotation_to_point`**:
+   centralizzano la matematica delle 4 rotazioni canoniche (0°, 90° CW,
+   180°, 270° CW). Per rotation = 0 il comportamento è identico al pre-
+    0.3.8 (semplice bottom-up → top-down).
+
+### Verifica
+
+Test di non-regressione su 4 PDF:
+
+| PDF | Rotation | Risultato |
+| --- | -------: | --------- |
+| busta_paga.pdf (cedolino TeamSystem) | 0° | Invariato — tutti i valori critici (`1.993,00`, `COGNOME E NOME`, `NETTO BUSTA`) preservati |
+| sample.pdf | 0° | Invariato (Lorem ipsum, 2913 char) |
+| complex.pdf (85 pag) | 0° | Invariato (224.645 char totali) |
+| **cu.pdf (CR Banca d'Italia, 226 pag)** | **90° CW** | **Estrazione ora corretta** |
+
+Esempio CU pagina 1 dopo il fix:
+
+```
+=== Tabella 0 ===
+  ['ntermediario:', 'BANCA NAZIONALE DEL LAVORO S.P.A.']
+
+=== Tabella 1 ===
+  Header: ['Categoria', 'Localizzazione', 'Durata/Residua', 'Divisa',
+           'Import Export', 'Tipo Attività', 'Stato Rapporto',
+           'Tipo/Garanzia', 'Ruolo/Affidato', 'Accordato',
+           'Accordato/Operativo', 'Utilizzato', 'Importo/Garantito']
+  Row 1:  ['RISCHI/AUTOLIQUIDANTI', 'TERMOLI', 'FINO A 1/ANNO', ...,
+           '0', '172.136', '172.136', '172.136', '0']
+```
+
+Coincide cella-per-cella con pdfplumber sullo stesso PDF.
+
+### API: nessuna breaking change
+
+Le API pubbliche `Page#chars`, `Page#words`, `Page#text`,
+`Page#line_segments`, `Page#extract_tables` mantengono la stessa
+firma. I valori restituiti **cambiano per i PDF ruotati**: prima
+erano in coord raw (sbagliate), ora in coord post-rotation (corrette,
+allineate al rendering visivo). Per PDF con rotation = 0 (la stragrande
+maggioranza) non c'è alcuna differenza.
+
+## [0.3.7] - bugfix critico: buffer overrun in `read_text_obj_text_from`
+
+### Risolto: IndexError "Memory access offset=0 size=N out of bounds"
+
+`Page#chars` (e di conseguenza `extract_text` / `extract_tables`) crashava
+con `IndexError` quando un text object PDF conteneva una stringa più
+lunga di 128 byte (parole come `consectetuer`, `Phasellus`, frasi intere
+da rivista). Lo stack trace tipico:
+
+```
+IndexError: Memory access offset=0 size=158 out of bounds
+  page.rb:429 in FFI::AbstractMemory#read_bytes
+  page.rb:429 in Page#read_text_obj_text_from
+  page.rb:343 in block in Page#compute_chars
+```
+
+Sui PDF tipici di gestionali italiani (cedolini TeamSystem) il bug NON
+si manifestava perché ogni text object lì contiene 1-4 char (sotto-soglia).
+Si attivava su PDF con text run più lunghi (riviste, articoli, qualsiasi
+PDF generato da TeX/Word/InDesign con kerning conservato a livello di
+parola).
+
+### Causa
+
+Errore mio nell'introdurre `:text_obj_ends_with_space` nella 0.3.4. La
+firma C di `FPDFTextObj_GetText` è:
+
+```c
+unsigned long FPDFTextObj_GetText(FPDF_PAGEOBJECT, FPDF_TEXTPAGE,
+                                  FPDF_WCHAR* buffer, unsigned long length);
+```
+
+dove **`length` è in BYTE** (non in count di uint16) e il return è il
+numero di byte **totali necessari** per scrivere il testo, anche se il
+buffer è troppo piccolo. Stavamo allocando 64 uint16 (= 128 byte),
+passando `64` come length (interpretato da PDFium come 64 BYTE = 32
+uint16!), e poi leggendo `(nbytes - 1) * 2` byte dal buffer dove `nbytes`
+era il return-value, che eccedeva il buffer allocato. Tre bug
+sovrapposti.
+
+### Fix
+
+Pattern probe-then-fetch con clamp difensivo:
+
+1. Provo con buffer ragionevole (256 byte = 128 char UTF-16, copre ~99%
+   dei text obj reali).
+2. Se PDFium ne richiede di più (`needed > buf_capacity`), rialloco
+   esatto e rileggo.
+3. Clamp finale: leggo `min(needed - 2, buf_capacity - 2)` byte, mai
+   oltre quanto effettivamente allocato. Difesa-in-profondità.
+
+Il costo extra di FFI nei casi tipici è zero (il buffer iniziale basta);
+solo per text obj > 256 byte serve una seconda chiamata.
+
+### Bug latenti collaterali fixati
+
+Stesso pattern di buffer-overrun era presente in 3 altri helper aggiunti
+nella 0.3.6:
+
+- `read_mark_name` (buffer 128 uint16)
+- `read_mark_param_key` (buffer 64 uint16)
+- `read_mark_param_string` (buffer 256 uint16)
+
+Mai stati hit in produzione perché i mark name / param sono tipicamente
+brevi ("Span", "Artifact", "MCID"), ma la patologia esisteva.
+Risolti tutti con lo stesso clamp.
+
+Anche `Structure::Attachment#bytes` aveva un pattern analogo: leggeva
+`buf.read_bytes(out_size.read_ulong)` dopo la seconda chiamata, dove
+`out_size` poteva eccedere il buffer. Cambiato a `buf.read_bytes(n)`
+con `n` = dimensione effettivamente allocata.
+
+### Test
+
+Smoke test esteso su `sample.pdf`, `complex.pdf` (60 MB / 85 pagine),
+e `busta_paga.pdf`: tutte le API pubbliche (`chars`, `words`, `text`,
+`line_segments`, `mediabox`, `cropbox`, `annotations`, `images`,
+`marked_content_regions`, `marked_content_inventory`, `extract_tables`,
+`attachments`) verdi su tutti e tre i PDF.
+
+Tutti i valori critici di non-regressione preservati:
+`1.993,00`, `2.895,26`, `COGNOME E NOME`, `MATRICOLA INPS`,
+`NETTO BUSTA`, Lorem ipsum su sample, 224.645 char su complex.
+
+## [0.3.6] - copertura binding pubbliche PDFium
+
+### Aggiunto: 52 binding pubbliche PDFium mancanti
+
+L'inventario sistematico dell'API pubblica PDFium (455 simboli esportati
+dal binario ufficiale) ha rivelato 319 funzioni non ancora attaccate.
+Selezionate 52 ad alto valore per una libreria di estrazione PDF generalista,
+escludendo i setter (mutation), gli event handler form-fill (mouse/keyboard)
+e API niche (thumbnail, JS actions). Tutte sono getter e tutti i tipi
+ritornati sono FFI-safe.
+
+Distribuzione per categoria:
+
+| Categoria              | Binding | Aiuta a... |
+| ---------------------- | ------: | ---------- |
+| Page geometry          | 5       | Sapere mediabox/cropbox/bleed/trim/art (pdfplumber-compat) |
+| PageObject state       | 5       | Filtrare oggetti nascosti, distinguere linee tratteggiate |
+| Marked Content         | 9       | Raggruppare semanticamente char in PDF tagged (PDF/UA) |
+| Catalog/Doc metadata   | 2       | Language, PageMode |
+| Links + hit-test       | 7       | API posizionale `link_at(x, y)`, mapping link → text range |
+| Actions/Destinations   | 6       | Outline navigation completa |
+| Font extras            | 4       | Font data raw, glyph path vettoriale |
+| Text page extras       | 3       | Char ↔ text index mapping per ricerca |
+| Annotation extras      | 7       | Flags/colors/border/AP/file attachment / quad points |
+| Attachment metadata    | 4       | Subtype, key-value custom metadata |
+
+### Nuove API pubbliche di alto livello
+
+- **`Page#mediabox / cropbox / bleedbox / trimbox / artbox`** — accessor
+  pdfplumber-compatibili. Ritornano tuple `[x0, top, x1, bottom]` in
+  coordinate top-down (coerenti con `chars`, `edges`, `cells`). `cropbox`
+  fa fallback automatico su mediabox se assente, come prescrive PDF spec
+  14.11.2. Ritornano `nil` se il box non è definito.
+
+- **`Page#marked_content_regions`** → Hash `{mcid => [page_objects]}`.
+  Raggruppa gli oggetti per Marked Content ID. Vuoto su PDF non-tagged
+  (gestionali italiani); su PDF tagged è il modo più affidabile di
+  ottenere unità semantiche (paragrafi, span, celle tabella).
+
+- **`Page#marked_content_inventory`** → Array di marks con `:obj`,
+  `:mark_name`, `:params`. Per inspection di Tagged PDF (nomi tipici:
+  "Span", "P", "TR", "TD", "Artifact", "Figure").
+
+- **`Page#link_at(x, y)`** — hit-test posizionale: ritorna l'Annotation
+  link che contiene il punto, o `nil`. Per il mapping click sul rendering
+  → URL.
+
+- **`Page#line_segments(include_curves: false, include_dashed: false)`**
+  — nuovo flag `include_dashed`. **Default cambiato a `false`**: le
+  linee tratteggiate sono spesso "guide non-printing" che confondono la
+  detection di cellule tabella. Chi le vuole esplicitamente (drawing
+  extraction completo) passa `include_dashed: true`. I segment hanno
+  ora il campo `:dashed` (bool).
+
+- **PageObject inactive automaticamente skippati** in line_segments:
+  oggetti con Optional Content disabilitato non finiscono più nell'output.
+  Su PDF normali (sempre attivi) il comportamento è invariato.
+
+### Bug fix collaterali
+
+- Rimossa duplicazione di `FPDFText_GetMatrix` (era attached due volte;
+  FFI dava warning ma una sola definizione era effettiva). La binding
+  resta solo nella sezione Text page (riga ~351 di `raw.rb`).
+- Tutti gli helper `read_*` per marked content sono in `begin/rescue
+  Rpdfium::LoadError` per supportare build PDFium più vecchi senza
+  introdurre regressioni.
+
+### Casi border-line text extraction
+
+**Non risolti** sui PDF da gestionali italiani (TeamSystem, Zucchetti):
+parole come `Sede pr i nc` (`Sede principale`), `Imp i ega to`
+(`Impiegato`), `IMPONIBILE INAILMESE` (`IMPONIBILE INAIL MESE`) restano
+spezzate o fuse perché il content stream PDF emette quei char con
+kerning interno (operatori `TJ` con valori intermedi) che PDFium consuma
+internamente per il rendering ma non espone via API C pubblica.
+
+Le binding `FPDFDICT_*` che permetterebbero di accedere al content stream
+raw (e ottenere il kerning, come fa pdfminer.six) **non esistono nel
+PDFium ufficiale di Google/Chromium**. Esistono solo nel fork commerciale
+Pdfium.NET di Patagames Software, non utilizzabile sotto licenza
+open-source. Le 421 simboli `FPDF*` esportati dal binario bblanchon
+sono stati verificati: nessun `FPDFDICT_*`.
+
+I marked content (`FPDFPageObj_GetMark` / `CountMarks`) **sono** la via
+ufficiale per accedere alla struttura semantica, ma richiedono che il
+PDF sia stato generato come Tagged PDF. I PDF da gestionali italiani
+non lo sono. Per PDF da Word/InDesign/InEsign-style tagged, le nuove
+API ora coprono il caso.
+
+## [0.3.5] - Ottimizzazioni
+
+### Migliorato: ridotta computazione e semplificati branch condizionali
+
+## [0.3.4] - advance del glifo, identità text-object, segnale fine-token
+
+### Aggiunto: bindings e nuove proprietà sui char
+
+Tre binding PDFium fondamentali che mancavano:
+
+- **`FPDFFont_GetGlyphWidth(font, glyph_cp, font_size, *float)`** — larghezza
+  nominale del glifo nel font program. Equivale concettualmente alla
+  metric che pdfminer.six legge dal font dictionary del PDF.
+
+- **`FPDFFont_GetAscent` / `FPDFFont_GetDescent`** — metriche font in
+  unità del font program, utili per baseline e leading detection.
+
+- **`FPDFText_GetMatrix(textpage, char_index, *FS_MATRIX)`** — matrice di
+  trasformazione (CTM) applicata al char. Componente `:a` è la scala
+  orizzontale font→pagina.
+
+Queste binding sono ora esposte come API pubbliche di `Rpdfium::Raw` ed
+utilizzate internamente per arricchire ogni char con tre nuove proprietà:
+
+| Proprietà                  | Tipo     | Significato |
+| -------------------------- | -------- | ----------- |
+| `:advance`                 | Float?   | Larghezza nominale del glifo in coordinate pagina, calcolata come `glyph_width × |CTM.a|`. Più stabile della `bbox_width` per char con kerning post-applied. |
+| `:text_obj_id`             | Integer? | Identificatore stabile (pointer address) del text object contenente questo char. Tutti i char dello stesso text obj condividono lo stesso ID — utile per raggruppare semanticamente char correlati a livello content-stream. |
+| `:text_obj_ends_with_space` | bool?  | True se il content stream PDF ha emesso uno spazio finale dopo questo char (es. fine di un token testuale). Segnale di "fine token" dichiarato dal PDF — non sempre coincidente con fine parola visiva, ma utile come indizio. |
+
+### Migliorato: rebuild_word_separators usa i nuovi segnali
+
+`Page#chars` (con `inject_spaces: true`, default) ora ricostruisce i word
+boundary combinando:
+
+1. **Veto duro**: se `prev[:text_obj_ends_with_space] == false`, nessuno
+   spazio viene inserito anche con gap geometrico grande. È kerning
+   interno a un token dichiarato dal PDF.
+
+2. **Threshold dinamica**: per i candidati ammessi (prev fine-token o
+   segnale assente), uso soglia geometrica `gap > 0.3 × max_advance`
+   come default, alzata a `0.7 × max_advance` se il contesto è numerico
+   (cifre o punteggiatura `.`/`,`). Questa euristica preserva i numeri
+   `2.895,26`/`1.993,00` interi mentre recupera la maggior parte degli
+   spazi tra parole.
+
+### Confronto con pdfplumber sul PDF di test
+
+Recuperi netti rispetto alla 0.3.3:
+
+| Cella                  | rpdfium 0.3.3 | rpdfium 0.3.4 | pdfplumber |
+| ---------------------- | ------------: | ------------: | ---------: |
+| COGNOME E NOME         | `COGNOME ENOME` | `COGNOME E NOME` ✓ | `COGNOME E NOME` |
+| MATRICOLA INPS         | `MATRICOLAINPS` | `MATRICOLA INPS` ✓ | `MATRICOLA INPS` |
+| POSIZIONE INAIL        | `POSIZIONE INAIL` ✓ | `POSIZIONE INAIL` ✓ | `POSIZIONE INAIL` |
+| DATA NASCITA           | `DATANASCITA` | `DATA NASCITA` ✓ | `DATA NASCITA` |
+| CODICE FISCALE         | `CODICE FISCALE` ✓ | `CODICE FISCALE` ✓ | `CODICE FISCALE` |
+| COMUNE DI RESIDENZA    | `COMUNEDI RESIDENZA` | `COMUNE DI RESIDENZA` ✓ | `COMUNE DI RESIDENZA` |
+| DATA ASSUNZIONE        | `DATAASSUNZIONE` | `DATA ASSUNZIONE` ✓ | `DATA ASSUNZIONE` |
+| QUALIFICA INPS         | `QUALIFICAINPS` | `QUALIFICA INPS` ✓ | `QUALIFICA INPS` |
+| TIPO RAPPORTO          | `TIPORAPPORTO` | `TIPO RAPPORTO` ✓ | `TIPO RAPPORTO` |
+| RETR. DI FATTO         | `RETR.DI FATTO` | `RETR. DI FATTO` ✓ | `RETR. DI FATTO` |
+| CCNL APPLICATO         | `CCNLAPPLICATO` | `CCNL APPLICATO` ✓ | `CCNL APPLICATO` |
+| ADD. REG. ANNO DOVUTA  | `ADD. REG.ANNODOVUTA` | `ADD. REG. ANNO DOVUTA` ✓ | `ADD. REG. ANNO DOVUTA` |
+| ADD. COM. ANNO DOVUTA  | `ADD. COM.ANNODOVUTA` | `ADD. COM. ANNO DOVUTA` ✓ | `ADD. COM. ANNO DOVUTA` |
+| BONUS IRPEF ANNO       | `BONUS IRPEFANNO` | `BONUS IRPEF ANNO` ✓ | `BONUS IRPEF ANNO` |
+| 2.857,15 (e altri num) | `2.857,15` ✓ | `2.857,15` ✓ | `2.857,15` |
+
+Casi border-line residui (PDFium non emette il segnale fine-token):
+`Sede pr i nc`, `Imp i ega to`, `IMPONIBILE INAILMESE`. Pdfminer.six li
+gestisce perché legge gli operatori `TJ` con kerning dal content stream
+raw, info che PDFium consuma internamente e non espone via API pubblica.
+
+### Test
+
+- 30 unit test + 8 test di integrazione su PDF reale, tutti verdi.
+- Nuovi test: presenza di `:advance`, `:text_obj_id`,
+  `:text_obj_ends_with_space` su char reali.
+
+## [0.3.3] - ricostruzione word boundary geometry-based
+
+### Risolto
+
+**`Page#chars` ricostruisce gli spazi tra parole basandosi sulla geometria
+dei char**, invece di affidarsi agli spazi sintetici di PDFium (che sono
+inaffidabili: PDFium li emette aggressivamente anche tra cifre di numeri).
+
+#### Perché era un problema
+
+PDFium ha due comportamenti patologici sui spazi sintetici:
+
+1. **Bbox degenere**: gli spazi tra parole hanno `top == bottom == baseline`,
+   non in linea con i char circostanti. Il cluster per riga in
+   `extract_text` li scartava, e parole adiacenti come `COGNOME E NOME`
+   si fondevano in `COGNOMEENOME`.
+
+2. **Falsi positivi sui numeri**: PDFium inserisce uno spazio sintetico
+   tra OGNI cifra e la punteggiatura di un numero. `2.895,26` aveva
+   spazi tra `2/.`, `./8`, `5/,`, `,/2`. Se li accettavamo, l'output
+   diventava `2 . 895 , 26`.
+
+#### La fix
+
+Ho buttato via tutti gli spazi sintetici di PDFium e ricostruito i
+word boundary basandomi solo sulla geometria dei char "veri":
+`gap > 0.4 × max(prev_width, next_width)` → spazio. La soglia 0.4 con
+`max_w` (non `avg_w`) è cruciale: i char di punteggiatura come `.` e `,`
+sono più stretti delle cifre, e usare la media gonfierebbe i ratio dei
+gap intra-numero. Usando il max delle due larghezze, il numero
+`2.895,26` ha tutti i gap intra-numero con ratio < 0.35, mentre i veri
+gap inter-parola hanno ratio > 0.45.
+
+Soglia 0.4 tarata empiricamente sui dati TeamSystem reali (1400 casi
+intra + 663 inter), con classificazione corretta al 100% sui casi
+non-borderline.
+
+#### Confronto col PDF di test
+
+| Cella                    | rpdfium 0.3.2 | rpdfium 0.3.3 | pdfplumber  |
+| ------------------------ | ------------: | ------------: | ----------: |
+| Imponibile IRPEF Mese    |    `2.618,84` |    `2.618,84` |  `2.618,84` |
+| Netto Busta              | `NETTOBUSTA/1.993,00` | `NETTOBUSTA/1.993,00` | `NETTO BUSTA/1.993,00` |
+| COGNOME E NOME           | `COGNOMEENOME` | `COGNOME ENOME` | `COGNOME E NOME` |
+| MATRICOLA INPS           | `MATRICOLAINPS` | `MATRICOLAINPS` | `MATRICOLA INPS` |
+| POSIZIONE INAIL          | `POSIZIONEINAIL` | `POSIZIONE INAIL` | `POSIZIONE INAIL` |
+| RETR. DI FATTO           | `RETR.DIFATTO` | `RETR.DI FATTO` | `RETR. DI FATTO` |
+| GIORNO DI RIPOSO         | `GIORNODIRIPOSO` | `GIORNO DI RIPOSO` | `GIORNO DI RIPOSO` |
+| ONERI DED.               |   `ONERIDED.` |    `ONERIDED.` |  `ONERI DED.` |
+
+La 0.3.3 recupera la maggior parte degli spazi inter-parola (vedi
+`POSIZIONE INAIL`, `GIORNO DI RIPOSO`, `RETR.DI FATTO`). Restano persi
+alcuni casi border-line dove il gap visivo è genuinamente piccolo
+(`COGNOME E NOME` che ha `E` molto vicina a `NOME`). Questi sono al
+limite delle possibilità di un algoritmo geometrico puro: pdfminer
+risolve usando l'advance del font dal content stream PDF, info non
+esposta da PDFium.
+
+### API
+
+- **`Page#chars(inject_spaces: true)` ora è il default**. Chi vuole il
+  comportamento "raw PDFium" (tutti i char inclusi gli spazi sintetici
+  aggressivi) passa `inject_spaces: false`.
+- Il vecchio metodo privato `inject_synthetic_spaces` è stato rimosso e
+  rimpiazzato da `rebuild_word_separators` (più descrittivo del nuovo
+  approccio).
+
+## [0.3.2] - punteggiatura preservata nelle celle tabellari
+
+### Risolto
+
+**`Page#chars` ora ritorna bbox "loose" di default** (`loose: true`),
+allineando il comportamento a quello di `pdfminer.six`. Le bbox loose
+sono uniformi per riga: tutti i char della stessa linea logica condividono
+top/bottom proporzionali alla font-size, invece dei tight glyph box che
+PDFium darebbe nativamente.
+
+#### Perché era un problema
+
+Le bbox tight rispettano il singolo glifo. Un `.` (punto decimale) ha
+una bbox alta ~0.85pt, mentre un `5` accanto ne ha ~7pt sulla stessa
+linea. I loro midpoint verticali differiscono di ~3pt — quanto basta a
+far cadere il `.` fuori dalla bbox cella nel filtro `Table#extract`,
+che usa il midpoint per decidere quali char appartengono alla cella
+(stessa scelta di pdfplumber).
+
+Effetto sul cedolino TeamSystem: valori come `1.993,00`, `2.857,15`,
+`7.788,60` venivano estratti come `1 993 00`, `2 857 15`, `7 788 60` —
+la punteggiatura cadeva fuori. Con loose box, tutti i char della riga
+hanno lo stesso midpoint verticale, e i punti/virgole arrivano dentro
+la cella.
+
+#### Confronto con pdfplumber
+
+Sul cedolino di test `busta_paga.pdf`:
+
+| Cella                | rpdfium 0.3.1 | rpdfium 0.3.2 | pdfplumber |
+| -------------------- | ------------: | ------------: | ---------: |
+| Netto Busta          |       `1 993 00` |   `1.993,00` |  `1.993,00` |
+| Imponibile IRPEF MESE |    `2 618 84` |   `2.618,84` |  `2.618,84` |
+| TFR Spettante        |       `3 446 15` |   `3.446,15` |  `3.446,15` |
+| Retr. di Fatto       |       `2 857 15` |   `2.857,15` |  `2.857,15` |
+
+### Aggiunto
+
+- **`Page#chars(inject_spaces: true)`**: opt-in che inietta spazi
+  sintetici nei gap orizzontali significativi (gap > 0.85 × char width)
+  della stessa riga. Approssima il comportamento di pdfminer.six per
+  parole adiacenti che PDFium fonderebbe per via del kerning. Può
+  produrre falsi positivi su font condensati. **Default `false`**:
+  preferiamo "non spezzare parole valide" rispetto a "catturare ogni
+  spazio mancante", in linea con la filosofia "quello che PDFium emette
+  è la verità".
+
+- Helper privato `Page#inject_synthetic_spaces` esposto come API
+  pubblica per chi vuole post-processare i char.
+
+- Cache di `Page#chars` per (loose, inject_spaces): ricostruire
+  l'array di char è O(n) di chiamate FFI, costoso su pagine grosse.
+
+### Limitazioni note
+
+- Sul cedolino di test, `inject_spaces: true` recupera ~80% degli
+  spazi inter-parola persi (es. `NETTO BUSTA`), ma introduce qualche
+  falso positivo (es. `Sede pr incipale`). Questo è un trade-off
+  intrinseco di PDFium che non espone l'advance del font dal content
+  stream, l'unica metrica davvero affidabile per decidere "spazio o no".
+  Per estrazione testuale che richiede spazi perfetti, considerare
+  pdfminer.six (e quindi pdfplumber); per estrazione tabellare con
+  punteggiatura preservata, rpdfium è ora allineato.
+
+## [0.3.1] - discesa nei Form XObjects
+
+### Risolto
+
+**`Page#line_segments` ora discende ricorsivamente nei Form XObjects**
+applicando la matrice di trasformazione affine che li posiziona nello spazio
+pagina. Prima di questa fix, su PDF dove la grafica della pagina era
+incapsulata in un singolo Form XObject (PDF generati da TeamSystem,
+Zucchetti e altri gestionali italiani; molti template Word/Excel),
+`line_segments` ritornava un Array vuoto anche se visivamente la pagina
+era piena di linee e bordi cella.
+
+Conseguenza diretta: `Page#vertical_lines`, `Page#horizontal_lines`, e la
+strategia `:lines` di `Table::Extractor` ora funzionano correttamente su
+questi PDF.
+
+Per il cedolino TeamSystem di test (`busta_paga.pdf`), i numeri:
+
+| Metrica           | prima 0.3.1 | dopo 0.3.1 | pdfplumber |
+| ----------------- | ----------: | ---------: | ---------: |
+| line_segments     |           0 |        525 |   420 (\*) |
+| horizontal_lines  |           0 |        375 |        210 |
+| vertical_lines    |           0 |        437 |        210 |
+| tabelle estratte  |           1 (\*\*) |     1 |          1 |
+| dimensione tab    |   1×N nonsens |  28×44 |      28×44 |
+
+(\*) pdfplumber decompone i 105 rettangoli in 4 lati ciascuno =
+420 edges; rpdfium attualmente li conta con duplicazione (le 4 linee del
+contour + il close-path), per questo 525 invece di 420. La detection di
+celle non ne risente perché lo snap+join collassa i duplicati.
+(\*\*) Senza linee, rpdfium 0.3.0 con strategia `:lines` non trovava
+tabelle e cadeva nel fallback `:text`, producendo una "tabella" gigantesca
+che copriva l'intera pagina.
+
+### Aggiunto
+
+- Bindings `FPDFFormObj_CountObjects` e `FPDFFormObj_GetObject` per
+  iterare i child di un Form XObject.
+- Helpers privati `compose_matrix`, `apply_matrix`, `read_object_matrix`
+  per la composizione di trasformazioni affini PDF.
+- Test di integrazione su PDF reale (`busta_paga.pdf`) che verifica:
+  numero minimo di line_segments, struttura della tabella anagrafica,
+  conteggio chars nel range atteso.
+
+### Compatibilità
+
+- Nessuna API breaking. `line_segments` mantiene la stessa firma e lo
+  stesso formato di output.
+- I PDF già funzionanti in 0.3.0 (con grafica top-level) continuano a
+  funzionare identici: la discesa nei Form XObjects parte dal CTM
+  identità, quindi a livello top non c'è cambiamento di coordinate.
+
+## [0.3.0] - estrazione tabelle riallineata 1:1 a pdfplumber
+
+### Riscritto da zero
+
+L'intero pipeline tabellare è stato riscritto seguendo il sorgente di
+[pdfplumber/table.py](https://github.com/jsvine/pdfplumber/blob/stable/pdfplumber/table.py)
+e [pdfplumber/utils/text.py](https://github.com/jsvine/pdfplumber/blob/stable/pdfplumber/utils/text.py).
+La versione 0.2.x aveva una serie di approssimazioni che producevano errori
+sistematici di estrazione su PDF con layout free-form (es. cedolini
+TeamSystem). I bug fix specifici:
+
+1. **`words_to_edges_v` clusterizza ora tre coordinate (`x0`, `x1`, centro)**
+   invece di solo `x0`. Le colonne numeriche right-aligned (importi
+   `1.234,56` allineati a destra) erano invisibili al clustering basato su
+   `x0`. Aggiunta dedupe per overlap di bbox: cluster sovrapposti tengono
+   solo il più popolato.
+
+2. **`words_to_edges_h` emette DUE edges per riga** (top + bottom della
+   bbox del cluster). Senza il bottom edge, l'ultima riga di una tabella
+   rilevata da text-strategy non veniva mai chiusa.
+
+3. **`intersections_to_cells` usa l'algoritmo `find_smallest_cell`** di
+   pdfplumber con verifica `edge_connect` su identità d'oggetto degli
+   edge, non su sole coordinate. Due intersezioni con la stessa `x` ma
+   appartenenti a edge verticali distinti non producono più cella spuria.
+
+4. **`cells_to_tables` usa il fixed-point su corner condivisi**, non più
+   adjacency check coordinate-based. Filtro single-cell per scartare rumore.
+
+5. **Estrazione testo da cella usa midpoint del char**, non bbox-clip via
+   `FPDFText_GetBoundedText`. Il midpoint è il criterio identico di
+   pdfplumber, e risolve la concatenazione cross-cell ("RETRIBUZIONEUTILE")
+   che si verificava su PDF dove i char di celle adiacenti hanno bbox
+   leggermente sovrapposti.
+
+### Aggiunto
+
+- **`Rpdfium::Util::Cluster`** (nuovo modulo): primitive di clustering 1D
+  agglomerativo single-linkage usate da tutto il pipeline (`cluster_list`,
+  `cluster_objects`, `objects_to_bbox`, `bbox_overlap`).
+
+- **`Rpdfium::Util::WordExtractor`** (nuova classe): estrazione words da
+  char fedele a `pdfplumber.WordExtractor`. Supporta `x_tolerance`,
+  `y_tolerance`, `keep_blank_chars`, `extra_attrs` (split su cambio
+  font/size).
+
+- **`Rpdfium::Util::TextExtraction.extract_text`** (nuovo modulo): converte
+  un Array di char in stringa, raggruppando per riga via clustering del
+  `top` e per parola via gap orizzontale > x_tolerance. Equivalente a
+  `pdfplumber.utils.text.extract_text(layout=False)`.
+
+- **`Rpdfium::Table::Table`** (nuova classe): rappresenta una tabella
+  estratta. Espone `.cells`, `.rows`, `.columns`, `.bbox`, `.extract`.
+  L'API combacia con `pdfplumber.table.Table`.
+
+- **`edge_min_length_prefilter`** (default 1.0): filtra edges troppo corti
+  prima dello snap+join, per ridurre rumore da micro-segmenti vettoriali.
+
+- **`Rpdfium.extract_tables(..., keep_blank_rows: false)`** filtra di
+  default le righe completamente vuote che la strategia `:text` produce
+  per costruzione (effetto del doppio edge top+bottom).
+
+### API: breaking changes minori
+
+- Le strategy del `Extractor` validano l'input: `vertical_strategy` e
+  `horizontal_strategy` accettano solo `:lines` / `:lines_strict` /
+  `:text` / `:explicit`. Valori invalidi alzano `ArgumentError`.
+
+- L'oggetto restituito da `Extractor#tables` (e dall'alias `find`) non è
+  più un Hash con `:bbox`/`:rows`/`:cols`/`:grid`, ma un'istanza di
+  `Rpdfium::Table::Table`. Chi usa `Rpdfium.extract_tables` (top-level)
+  vede solo strutture base (Hash con `:page` e `:rows`), invariato.
+
+- `Edges.snap_horizontal` / `Edges.snap_vertical` / `Edges.join_horizontal`
+  / `Edges.join_vertical` / `Edges.intersections` (firma vecchia) /
+  `Cells.from_intersections` / `Cells.group_into_tables` rimossi. I
+  rimpiazzi sono `snap_edges`, `join_edge_group`, `merge_edges`,
+  `filter_edges`, `edges_to_intersections`, `intersections_to_cells`,
+  `cells_to_tables` con segnature 1:1 da pdfplumber.
+
+### Fix lifecycle (race finalizer)
+
+Document/Page/TextPage/Annotation/Search/Form::Environment usano ora un
+**state Hash condiviso tra istanza e finalizer**. Tre proprietà
+acquisite:
+
+- **Idempotenza** (`@state[:closed]` flag): nessuna doppia chiamata a
+  `FPDF_CloseDocument`/`FPDF_ClosePage`/etc anche se sia `close()`
+  esplicito che il GC partono.
+- **No-leak della closure**: il finalizer cattura un Hash, non `self`.
+  L'istanza può essere raccolta liberamente dal GC.
+- **Disarmo esplicito**: `close()` chiama `ObjectSpace.undefine_finalizer`
+  per impedire qualsiasi esecuzione tardiva del finalizer su un handle
+  già liberato.
+
+Risolve il segfault `FPDF_CloseDocument` durante introspezione del
+debugger su una collection di tabelle (riportato dall'utente con
+ruby-debug-ide).
+
+### Fix `candidate_paths` (FFI)
+
+Su macOS, FFI auto-appendeva `.dylib` a path `.so`, causando il fallimento
+del caricamento. Ora `candidate_paths` filtra i nomi di sistema per OS
+host: solo `.dylib` su macOS, solo `.so` su Linux, solo `.dll` su Windows.
+Inoltre se `ENV["PDFIUM_LIBRARY_PATH"]` o `Rpdfium::Binary.library_path`
+è impostato, viene usato come unico path: nessun fallback automatico.
+
+### Test
+
+- 30 unit test (60 asserzioni) coprono cluster primitives, word
+  extraction, edges (snap/join/filter/intersections/words_to_edges_v/h),
+  cells (smallest-cell + edge identity check), table (rows/columns/bbox/
+  extract con midpoint), extractor end-to-end con FakePage, regressione
+  TeamSystem (no più cross-cell concatenation; words_to_edges_v sui dati
+  reali di un cedolino italiano in formato TeamSystem).
+
+## [0.2.1] - allineamento PDFium chromium/6611+
+
+### Cambiato
+
+- **`FPDFText_GetTextRenderMode(text_page, char_index)` rimossa dalle
+  bindings.** Era stata rimossa upstream da PDFium in chromium/6611
+  (luglio 2024) — chiamarla causa `undefined symbol` con i build recenti
+  di pdfium-binaries. Riferimenti:
+  [pypdfium2#335](https://github.com/pypdfium2-team/pypdfium2/issues/335),
+  [pdfium-render#151](https://github.com/ajrcarey/pdfium-render/issues/151).
+- `Page#chars` ora ottiene `:render_mode` via il path nuovo: prima
+  risolve il text object che contiene il char con
+  `FPDFText_GetTextObject`, poi legge il render mode con
+  `FPDFTextObj_GetTextRenderMode` (che era già presente nella binding
+  ma non utilizzato a char-level). Una cache interna evita lookup
+  ripetuti — overhead invariato anche su pagine con migliaia di char.
+- Su build PDFium antichi (< chromium/6611) che non espongono
+  `FPDFText_GetTextObject`, `:render_mode` ricade a `nil` invece di
+  far esplodere l'estrazione.
+
+### Aggiunto
+
+- Binding di **`FPDFText_GetTextObject(text_page, char_index)`** —
+  rimpiazzo upstream per ottenere il text object di un char.
+- Binding di **`FPDFFont_GetBaseFontName(font, buffer, size)`** —
+  ritorna il `BaseFont` entry dal dict del font (può includere prefissi
+  di subset come `ABCDEF+Helvetica`). Firma `c_size_t` invece di
+  `c_ulong`, secondo l'header pubblico aggiornato.
+- Binding di **`FPDFFont_GetFamilyName(font, buffer, size)`** — ritorna
+  il nome famiglia "pulito".
+- `FPDFFont_GetFontName` mantenuta come fallback per compatibilità con
+  build PDFium più vecchi.
+
+## [0.2.0] - parità con pypdfium2
+
+Espansione massiccia. La superficie di API copre ora i casi d'uso principali
+di pypdfium2 più l'estrazione tabellare in stile pdfplumber.
+
+### Aggiunto — bindings FFI
+
+- **Path segments reali** via `FPDFPath_CountSegments`,
+  `FPDFPath_GetPathSegment`, `FPDFPathSegment_GetPoint/GetType/GetClose`.
+  Iterazione MOVETO/LINETO/BEZIERTO con state-machine corretta per
+  `closepath`, sostituendo l'approccio "bbox del path" della 0.1.0.
+- **Image objects**: `FPDFImageObj_GetImageMetadata`,
+  `GetImagePixelSize`, `GetBitmap`, `GetRenderedBitmap`,
+  `GetImageDataDecoded`, `GetImageDataRaw`, `GetImageFilterCount`,
+  `GetImageFilter`.
+- **Annotazioni**: `FPDFPage_GetAnnotCount/GetAnnot/CloseAnnot`,
+  `FPDFAnnot_GetSubtype/GetRect/GetStringValue/HasKey/GetLink`,
+  `FPDFLink_GetAction/GetDest/GetURL`, `FPDFAction_GetType/GetURIPath`.
+- **Form fields** (read-only): `FPDFDOC_InitFormFillEnvironment` con
+  `FPDF_FORMFILLINFO` versione 2 minimale, `FPDF_FFLDraw`,
+  `FPDFAnnot_GetFormFieldType/Name/Value/Flags/IsChecked`,
+  `GetOptionCount/GetOptionLabel`.
+- **Bookmarks** (outline): `FPDFBookmark_GetFirstChild/GetNextSibling/
+  GetTitle/GetDest`, `FPDFDest_GetDestPageIndex`.
+- **Attachments**: `FPDFDoc_GetAttachmentCount/GetAttachment`,
+  `FPDFAttachment_GetName/GetFile`.
+- **Structure tree** (PDF tagged): `FPDF_StructTree_GetForPage`,
+  `CountChildren`, `GetChildAtIndex`, `GetType`, `GetTitle`.
+- **Search interna**: `FPDFText_FindStart/FindNext/FindPrev/FindClose`,
+  `GetSchResultIndex`, `GetSchCount`.
+- **Char metadata estesa**: `FPDFText_GetLooseCharBox`,
+  `GetCharOrigin`, `GetCharAngle`, `IsGenerated`, `IsHyphen`,
+  `HasUnicodeMapError`, `GetFontInfo`, `GetTextRenderMode`, `GetMatrix`.
+- **Document**: `FPDF_GetMetaText`, `GetDocPermissions`, `GetFileVersion`,
+  `GetFormType`, `GetPageLabel`.
+- **Bitmap**: `CreateEx`, `RenderPageBitmapWithMatrix`, format detection.
+- **Page boxes**: `MediaBox`, `CropBox`, `BleedBox`, `TrimBox`, `ArtBox`.
+
+### Aggiunto — wrapper di alto livello
+
+- `Rpdfium::Document` ora espone: `metadata` (Title/Author/Producer/...),
+  `permissions` (hash di booleans per print/copy/modify/...), `file_version`,
+  `form_type`, `has_forms?`, `outline`, `attachments`, `page_label(idx)`.
+- `Rpdfium::Page` ora espone:
+  - `box(:media|:crop|:bleed|:trim|:art)`
+  - `chars(loose: false)` — array di hash con `char`, `codepoint`, bbox,
+    `origin_x/y`, `angle`, `fontsize`, `font`, `weight`, `render_mode`,
+    `generated`, `hyphen`, `unicode_error`
+  - `words(x_tolerance:, y_tolerance:)` — clustering layout-aware
+  - `text_in_bbox(left:, top:, right:, bottom:)` — top-down coords
+  - `line_segments` — segmenti vettoriali REALI dai path objects
+  - `horizontal_lines`, `vertical_lines` — derivati da `line_segments`
+  - `images` — `Image::Embedded` array
+  - `annotations`, `links`, `form_fields`
+  - `render(scale:, rotate:, output: :rgba|:bgra|:gray, include_annotations:,
+    include_forms:, background:)`
+  - `render_to_png(path)` — pure-Ruby, zero dipendenze esterne
+  - `search(query, **opts)` — internal full-text search
+- `Rpdfium::Image::Embedded` con `metadata`, `pixel_size`, `bbox`,
+  `filters`, `raw_bytes`, `decoded_bytes`, `render_bitmap`, `save(path)`
+  (passthrough JPEG quando il filter è `DCTDecode`).
+- `Rpdfium::Annotation` con `subtype`, `bbox`, `[]`, `link_uri`,
+  `link_dest_page`.
+- `Rpdfium::Form::{Environment, Field}` con tipi mappati (textfield,
+  checkbox, radiobutton, combobox, listbox, signature, ...) e
+  `readonly?`, `required?`, `checked?`, `options`.
+- `Rpdfium::Search` con `Enumerable`, ogni match include rects per riga.
+- `Rpdfium::Outline` con tree ricorsivo, `flatten` preorder, `to_h`.
+- `Rpdfium::Attachment` con `name`, `bytes`, `save(path)`.
+
+### Aggiunto — estrazione tabellare
+
+- Pipeline pdfplumber-style:
+  1. raccolta edges (strategie `:lines`, `:text`, `:explicit`,
+     `:lines_strict`)
+  2. snap (cluster collineari → coord media)
+  3. join (segmenti contigui → unico edge)
+  4. filter per `edge_min_length`
+  5. intersezioni h × v entro `intersection_tolerance`
+  6. costruzione celle (4 angoli intersezioni)
+  7. raggruppamento celle adiacenti (union-find) in tabelle
+  8. estrazione testo per cella via `FPDFText_GetBoundedText`
+- Tutti i parametri di pdfplumber supportati: `snap_tolerance` (con
+  varianti `_x`, `_y`), `join_tolerance`, `intersection_tolerance`,
+  `edge_min_length`, `min_words_vertical`, `min_words_horizontal`,
+  `text_tolerance`, `keep_blank_chars`.
+- `auto_fallback` opzionale: se `:lines` non produce nulla, riprova con
+  `:text`.
+- `Rpdfium::Table::Debugger.visualize(page, output_path)` — overlay
+  visivo (linee rosse, intersezioni verdi, tabelle blu trasparenti)
+  equivalente di `pdfplumber.Page.debug_tablefinder()`. Implementato in
+  Ruby puro con canvas RGBA, Bresenham, alpha blending.
+
+### Aggiunto — utility
+
+- `Rpdfium::IO::PNG` — writer PNG puro Ruby (zero deps), supporta
+  RGBA 8bpc. CRC32 corretti, deflate via stdlib `zlib`.
+- `Raw.read_utf16_string` helper centralizzato per il pattern
+  probe-then-fetch di PDFium (che ritorna stringhe UTF-16LE).
+
+### Cambiato
+
+- Coordinate top-down ovunque nelle API pubbliche (PDFium internamente
+  è bottom-up; conversione fatta una volta sola per evitare confusione).
+- Il documento mantiene una cache delle pagine: `doc.page(0)` ritorna
+  sempre la stessa istanza (le pagine sono read-only nel nostro modello).
+- Init/destroy della libreria ora è thread-safe (`Mutex`) e idempotente.
+- `Document#close` rilascia in cascata: form env → pagine cached → doc.
+
+## [0.1.0]
+
+Prima release: bindings minimali, text/render base, table extractor
+embrionale.