@effortlessmotion/pdf-to-md 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +157 -0
  3. package/bin/cli.js +9 -0
  4. package/dist/cjs/analyze.d.cts +35 -0
  5. package/dist/cjs/analyze.d.ts +35 -0
  6. package/dist/cjs/analyze.js +620 -0
  7. package/dist/cjs/analyze.js.map +1 -0
  8. package/dist/cjs/audit.d.cts +38 -0
  9. package/dist/cjs/audit.d.ts +38 -0
  10. package/dist/cjs/audit.js +252 -0
  11. package/dist/cjs/audit.js.map +1 -0
  12. package/dist/cjs/cli/audit.d.cts +3 -0
  13. package/dist/cjs/cli/audit.d.ts +3 -0
  14. package/dist/cjs/cli/audit.js +269 -0
  15. package/dist/cjs/cli/audit.js.map +1 -0
  16. package/dist/cjs/cli/extract.d.cts +3 -0
  17. package/dist/cjs/cli/extract.d.ts +3 -0
  18. package/dist/cjs/cli/extract.js +704 -0
  19. package/dist/cjs/cli/extract.js.map +1 -0
  20. package/dist/cjs/cli/index.d.cts +5 -0
  21. package/dist/cjs/cli/index.d.ts +5 -0
  22. package/dist/cjs/cli/index.js +58 -0
  23. package/dist/cjs/cli/index.js.map +1 -0
  24. package/dist/cjs/cli/render.d.cts +3 -0
  25. package/dist/cjs/cli/render.d.ts +3 -0
  26. package/dist/cjs/cli/render.js +361 -0
  27. package/dist/cjs/cli/render.js.map +1 -0
  28. package/dist/cjs/cli/types.d.cts +10 -0
  29. package/dist/cjs/cli/types.d.ts +10 -0
  30. package/dist/cjs/cli/types.js +7 -0
  31. package/dist/cjs/cli/types.js.map +1 -0
  32. package/dist/cjs/cli.d.cts +2 -0
  33. package/dist/cjs/cli.d.ts +2 -0
  34. package/dist/cjs/cli.js +345 -0
  35. package/dist/cjs/cli.js.map +1 -0
  36. package/dist/cjs/collect.d.cts +6 -0
  37. package/dist/cjs/collect.d.ts +6 -0
  38. package/dist/cjs/collect.js +370 -0
  39. package/dist/cjs/collect.js.map +1 -0
  40. package/dist/cjs/dict.d.cts +8 -0
  41. package/dist/cjs/dict.d.ts +8 -0
  42. package/dist/cjs/dict.js +55 -0
  43. package/dist/cjs/dict.js.map +1 -0
  44. package/dist/cjs/emit.d.cts +27 -0
  45. package/dist/cjs/emit.d.ts +27 -0
  46. package/dist/cjs/emit.js +187 -0
  47. package/dist/cjs/emit.js.map +1 -0
  48. package/dist/cjs/engines/tesseract.d.cts +30 -0
  49. package/dist/cjs/engines/tesseract.d.ts +30 -0
  50. package/dist/cjs/engines/tesseract.js +650 -0
  51. package/dist/cjs/engines/tesseract.js.map +1 -0
  52. package/dist/cjs/errors.d.cts +21 -0
  53. package/dist/cjs/errors.d.ts +21 -0
  54. package/dist/cjs/errors.js +124 -0
  55. package/dist/cjs/errors.js.map +1 -0
  56. package/dist/cjs/extract.d.cts +88 -0
  57. package/dist/cjs/extract.d.ts +88 -0
  58. package/dist/cjs/extract.js +436 -0
  59. package/dist/cjs/extract.js.map +1 -0
  60. package/dist/cjs/geometry.d.cts +63 -0
  61. package/dist/cjs/geometry.d.ts +63 -0
  62. package/dist/cjs/geometry.js +521 -0
  63. package/dist/cjs/geometry.js.map +1 -0
  64. package/dist/cjs/index.d.cts +15 -0
  65. package/dist/cjs/index.d.ts +15 -0
  66. package/dist/cjs/index.js +56 -0
  67. package/dist/cjs/index.js.map +1 -0
  68. package/dist/cjs/lines.d.cts +3 -0
  69. package/dist/cjs/lines.d.ts +3 -0
  70. package/dist/cjs/lines.js +181 -0
  71. package/dist/cjs/lines.js.map +1 -0
  72. package/dist/cjs/markdown.d.cts +2 -0
  73. package/dist/cjs/markdown.d.ts +2 -0
  74. package/dist/cjs/markdown.js +222 -0
  75. package/dist/cjs/markdown.js.map +1 -0
  76. package/dist/cjs/package.json +1 -0
  77. package/dist/cjs/page-marker.d.cts +16 -0
  78. package/dist/cjs/page-marker.d.ts +16 -0
  79. package/dist/cjs/page-marker.js +85 -0
  80. package/dist/cjs/page-marker.js.map +1 -0
  81. package/dist/cjs/pdf-open.d.cts +12 -0
  82. package/dist/cjs/pdf-open.d.ts +12 -0
  83. package/dist/cjs/pdf-open.js +257 -0
  84. package/dist/cjs/pdf-open.js.map +1 -0
  85. package/dist/cjs/raster.d.cts +26 -0
  86. package/dist/cjs/raster.d.ts +26 -0
  87. package/dist/cjs/raster.js +262 -0
  88. package/dist/cjs/raster.js.map +1 -0
  89. package/dist/cjs/render-analysis.d.cts +25 -0
  90. package/dist/cjs/render-analysis.d.ts +25 -0
  91. package/dist/cjs/render-analysis.js +319 -0
  92. package/dist/cjs/render-analysis.js.map +1 -0
  93. package/dist/cjs/report.d.cts +12 -0
  94. package/dist/cjs/report.d.ts +12 -0
  95. package/dist/cjs/report.js +392 -0
  96. package/dist/cjs/report.js.map +1 -0
  97. package/dist/cjs/resolve.d.cts +1 -0
  98. package/dist/cjs/resolve.d.ts +1 -0
  99. package/dist/cjs/resolve.js +18 -0
  100. package/dist/cjs/resolve.js.map +1 -0
  101. package/dist/cjs/types.d.cts +171 -0
  102. package/dist/cjs/types.d.ts +171 -0
  103. package/dist/cjs/types.js +9 -0
  104. package/dist/cjs/types.js.map +1 -0
  105. package/dist/cjs/validate.d.cts +14 -0
  106. package/dist/cjs/validate.d.ts +14 -0
  107. package/dist/cjs/validate.js +96 -0
  108. package/dist/cjs/validate.js.map +1 -0
  109. package/dist/esm/analyze.d.ts +35 -0
  110. package/dist/esm/analyze.js +270 -0
  111. package/dist/esm/analyze.js.map +1 -0
  112. package/dist/esm/audit.d.ts +38 -0
  113. package/dist/esm/audit.js +113 -0
  114. package/dist/esm/audit.js.map +1 -0
  115. package/dist/esm/cli/audit.d.ts +3 -0
  116. package/dist/esm/cli/audit.js +20 -0
  117. package/dist/esm/cli/audit.js.map +1 -0
  118. package/dist/esm/cli/extract.d.ts +3 -0
  119. package/dist/esm/cli/extract.js +313 -0
  120. package/dist/esm/cli/extract.js.map +1 -0
  121. package/dist/esm/cli/index.d.ts +5 -0
  122. package/dist/esm/cli/index.js +7 -0
  123. package/dist/esm/cli/index.js.map +1 -0
  124. package/dist/esm/cli/render.d.ts +3 -0
  125. package/dist/esm/cli/render.js +77 -0
  126. package/dist/esm/cli/render.js.map +1 -0
  127. package/dist/esm/cli/types.d.ts +10 -0
  128. package/dist/esm/cli/types.js +3 -0
  129. package/dist/esm/cli/types.js.map +1 -0
  130. package/dist/esm/cli.d.ts +2 -0
  131. package/dist/esm/cli.js +90 -0
  132. package/dist/esm/cli.js.map +1 -0
  133. package/dist/esm/collect.d.ts +6 -0
  134. package/dist/esm/collect.js +80 -0
  135. package/dist/esm/collect.js.map +1 -0
  136. package/dist/esm/dict.d.ts +8 -0
  137. package/dist/esm/dict.js +28 -0
  138. package/dist/esm/dict.js.map +1 -0
  139. package/dist/esm/emit.d.ts +27 -0
  140. package/dist/esm/emit.js +131 -0
  141. package/dist/esm/emit.js.map +1 -0
  142. package/dist/esm/engines/tesseract.d.ts +30 -0
  143. package/dist/esm/engines/tesseract.js +190 -0
  144. package/dist/esm/engines/tesseract.js.map +1 -0
  145. package/dist/esm/errors.d.ts +21 -0
  146. package/dist/esm/errors.js +9 -0
  147. package/dist/esm/errors.js.map +1 -0
  148. package/dist/esm/extract.d.ts +88 -0
  149. package/dist/esm/extract.js +147 -0
  150. package/dist/esm/extract.js.map +1 -0
  151. package/dist/esm/geometry.d.ts +63 -0
  152. package/dist/esm/geometry.js +279 -0
  153. package/dist/esm/geometry.js.map +1 -0
  154. package/dist/esm/index.d.ts +15 -0
  155. package/dist/esm/index.js +10 -0
  156. package/dist/esm/index.js.map +1 -0
  157. package/dist/esm/lines.d.ts +3 -0
  158. package/dist/esm/lines.js +67 -0
  159. package/dist/esm/lines.js.map +1 -0
  160. package/dist/esm/markdown.d.ts +2 -0
  161. package/dist/esm/markdown.js +153 -0
  162. package/dist/esm/markdown.js.map +1 -0
  163. package/dist/esm/package.json +1 -0
  164. package/dist/esm/page-marker.d.ts +16 -0
  165. package/dist/esm/page-marker.js +40 -0
  166. package/dist/esm/page-marker.js.map +1 -0
  167. package/dist/esm/pdf-open.d.ts +12 -0
  168. package/dist/esm/pdf-open.js +61 -0
  169. package/dist/esm/pdf-open.js.map +1 -0
  170. package/dist/esm/raster.d.ts +26 -0
  171. package/dist/esm/raster.js +60 -0
  172. package/dist/esm/raster.js.map +1 -0
  173. package/dist/esm/render-analysis.d.ts +25 -0
  174. package/dist/esm/render-analysis.js +115 -0
  175. package/dist/esm/render-analysis.js.map +1 -0
  176. package/dist/esm/report.d.ts +12 -0
  177. package/dist/esm/report.js +182 -0
  178. package/dist/esm/report.js.map +1 -0
  179. package/dist/esm/resolve.d.ts +1 -0
  180. package/dist/esm/resolve.js +7 -0
  181. package/dist/esm/resolve.js.map +1 -0
  182. package/dist/esm/types.d.ts +171 -0
  183. package/dist/esm/types.js +6 -0
  184. package/dist/esm/types.js.map +1 -0
  185. package/dist/esm/validate.d.ts +14 -0
  186. package/dist/esm/validate.js +56 -0
  187. package/dist/esm/validate.js.map +1 -0
  188. package/package.json +67 -0
  189. package/skills/pdf-to-md/SKILL.md +102 -0
@@ -0,0 +1,190 @@
1
+ // engines/tesseract.ts — THE OCR engine: tesseract.js on every platform.
2
+ //
3
+ // Seam contract: words come back in normalized 0-1 page coordinates, origin
4
+ // bottom-left, y increasing upward — the y-flip happens here, and nowhere else.
5
+ //
6
+ // Pure WASM, in-process, no native dependency: no crash containment needed.
7
+ import { mkdirSync } from 'node:fs';
8
+ import os from 'node:os';
9
+ import path from 'node:path';
10
+ import { createWorker, PSM } from 'tesseract.js';
11
+ import { foldTypographic } from '../lines.js';
12
+ import { awaitPdfOpen, openPdfForRender } from '../pdf-open.js';
13
+ import { renderLoadedPage } from '../raster.js';
14
+ import { resolvePackagePath } from '../resolve.js';
15
+ // 288 dpi: the render resolution the engine's word-overlap numbers were
16
+ // measured at (test/fixtures/ocr-engine-poc/) — the known-good operating point.
17
+ export const OCR_RENDER_DPI = 288;
18
+ // Chart pages starve PSM.AUTO (unrecognized text can't be marked for review).
19
+ // Prose-fraction retry trigger, measured (sparse-retry.test.ts): chart 0.442 vs prose 0.767-0.938, cut 0.6.
20
+ export const SPARSE_RETRY_PROSE_FRACTION = 0.6;
21
+ /** Share of `words` whose text contains a run of 3+ letters (`src/emit.ts`'s isUnstructured canary, applied per-page instead of per-block). */ function proseFraction(words) {
22
+ if (words.length === 0) return 0;
23
+ return words.filter((w)=>/[A-Za-z]{3}/.test(w.text)).length / words.length;
24
+ }
25
+ /** Does this page's PSM.AUTO pass look chart-like enough to re-recognize
26
+ * with PSM.SPARSE_TEXT? A page with 0 words never retries (nothing to take a prose fraction of). */ export function shouldRetrySparse(words) {
27
+ return words.length > 0 && proseFraction(words) < SPARSE_RETRY_PROSE_FRACTION;
28
+ }
29
+ // The locally installed traineddata (npm package @tesseract.js-data/eng),
30
+ // resolved dynamically so depcheck won't flag it "unused" — it's a genuine runtime dependency, listed in .depcheckrc's `ignores`.
31
+ const TESSDATA_DIR = path.join(path.dirname(resolvePackagePath('@tesseract.js-data/eng/package.json')), '4.0.0');
32
+ /** tesseract.js's nested blocks/paragraphs/lines/words -> this repo's flat Word contract (normalize + y-flip). Same shape regardless of which PSM produced `page`, so both the AUTO pass and the SPARSE_TEXT retry share it. */ function wordsFromPage(page, width, height) {
33
+ var _page_blocks;
34
+ const pageWords = [];
35
+ for (const block of (_page_blocks = page.blocks) !== null && _page_blocks !== void 0 ? _page_blocks : []){
36
+ var _block_paragraphs;
37
+ for (const para of (_block_paragraphs = block.paragraphs) !== null && _block_paragraphs !== void 0 ? _block_paragraphs : []){
38
+ var _para_lines;
39
+ for (const line of (_para_lines = para.lines) !== null && _para_lines !== void 0 ? _para_lines : []){
40
+ var _line_words;
41
+ for (const w of (_line_words = line.words) !== null && _line_words !== void 0 ? _line_words : []){
42
+ const { x0, y0, x1, y1 } = w.bbox;
43
+ pageWords.push({
44
+ // Same typographic folding as the text path (src/lines.ts) — both
45
+ // paths must agree on how a printed apostrophe is spelled.
46
+ text: foldTypographic(w.text),
47
+ x: x0 / width,
48
+ y: (height - y1) / height,
49
+ w: (x1 - x0) / width,
50
+ h: (y1 - y0) / height,
51
+ // Plumbed through unmodified — tesseract.js's own 0-100
52
+ // per-word confidence. See src/report.ts's LOW_CONFIDENCE_THRESHOLD.
53
+ confidence: w.confidence
54
+ });
55
+ }
56
+ }
57
+ }
58
+ }
59
+ return pageWords;
60
+ }
61
+ // tesseract.js-core's WASM build writes native diagnostics straight to this
62
+ // process's stdout/stderr, with no override to silence them at the source.
63
+ //
64
+ // Suppression must span the whole run: worker-thread stdio arrives
65
+ // asynchronously, on later event-loop turns; the synchronous carve-out below (`withRealStdio`) is the only safe exit.
66
+ let suppressDepth = 0;
67
+ let savedStdoutWrite = null;
68
+ let savedStderrWrite = null;
69
+ async function withSuppressedStdio(fn) {
70
+ if (suppressDepth === 0) {
71
+ savedStdoutWrite = process.stdout.write.bind(process.stdout);
72
+ savedStderrWrite = process.stderr.write.bind(process.stderr);
73
+ process.stdout.write = ()=>true;
74
+ process.stderr.write = ()=>true;
75
+ }
76
+ suppressDepth++;
77
+ try {
78
+ return await fn();
79
+ } finally{
80
+ suppressDepth--;
81
+ if (suppressDepth === 0) {
82
+ if (savedStdoutWrite) process.stdout.write = savedStdoutWrite;
83
+ if (savedStderrWrite) process.stderr.write = savedStderrWrite;
84
+ savedStdoutWrite = null;
85
+ savedStderrWrite = null;
86
+ }
87
+ }
88
+ }
89
+ /** Pierces an active `withSuppressedStdio` region SYNCHRONOUSLY to let this
90
+ * module's own onProgress/onWarning calls through. No-op outside any suppressed region. */ function withRealStdio(fn) {
91
+ if (suppressDepth === 0) return fn();
92
+ const realOut = savedStdoutWrite;
93
+ const realErr = savedStderrWrite;
94
+ if (realOut) process.stdout.write = realOut;
95
+ if (realErr) process.stderr.write = realErr;
96
+ try {
97
+ return fn();
98
+ } finally{
99
+ process.stdout.write = ()=>true;
100
+ process.stderr.write = ()=>true;
101
+ }
102
+ }
103
+ /** Recognize words on pages [first..last] of a PDF (renders at `dpi`,
104
+ * default OCR_RENDER_DPI). Progress via `onProgress`; diagnostics via `onWarning` — this module never writes to stdout/stderr itself. */ export async function recognizePdf(pdfPath, first, last, { dpi = OCR_RENDER_DPI, onProgress, onWarning } = {}) {
105
+ // tesseract.js writes its decompressed traineddata cache here by default,
106
+ // dropping a model file into the user's cwd — redirect it under tmpdir() instead.
107
+ const cachePath = path.join(os.tmpdir(), 'pdf-to-md-engine');
108
+ mkdirSync(cachePath, {
109
+ recursive: true
110
+ });
111
+ const words = [];
112
+ const emptyPages = [];
113
+ const msPerPage = new Map();
114
+ // ONE continuous suppressed region for the whole run; onProgress/onWarning
115
+ // below go through `withRealStdio`, the only sanctioned way out of it.
116
+ await withSuppressedStdio(async ()=>{
117
+ // OEM 1 (LSTM only, tesseract.js's own default): measured 99.0% recall
118
+ // on the hard benchmark pages (2026-08-16).
119
+ const worker = await createWorker('eng', 1, {
120
+ langPath: TESSDATA_DIR,
121
+ cachePath
122
+ });
123
+ try {
124
+ // NOT optional: tesseract.js's own default PSM (SINGLE_BLOCK) measured
125
+ // 3-8 percentage points worse than AUTO on two-column pages.
126
+ await worker.setParameters({
127
+ tessedit_pageseg_mode: PSM.AUTO
128
+ });
129
+ const loadingTask = openPdfForRender(pdfPath);
130
+ try {
131
+ const pdf = await awaitPdfOpen(loadingTask, pdfPath);
132
+ for(let pn = first; pn <= Math.min(last, pdf.numPages); pn++){
133
+ const t0 = Date.now();
134
+ const { png, width, height } = await renderLoadedPage(pdf, pn, dpi);
135
+ const { data } = await worker.recognize(png, {}, {
136
+ blocks: true
137
+ });
138
+ let pageWords = wordsFromPage(data, width, height);
139
+ // Adaptive second pass: re-recognizes the SAME rendered PNG, so
140
+ // this costs one extra recognize() call only on chart-like pages.
141
+ if (shouldRetrySparse(pageWords)) {
142
+ const autoFraction = proseFraction(pageWords);
143
+ const autoWords = pageWords;
144
+ // setParameters on the shared worker is reversible, so one
145
+ // in-process worker can alternate PSM per page instead of paying for a second worker.
146
+ await worker.setParameters({
147
+ tessedit_pageseg_mode: PSM.SPARSE_TEXT
148
+ });
149
+ const sparse = await worker.recognize(png, {}, {
150
+ blocks: true
151
+ });
152
+ const sparseWords = wordsFromPage(sparse.data, width, height);
153
+ await worker.setParameters({
154
+ tessedit_pageseg_mode: PSM.AUTO
155
+ });
156
+ if (sparseWords.length > autoWords.length) {
157
+ pageWords = sparseWords;
158
+ const autoCount = autoWords.length;
159
+ const sparseCount = sparseWords.length;
160
+ withRealStdio(()=>onWarning === null || onWarning === void 0 ? void 0 : onWarning(`p${pn}: chart-like page (prose fraction ${autoFraction.toFixed(2)}) — retried with sparse-text segmentation, ${autoCount} -> ${sparseCount} words`));
161
+ }
162
+ }
163
+ const ms = Date.now() - t0;
164
+ for (const w of pageWords)words.push({
165
+ page: pn,
166
+ ...w
167
+ });
168
+ if (pageWords.length === 0) emptyPages.push(pn);
169
+ msPerPage.set(pn, ms);
170
+ const wordCount = pageWords.length;
171
+ withRealStdio(()=>onProgress === null || onProgress === void 0 ? void 0 : onProgress({
172
+ type: 'page',
173
+ page: pn,
174
+ words: wordCount,
175
+ ms
176
+ }));
177
+ }
178
+ } finally{
179
+ await loadingTask.destroy();
180
+ }
181
+ } finally{
182
+ await worker.terminate();
183
+ }
184
+ });
185
+ return {
186
+ words,
187
+ emptyPages,
188
+ msPerPage
189
+ };
190
+ }
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["/Users/kevin/Projects/pdf-to-md/src/engines/tesseract.ts"],"sourcesContent":["// engines/tesseract.ts — THE OCR engine: tesseract.js on every platform.\n//\n// Seam contract: words come back in normalized 0-1 page coordinates, origin\n// bottom-left, y increasing upward — the y-flip happens here, and nowhere else.\n//\n// Pure WASM, in-process, no native dependency: no crash containment needed.\nimport { mkdirSync } from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\nimport type { Page as TesseractPage } from 'tesseract.js';\nimport { createWorker, PSM } from 'tesseract.js';\nimport type { PageWord, Word } from '../geometry.ts';\nimport { foldTypographic } from '../lines.ts';\nimport { awaitPdfOpen, openPdfForRender } from '../pdf-open.ts';\nimport { renderLoadedPage } from '../raster.ts';\nimport { resolvePackagePath } from '../resolve.ts';\n\n// 288 dpi: the render resolution the engine's word-overlap numbers were\n// measured at (test/fixtures/ocr-engine-poc/) — the known-good operating point.\nexport const OCR_RENDER_DPI = 288;\n\n// Chart pages starve PSM.AUTO (unrecognized text can't be marked for review).\n// Prose-fraction retry trigger, measured (sparse-retry.test.ts): chart 0.442 vs prose 0.767-0.938, cut 0.6.\nexport const SPARSE_RETRY_PROSE_FRACTION = 0.6;\n\n/** Share of `words` whose text contains a run of 3+ letters (`src/emit.ts`'s isUnstructured canary, applied per-page instead of per-block). */\nfunction proseFraction(words: { text: string }[]): number {\n if (words.length === 0) return 0;\n return words.filter((w) => /[A-Za-z]{3}/.test(w.text)).length / words.length;\n}\n\n/** Does this page's PSM.AUTO pass look chart-like enough to re-recognize\n * with PSM.SPARSE_TEXT? A page with 0 words never retries (nothing to take a prose fraction of). */\nexport function shouldRetrySparse(words: { text: string }[]): boolean {\n return words.length > 0 && proseFraction(words) < SPARSE_RETRY_PROSE_FRACTION;\n}\n\n// The locally installed traineddata (npm package @tesseract.js-data/eng),\n// resolved dynamically so depcheck won't flag it \"unused\" — it's a genuine runtime dependency, listed in .depcheckrc's `ignores`.\nconst TESSDATA_DIR = path.join(path.dirname(resolvePackagePath('@tesseract.js-data/eng/package.json')), '4.0.0');\n\n/** Per-page recognition progress, delivered once per page as it finishes.\n * Engine chatter goes through `onWarning`/`warnings` instead — this is timing/count data only. */\nexport type OcrProgressEvent = { type: 'page'; page: number; words: number; ms: number };\n\nexport interface RecognizeResult {\n words: PageWord[];\n /** pages (1-based) where the engine returned zero words */\n emptyPages: number[];\n /** wall-clock ms per page (render + recognize), keyed by page number */\n msPerPage: Map<number, number>;\n}\n\n/** tesseract.js's nested blocks/paragraphs/lines/words -> this repo's flat Word contract (normalize + y-flip). Same shape regardless of which PSM produced `page`, so both the AUTO pass and the SPARSE_TEXT retry share it. */\nfunction wordsFromPage(page: TesseractPage, width: number, height: number): Word[] {\n const pageWords: Word[] = [];\n for (const block of page.blocks ?? []) {\n for (const para of block.paragraphs ?? []) {\n for (const line of para.lines ?? []) {\n for (const w of line.words ?? []) {\n const { x0, y0, x1, y1 } = w.bbox;\n pageWords.push({\n // Same typographic folding as the text path (src/lines.ts) — both\n // paths must agree on how a printed apostrophe is spelled.\n text: foldTypographic(w.text),\n x: x0 / width,\n y: (height - y1) / height, // y-flip: top-left px -> bottom-left normalized\n w: (x1 - x0) / width,\n h: (y1 - y0) / height,\n // Plumbed through unmodified — tesseract.js's own 0-100\n // per-word confidence. See src/report.ts's LOW_CONFIDENCE_THRESHOLD.\n confidence: w.confidence,\n });\n }\n }\n }\n }\n return pageWords;\n}\n\n// tesseract.js-core's WASM build writes native diagnostics straight to this\n// process's stdout/stderr, with no override to silence them at the source.\n//\n// Suppression must span the whole run: worker-thread stdio arrives\n// asynchronously, on later event-loop turns; the synchronous carve-out below (`withRealStdio`) is the only safe exit.\nlet suppressDepth = 0;\nlet savedStdoutWrite: typeof process.stdout.write | null = null;\nlet savedStderrWrite: typeof process.stderr.write | null = null;\nasync function withSuppressedStdio<T>(fn: () => Promise<T>): Promise<T> {\n if (suppressDepth === 0) {\n savedStdoutWrite = process.stdout.write.bind(process.stdout);\n savedStderrWrite = process.stderr.write.bind(process.stderr);\n process.stdout.write = (() => true) as typeof process.stdout.write;\n process.stderr.write = (() => true) as typeof process.stderr.write;\n }\n suppressDepth++;\n try {\n return await fn();\n } finally {\n suppressDepth--;\n if (suppressDepth === 0) {\n if (savedStdoutWrite) process.stdout.write = savedStdoutWrite;\n if (savedStderrWrite) process.stderr.write = savedStderrWrite;\n savedStdoutWrite = null;\n savedStderrWrite = null;\n }\n }\n}\n\n/** Pierces an active `withSuppressedStdio` region SYNCHRONOUSLY to let this\n * module's own onProgress/onWarning calls through. No-op outside any suppressed region. */\nfunction withRealStdio<T>(fn: () => T): T {\n if (suppressDepth === 0) return fn();\n const realOut = savedStdoutWrite;\n const realErr = savedStderrWrite;\n if (realOut) process.stdout.write = realOut;\n if (realErr) process.stderr.write = realErr;\n try {\n return fn();\n } finally {\n process.stdout.write = (() => true) as typeof process.stdout.write;\n process.stderr.write = (() => true) as typeof process.stderr.write;\n }\n}\n\n/** Recognize words on pages [first..last] of a PDF (renders at `dpi`,\n * default OCR_RENDER_DPI). Progress via `onProgress`; diagnostics via `onWarning` — this module never writes to stdout/stderr itself. */\nexport async function recognizePdf(pdfPath: string, first: number, last: number, { dpi = OCR_RENDER_DPI, onProgress, onWarning }: { dpi?: number; onProgress?: (e: OcrProgressEvent) => void; onWarning?: (message: string) => void } = {}): Promise<RecognizeResult> {\n // tesseract.js writes its decompressed traineddata cache here by default,\n // dropping a model file into the user's cwd — redirect it under tmpdir() instead.\n const cachePath = path.join(os.tmpdir(), 'pdf-to-md-engine');\n mkdirSync(cachePath, { recursive: true });\n\n const words: PageWord[] = [];\n const emptyPages: number[] = [];\n const msPerPage = new Map<number, number>();\n\n // ONE continuous suppressed region for the whole run; onProgress/onWarning\n // below go through `withRealStdio`, the only sanctioned way out of it.\n await withSuppressedStdio(async () => {\n // OEM 1 (LSTM only, tesseract.js's own default): measured 99.0% recall\n // on the hard benchmark pages (2026-08-16).\n const worker = await createWorker('eng', 1, {\n langPath: TESSDATA_DIR,\n cachePath,\n });\n try {\n // NOT optional: tesseract.js's own default PSM (SINGLE_BLOCK) measured\n // 3-8 percentage points worse than AUTO on two-column pages.\n await worker.setParameters({ tessedit_pageseg_mode: PSM.AUTO });\n\n const loadingTask = openPdfForRender(pdfPath);\n try {\n const pdf = await awaitPdfOpen(loadingTask, pdfPath);\n for (let pn = first; pn <= Math.min(last, pdf.numPages); pn++) {\n const t0 = Date.now();\n const { png, width, height } = await renderLoadedPage(pdf, pn, dpi);\n const { data } = await worker.recognize(png, {}, { blocks: true });\n let pageWords: Word[] = wordsFromPage(data, width, height);\n\n // Adaptive second pass: re-recognizes the SAME rendered PNG, so\n // this costs one extra recognize() call only on chart-like pages.\n if (shouldRetrySparse(pageWords)) {\n const autoFraction = proseFraction(pageWords);\n const autoWords = pageWords;\n // setParameters on the shared worker is reversible, so one\n // in-process worker can alternate PSM per page instead of paying for a second worker.\n await worker.setParameters({ tessedit_pageseg_mode: PSM.SPARSE_TEXT });\n const sparse = await worker.recognize(png, {}, { blocks: true });\n const sparseWords = wordsFromPage(sparse.data, width, height);\n await worker.setParameters({ tessedit_pageseg_mode: PSM.AUTO });\n\n if (sparseWords.length > autoWords.length) {\n pageWords = sparseWords;\n const autoCount = autoWords.length;\n const sparseCount = sparseWords.length;\n withRealStdio(() => onWarning?.(`p${pn}: chart-like page (prose fraction ${autoFraction.toFixed(2)}) — retried with sparse-text segmentation, ${autoCount} -> ${sparseCount} words`));\n }\n }\n\n const ms = Date.now() - t0;\n for (const w of pageWords) words.push({ page: pn, ...w });\n if (pageWords.length === 0) emptyPages.push(pn);\n msPerPage.set(pn, ms);\n const wordCount = pageWords.length;\n withRealStdio(() => onProgress?.({ type: 'page', page: pn, words: wordCount, ms }));\n }\n } finally {\n await loadingTask.destroy();\n }\n } finally {\n await worker.terminate();\n }\n });\n\n return { words, emptyPages, msPerPage };\n}\n"],"names":["mkdirSync","os","path","createWorker","PSM","foldTypographic","awaitPdfOpen","openPdfForRender","renderLoadedPage","resolvePackagePath","OCR_RENDER_DPI","SPARSE_RETRY_PROSE_FRACTION","proseFraction","words","length","filter","w","test","text","shouldRetrySparse","TESSDATA_DIR","join","dirname","wordsFromPage","page","width","height","pageWords","block","blocks","para","paragraphs","line","lines","x0","y0","x1","y1","bbox","push","x","y","h","confidence","suppressDepth","savedStdoutWrite","savedStderrWrite","withSuppressedStdio","fn","process","stdout","write","bind","stderr","withRealStdio","realOut","realErr","recognizePdf","pdfPath","first","last","dpi","onProgress","onWarning","cachePath","tmpdir","recursive","emptyPages","msPerPage","Map","worker","langPath","setParameters","tessedit_pageseg_mode","AUTO","loadingTask","pdf","pn","Math","min","numPages","t0","Date","now","png","data","recognize","autoFraction","autoWords","SPARSE_TEXT","sparse","sparseWords","autoCount","sparseCount","toFixed","ms","set","wordCount","type","destroy","terminate"],"mappings":"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"}
@@ -0,0 +1,21 @@
1
+ /** The closed set of error codes every `PdfToMdError` carries — switch on
2
+ * `code` instead of parsing `message`. */
3
+ export type PdfToMdErrorCode =
4
+ /** input missing/unreadable/not a PDF */
5
+ 'PDF_OPEN'
6
+ /** malformed page selection (validated before any work) */
7
+ | 'PAGE_RANGE'
8
+ /** rendering an opened, in-range page to PNG failed */
9
+ | 'PAGE_RENDER'
10
+ /** the OCR engine crashed twice on one page (message names it) */
11
+ | 'OCR_PAGE_FAILED'
12
+ /** malformed word-dump input (--words-json / extractOcr words) */
13
+ | 'WORDS_INPUT'
14
+ /** malformed Analysis handed to toMarkdown/toText (e.g. an out-of-range
15
+ * wordIndexes entry) — validated fail-fast, whole object checked before any output. */
16
+ | 'ANALYSIS_INPUT';
17
+ /** The error every entry point throws — never a bare `Error`. */
18
+ export declare class PdfToMdError extends Error {
19
+ code: PdfToMdErrorCode;
20
+ constructor(code: PdfToMdErrorCode, message: string);
21
+ }
@@ -0,0 +1,9 @@
1
+ // Library code throws; only src/cli.ts prints and exits.
2
+ /** The closed set of error codes every `PdfToMdError` carries — switch on
3
+ * `code` instead of parsing `message`. */ /** The error every entry point throws — never a bare `Error`. */ export class PdfToMdError extends Error {
4
+ constructor(code, message){
5
+ super(message);
6
+ this.name = 'PdfToMdError';
7
+ this.code = code;
8
+ }
9
+ }
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["/Users/kevin/Projects/pdf-to-md/src/errors.ts"],"sourcesContent":["// Library code throws; only src/cli.ts prints and exits.\n\n/** The closed set of error codes every `PdfToMdError` carries — switch on\n * `code` instead of parsing `message`. */\nexport type PdfToMdErrorCode =\n /** input missing/unreadable/not a PDF */\n | 'PDF_OPEN'\n /** malformed page selection (validated before any work) */\n | 'PAGE_RANGE'\n /** rendering an opened, in-range page to PNG failed */\n | 'PAGE_RENDER'\n /** the OCR engine crashed twice on one page (message names it) */\n | 'OCR_PAGE_FAILED'\n /** malformed word-dump input (--words-json / extractOcr words) */\n | 'WORDS_INPUT'\n /** malformed Analysis handed to toMarkdown/toText (e.g. an out-of-range\n * wordIndexes entry) — validated fail-fast, whole object checked before any output. */\n | 'ANALYSIS_INPUT';\n\n/** The error every entry point throws — never a bare `Error`. */\nexport class PdfToMdError extends Error {\n code: PdfToMdErrorCode;\n\n constructor(code: PdfToMdErrorCode, message: string) {\n super(message);\n this.name = 'PdfToMdError';\n this.code = code;\n }\n}\n"],"names":["PdfToMdError","Error","code","message","name"],"mappings":"AAAA,yDAAyD;AAEzD;wCACwC,GAgBxC,+DAA+D,GAC/D,OAAO,MAAMA,qBAAqBC;IAGhC,YAAYC,IAAsB,EAAEC,OAAe,CAAE;QACnD,KAAK,CAACA;QACN,IAAI,CAACC,IAAI,GAAG;QACZ,IAAI,CAACF,IAAI,GAAGA;IACd;AACF"}
@@ -0,0 +1,88 @@
1
+ import type { OcrProgressEvent } from './engines/tesseract.js';
2
+ import type { PageWord, Tuning } from './geometry.js';
3
+ import type { Report } from './types.js';
4
+ export type { OcrProgressEvent } from './engines/tesseract.js';
5
+ /** One recognized word with its page — the OCR replay input contract (same
6
+ * shape as `geometry.ts`'s `PageWord`, re-exported under this module's public name). */
7
+ export type OcrWordInput = PageWord;
8
+ /** A 1-based, inclusive page range — the shape every entry point's `pages`
9
+ * option takes (the CLI's own `--pages N[-M]` parses into this). */
10
+ export interface PageSelection {
11
+ first: number;
12
+ /** inclusive; defaults to `first` */
13
+ last?: number;
14
+ }
15
+ /** extractText/extractOcr/pdfToMarkdown's common return shape. */
16
+ export interface ExtractResult {
17
+ markdown: string;
18
+ /** per-document and per-page QA metrics — see `Report` (`src/types.ts`) */
19
+ report: Report;
20
+ /** every notice also delivered incrementally via `onWarning`, collected
21
+ * here in full (hybrid pages, auto-OCR-fallback, empty OCR pages, sparse-retry) */
22
+ warnings: string[];
23
+ }
24
+ interface CommonOptions {
25
+ /** convert only this page range (1-based, inclusive); defaults to the
26
+ * whole document */
27
+ pages?: PageSelection;
28
+ /** delivered as each warning happens (also returned, in full, as
29
+ * `warnings` on the resolved result) */
30
+ onWarning?: (message: string) => void;
31
+ }
32
+ /** Options for {@link extractText}. */
33
+ export interface ExtractTextOptions extends CommonOptions {
34
+ /** emit a `### pN` marker before each page's content (output formatting
35
+ * only — `report.pageStats` is always populated regardless) */
36
+ pageMarkers?: boolean;
37
+ }
38
+ /** Options for {@link extractOcr}. */
39
+ export interface ExtractOcrOptions extends CommonOptions {
40
+ /** override any subset of the OCR-path geometry defaults — see
41
+ * DEFAULT_TUNING (`src/geometry.ts`) for each knob's measured default */
42
+ tuning?: Partial<Tuning>;
43
+ /** page-render resolution for engine recognition (default 288, measured;
44
+ * >~400 measured WORSE on ordinary pages — not a "bigger is safer" knob) */
45
+ dpi?: number;
46
+ /** marks report.ocrFallback — set by pdfToMarkdown's auto-fallback */
47
+ fallback?: boolean;
48
+ /** one event per page as recognition finishes (timing/count only — engine
49
+ * chatter and the sparse-retry notice arrive via `onWarning` instead) */
50
+ onProgress?: (e: OcrProgressEvent) => void;
51
+ /** every recognized word entering the geometry, delivered once after
52
+ * recognition — the severity-1 audit instrument (--debug-words) */
53
+ onWords?: (words: OcrWordInput[]) => void;
54
+ }
55
+ /** Options for {@link pdfToMarkdown}. */
56
+ export interface PdfToMarkdownOptions extends ExtractTextOptions, Omit<ExtractOcrOptions, 'fallback'> {
57
+ /** force the OCR path even when a text layer exists */
58
+ ocr?: boolean;
59
+ /** never fall back to OCR, even for image-only pages */
60
+ noOcr?: boolean;
61
+ }
62
+ export declare function extractText(pdfPath: string, opts?: ExtractTextOptions): Promise<ExtractResult>;
63
+ /**
64
+ * OCR extraction. Input is either a PDF (pages render at `dpi` and the
65
+ * engine recognizes them, imported lazily) or an already-recognized word dump (the offline replay input — see `--words-json`).
66
+ *
67
+ * @param input `{ pdfPath }` to recognize, or `{ words }` to replay a dump
68
+ * @param opts see {@link ExtractOcrOptions}
69
+ */
70
+ export declare function extractOcr(input: {
71
+ pdfPath: string;
72
+ } | {
73
+ words: OcrWordInput[];
74
+ }, opts?: ExtractOcrOptions): Promise<ExtractResult>;
75
+ /** pdfToMarkdown's auto-OCR fallback predicate, shared with the CLI's
76
+ * --format=raw|txt path so the two call sites can never drift apart. Module-internal: not re-exported by `src/index.ts`. */
77
+ export declare function needsOcrFallback(charsPerPage: number): boolean;
78
+ /** The exact stderr/warnings notice printed when needsOcrFallback fires —
79
+ * one copy of the string for both call sites (asserted verbatim by the suite). */
80
+ export declare function ocrFallbackNotice(charsPerPage: number): string;
81
+ /**
82
+ * The headline API: extract a PDF to markdown, text layer first, falling
83
+ * back to OCR when the text layer is empty enough the pages are certainly images of text (< `AUTO_OCR_CHARS_PER_PAGE` chars/page) — the same decision the CLI makes.
84
+ *
85
+ * @param pdfPath path to the PDF file
86
+ * @param opts see {@link PdfToMarkdownOptions}
87
+ */
88
+ export declare function pdfToMarkdown(pdfPath: string, opts?: PdfToMarkdownOptions): Promise<ExtractResult>;
@@ -0,0 +1,147 @@
1
+ // The library layer for PDF -> markdown conversion: extractText/extractOcr/
2
+ // pdfToMarkdown each take plain args, return plain data, and throw PdfToMdError — no process.exit, no console.*, no file writing.
3
+ //
4
+ // Warnings are DATA: every notice is returned in `warnings` verbatim and also
5
+ // delivered incrementally via `onWarning` — the exact strings are load-bearing (the test suite asserts them).
6
+ import { buildOcrAnalysisPages } from './analyze.js';
7
+ import { collect } from './collect.js';
8
+ import { dictAvailable, dictUnavailableWarning } from './dict.js';
9
+ import { toLines } from './lines.js';
10
+ import { buildMarkdown } from './markdown.js';
11
+ import { renderPagesToMarkdown } from './render-analysis.js';
12
+ import { AUTO_OCR_CHARS_PER_PAGE, buildOcrReport, buildReport } from './report.js';
13
+ import { validatePages } from './validate.js';
14
+ /**
15
+ * Text-layer extraction. Returns markdown + QA report + warnings (hybrid
16
+ * pages carrying large images whose baked-in text the text layer can never see). Makes no OCR decision — see pdfToMarkdown for the fallback.
17
+ *
18
+ * @param pdfPath path to the PDF file
19
+ * @param opts see {@link ExtractTextOptions}
20
+ */ // One collector per entry point: collects into `warnings`, streams via
21
+ // onWarning, and emits the dictionary-unavailable notice exactly once up front.
22
+ function warnCollector(onWarning) {
23
+ const warnings = [];
24
+ const warn = (m)=>{
25
+ warnings.push(m);
26
+ onWarning === null || onWarning === void 0 ? void 0 : onWarning(m);
27
+ };
28
+ if (!dictAvailable()) warn(dictUnavailableWarning());
29
+ return {
30
+ warnings,
31
+ warn
32
+ };
33
+ }
34
+ export async function extractText(pdfPath, opts = {}) {
35
+ var _opts_pages_last, _opts_pageMarkers;
36
+ validatePages(opts.pages);
37
+ const { warnings, warn } = warnCollector(opts.onWarning);
38
+ const range = opts.pages ? {
39
+ first: opts.pages.first,
40
+ last: (_opts_pages_last = opts.pages.last) !== null && _opts_pages_last !== void 0 ? _opts_pages_last : opts.pages.first
41
+ } : {};
42
+ const { numPages, pages, heightChars } = await collect(pdfPath, range);
43
+ const pageLines = pages.map((p)=>({
44
+ page: p.page,
45
+ lines: toLines(p)
46
+ }));
47
+ const pageMarkers = (_opts_pageMarkers = opts.pageMarkers) !== null && _opts_pageMarkers !== void 0 ? _opts_pageMarkers : false;
48
+ const { md, stats, bodyH, headingSizes } = buildMarkdown(pageLines, heightChars, {
49
+ pageMarkers
50
+ });
51
+ // pageStats needs "### pN" markers to segment content; when the caller
52
+ // didn't request them, build a throwaway marked variant (same heightChars) purely to measure stats from, so pageStats is always populated.
53
+ const statsMd = pageMarkers ? md : buildMarkdown(pageLines, heightChars, {
54
+ pageMarkers: true
55
+ }).md;
56
+ // Advisory, not prescriptive: `hasLargeImage` fires on any large image,
57
+ // even one with no baked-in text, where `--ocr` recovers nothing and can
58
+ // actively degrade a correct result (measured: "I" -> "|", stray em-dashes) — so this tells the caller to COMPARE the OCR rerun, never blindly replace.
59
+ const hybridPages = pages.filter((p)=>p.largeImage).map((p)=>p.page);
60
+ for (const n of hybridPages){
61
+ warn(`p${n}: text layer used but page carries large image(s); if it has baked-in text this output won't have it — compare (don't blindly replace) against --pages ${n} --ocr, which can itself introduce errors`);
62
+ }
63
+ const report = buildReport({
64
+ numPages,
65
+ md,
66
+ statsMd,
67
+ stats,
68
+ bodyH,
69
+ headingSizes,
70
+ hybridPages
71
+ });
72
+ return {
73
+ markdown: md,
74
+ report,
75
+ warnings
76
+ };
77
+ }
78
+ /**
79
+ * OCR extraction. Input is either a PDF (pages render at `dpi` and the
80
+ * engine recognizes them, imported lazily) or an already-recognized word dump (the offline replay input — see `--words-json`).
81
+ *
82
+ * @param input `{ pdfPath }` to recognize, or `{ words }` to replay a dump
83
+ * @param opts see {@link ExtractOcrOptions}
84
+ */ export async function extractOcr(input, opts = {}) {
85
+ validatePages(opts.pages);
86
+ const { warnings, warn } = warnCollector(opts.onWarning);
87
+ // Shared with analyze(pdf, {path:'ocr'}) — see that module's header for
88
+ // why this makes the two byte-identical by construction, not by hand.
89
+ const { pages, words } = await buildOcrAnalysisPages(input, opts, warn);
90
+ const md = renderPagesToMarkdown(pages, {
91
+ forcePageMarkers: true,
92
+ pageMarkers: true
93
+ });
94
+ const report = buildOcrReport({
95
+ md,
96
+ fallback: opts.fallback,
97
+ // Confidence is on `words` — see report.ts's low-confidence detector for
98
+ // how it handles a confidence-less replay honestly.
99
+ words
100
+ });
101
+ return {
102
+ markdown: md,
103
+ report,
104
+ warnings
105
+ };
106
+ }
107
+ /** pdfToMarkdown's auto-OCR fallback predicate, shared with the CLI's
108
+ * --format=raw|txt path so the two call sites can never drift apart. Module-internal: not re-exported by `src/index.ts`. */ export function needsOcrFallback(charsPerPage) {
109
+ return charsPerPage < AUTO_OCR_CHARS_PER_PAGE;
110
+ }
111
+ /** The exact stderr/warnings notice printed when needsOcrFallback fires —
112
+ * one copy of the string for both call sites (asserted verbatim by the suite). */ export function ocrFallbackNotice(charsPerPage) {
113
+ return `text layer yields ~${charsPerPage} chars/page (< ${AUTO_OCR_CHARS_PER_PAGE}) — pages are images of text; falling back to OCR (suppress with --no-ocr)`;
114
+ }
115
+ /**
116
+ * The headline API: extract a PDF to markdown, text layer first, falling
117
+ * back to OCR when the text layer is empty enough the pages are certainly images of text (< `AUTO_OCR_CHARS_PER_PAGE` chars/page) — the same decision the CLI makes.
118
+ *
119
+ * @param pdfPath path to the PDF file
120
+ * @param opts see {@link PdfToMarkdownOptions}
121
+ */ export async function pdfToMarkdown(pdfPath, opts = {}) {
122
+ var _opts_onWarning;
123
+ if (opts.ocr) return extractOcr({
124
+ pdfPath
125
+ }, opts);
126
+ // Warning DELIVERY is deferred on the text pass: if the fallback fires,
127
+ // those hybrid warnings describe output being discarded, so only a kept text result replays them.
128
+ const text = await extractText(pdfPath, {
129
+ ...opts,
130
+ onWarning: undefined
131
+ });
132
+ if (needsOcrFallback(text.report.charsPerPage) && !opts.noOcr) {
133
+ var _opts_onWarning1;
134
+ const notice = ocrFallbackNotice(text.report.charsPerPage);
135
+ (_opts_onWarning1 = opts.onWarning) === null || _opts_onWarning1 === void 0 ? void 0 : _opts_onWarning1.call(opts, notice);
136
+ const ocr = await extractOcr({
137
+ pdfPath
138
+ }, {
139
+ ...opts,
140
+ fallback: true
141
+ });
142
+ ocr.warnings.unshift(notice);
143
+ return ocr;
144
+ }
145
+ for (const w of text.warnings)(_opts_onWarning = opts.onWarning) === null || _opts_onWarning === void 0 ? void 0 : _opts_onWarning.call(opts, w);
146
+ return text;
147
+ }
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["/Users/kevin/Projects/pdf-to-md/src/extract.ts"],"sourcesContent":["// The library layer for PDF -> markdown conversion: extractText/extractOcr/\n// pdfToMarkdown each take plain args, return plain data, and throw PdfToMdError — no process.exit, no console.*, no file writing.\n//\n// Warnings are DATA: every notice is returned in `warnings` verbatim and also\n// delivered incrementally via `onWarning` — the exact strings are load-bearing (the test suite asserts them).\nimport { buildOcrAnalysisPages } from './analyze.ts';\nimport { collect } from './collect.ts';\nimport { dictAvailable, dictUnavailableWarning } from './dict.ts';\nimport type { OcrProgressEvent } from './engines/tesseract.ts';\nimport type { PageWord, Tuning } from './geometry.ts';\nimport { toLines } from './lines.ts';\nimport { buildMarkdown } from './markdown.ts';\nimport { renderPagesToMarkdown } from './render-analysis.ts';\nimport { AUTO_OCR_CHARS_PER_PAGE, buildOcrReport, buildReport } from './report.ts';\nimport type { PageLines, Report } from './types.ts';\nimport { validatePages } from './validate.ts';\n\nexport type { OcrProgressEvent } from './engines/tesseract.ts';\n\n// A plain-JS caller (or `.ts` with `as any`) gets no compile-time check on\n// `pages`, so it's validated once at runtime — see src/validate.ts's `validatePages`.\n\n/** One recognized word with its page — the OCR replay input contract (same\n * shape as `geometry.ts`'s `PageWord`, re-exported under this module's public name). */\nexport type OcrWordInput = PageWord;\n\n/** A 1-based, inclusive page range — the shape every entry point's `pages`\n * option takes (the CLI's own `--pages N[-M]` parses into this). */\nexport interface PageSelection {\n first: number;\n /** inclusive; defaults to `first` */\n last?: number;\n}\n\n/** extractText/extractOcr/pdfToMarkdown's common return shape. */\nexport interface ExtractResult {\n markdown: string;\n /** per-document and per-page QA metrics — see `Report` (`src/types.ts`) */\n report: Report;\n /** every notice also delivered incrementally via `onWarning`, collected\n * here in full (hybrid pages, auto-OCR-fallback, empty OCR pages, sparse-retry) */\n warnings: string[];\n}\n\ninterface CommonOptions {\n /** convert only this page range (1-based, inclusive); defaults to the\n * whole document */\n pages?: PageSelection;\n /** delivered as each warning happens (also returned, in full, as\n * `warnings` on the resolved result) */\n onWarning?: (message: string) => void;\n}\n\n/** Options for {@link extractText}. */\nexport interface ExtractTextOptions extends CommonOptions {\n /** emit a `### pN` marker before each page's content (output formatting\n * only — `report.pageStats` is always populated regardless) */\n pageMarkers?: boolean;\n}\n\n/** Options for {@link extractOcr}. */\nexport interface ExtractOcrOptions extends CommonOptions {\n /** override any subset of the OCR-path geometry defaults — see\n * DEFAULT_TUNING (`src/geometry.ts`) for each knob's measured default */\n tuning?: Partial<Tuning>;\n /** page-render resolution for engine recognition (default 288, measured;\n * >~400 measured WORSE on ordinary pages — not a \"bigger is safer\" knob) */\n dpi?: number;\n /** marks report.ocrFallback — set by pdfToMarkdown's auto-fallback */\n fallback?: boolean;\n /** one event per page as recognition finishes (timing/count only — engine\n * chatter and the sparse-retry notice arrive via `onWarning` instead) */\n onProgress?: (e: OcrProgressEvent) => void;\n /** every recognized word entering the geometry, delivered once after\n * recognition — the severity-1 audit instrument (--debug-words) */\n onWords?: (words: OcrWordInput[]) => void;\n}\n\n/** Options for {@link pdfToMarkdown}. */\nexport interface PdfToMarkdownOptions extends ExtractTextOptions, Omit<ExtractOcrOptions, 'fallback'> {\n /** force the OCR path even when a text layer exists */\n ocr?: boolean;\n /** never fall back to OCR, even for image-only pages */\n noOcr?: boolean;\n}\n\n/**\n * Text-layer extraction. Returns markdown + QA report + warnings (hybrid\n * pages carrying large images whose baked-in text the text layer can never see). Makes no OCR decision — see pdfToMarkdown for the fallback.\n *\n * @param pdfPath path to the PDF file\n * @param opts see {@link ExtractTextOptions}\n */\n// One collector per entry point: collects into `warnings`, streams via\n// onWarning, and emits the dictionary-unavailable notice exactly once up front.\nfunction warnCollector(onWarning?: (message: string) => void): { warnings: string[]; warn: (m: string) => void } {\n const warnings: string[] = [];\n const warn = (m: string) => {\n warnings.push(m);\n onWarning?.(m);\n };\n if (!dictAvailable()) warn(dictUnavailableWarning());\n return { warnings, warn };\n}\n\nexport async function extractText(pdfPath: string, opts: ExtractTextOptions = {}): Promise<ExtractResult> {\n validatePages(opts.pages);\n const { warnings, warn } = warnCollector(opts.onWarning);\n\n const range = opts.pages ? { first: opts.pages.first, last: opts.pages.last ?? opts.pages.first } : {};\n const { numPages, pages, heightChars } = await collect(pdfPath, range);\n const pageLines: PageLines[] = pages.map((p) => ({\n page: p.page,\n lines: toLines(p),\n }));\n const pageMarkers = opts.pageMarkers ?? false;\n const { md, stats, bodyH, headingSizes } = buildMarkdown(pageLines, heightChars, { pageMarkers });\n // pageStats needs \"### pN\" markers to segment content; when the caller\n // didn't request them, build a throwaway marked variant (same heightChars) purely to measure stats from, so pageStats is always populated.\n const statsMd = pageMarkers ? md : buildMarkdown(pageLines, heightChars, { pageMarkers: true }).md;\n\n // Advisory, not prescriptive: `hasLargeImage` fires on any large image,\n // even one with no baked-in text, where `--ocr` recovers nothing and can\n // actively degrade a correct result (measured: \"I\" -> \"|\", stray em-dashes) — so this tells the caller to COMPARE the OCR rerun, never blindly replace.\n const hybridPages = pages.filter((p) => p.largeImage).map((p) => p.page);\n for (const n of hybridPages) {\n warn(`p${n}: text layer used but page carries large image(s); if it has baked-in text this output won't have it — compare (don't blindly replace) against --pages ${n} --ocr, which can itself introduce errors`);\n }\n\n const report = buildReport({\n numPages,\n md,\n statsMd,\n stats,\n bodyH,\n headingSizes,\n hybridPages,\n });\n return { markdown: md, report, warnings };\n}\n\n/**\n * OCR extraction. Input is either a PDF (pages render at `dpi` and the\n * engine recognizes them, imported lazily) or an already-recognized word dump (the offline replay input — see `--words-json`).\n *\n * @param input `{ pdfPath }` to recognize, or `{ words }` to replay a dump\n * @param opts see {@link ExtractOcrOptions}\n */\nexport async function extractOcr(input: { pdfPath: string } | { words: OcrWordInput[] }, opts: ExtractOcrOptions = {}): Promise<ExtractResult> {\n validatePages(opts.pages);\n const { warnings, warn } = warnCollector(opts.onWarning);\n\n // Shared with analyze(pdf, {path:'ocr'}) — see that module's header for\n // why this makes the two byte-identical by construction, not by hand.\n const { pages, words } = await buildOcrAnalysisPages(input, opts, warn);\n const md = renderPagesToMarkdown(pages, { forcePageMarkers: true, pageMarkers: true });\n\n const report = buildOcrReport({\n md,\n fallback: opts.fallback,\n // Confidence is on `words` — see report.ts's low-confidence detector for\n // how it handles a confidence-less replay honestly.\n words,\n });\n return { markdown: md, report, warnings };\n}\n\n/** pdfToMarkdown's auto-OCR fallback predicate, shared with the CLI's\n * --format=raw|txt path so the two call sites can never drift apart. Module-internal: not re-exported by `src/index.ts`. */\nexport function needsOcrFallback(charsPerPage: number): boolean {\n return charsPerPage < AUTO_OCR_CHARS_PER_PAGE;\n}\n\n/** The exact stderr/warnings notice printed when needsOcrFallback fires —\n * one copy of the string for both call sites (asserted verbatim by the suite). */\nexport function ocrFallbackNotice(charsPerPage: number): string {\n return `text layer yields ~${charsPerPage} chars/page (< ${AUTO_OCR_CHARS_PER_PAGE}) — pages are images of text; falling back to OCR (suppress with --no-ocr)`;\n}\n\n/**\n * The headline API: extract a PDF to markdown, text layer first, falling\n * back to OCR when the text layer is empty enough the pages are certainly images of text (< `AUTO_OCR_CHARS_PER_PAGE` chars/page) — the same decision the CLI makes.\n *\n * @param pdfPath path to the PDF file\n * @param opts see {@link PdfToMarkdownOptions}\n */\nexport async function pdfToMarkdown(pdfPath: string, opts: PdfToMarkdownOptions = {}): Promise<ExtractResult> {\n if (opts.ocr) return extractOcr({ pdfPath }, opts);\n\n // Warning DELIVERY is deferred on the text pass: if the fallback fires,\n // those hybrid warnings describe output being discarded, so only a kept text result replays them.\n const text = await extractText(pdfPath, { ...opts, onWarning: undefined });\n if (needsOcrFallback(text.report.charsPerPage) && !opts.noOcr) {\n const notice = ocrFallbackNotice(text.report.charsPerPage);\n opts.onWarning?.(notice);\n const ocr = await extractOcr({ pdfPath }, { ...opts, fallback: true });\n ocr.warnings.unshift(notice);\n return ocr;\n }\n for (const w of text.warnings) opts.onWarning?.(w);\n return text;\n}\n"],"names":["buildOcrAnalysisPages","collect","dictAvailable","dictUnavailableWarning","toLines","buildMarkdown","renderPagesToMarkdown","AUTO_OCR_CHARS_PER_PAGE","buildOcrReport","buildReport","validatePages","warnCollector","onWarning","warnings","warn","m","push","extractText","pdfPath","opts","pages","range","first","last","numPages","heightChars","pageLines","map","p","page","lines","pageMarkers","md","stats","bodyH","headingSizes","statsMd","hybridPages","filter","largeImage","n","report","markdown","extractOcr","input","words","forcePageMarkers","fallback","needsOcrFallback","charsPerPage","ocrFallbackNotice","pdfToMarkdown","ocr","text","undefined","noOcr","notice","unshift","w"],"mappings":"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"}
@@ -0,0 +1,63 @@
1
+ export interface Word {
2
+ text: string;
3
+ x: number;
4
+ y: number;
5
+ w: number;
6
+ h: number;
7
+ confidence?: number;
8
+ }
9
+ /** A `Word` with its page number — the shared shape behind both the OCR
10
+ * engine's own output (tesseract.ts) and the replay input contract (extract.ts's OcrWordInput). */
11
+ export interface PageWord extends Word {
12
+ page: number;
13
+ }
14
+ export interface OcrLine {
15
+ text: string;
16
+ x: number;
17
+ width: number;
18
+ midY: number;
19
+ h: number;
20
+ col: number;
21
+ words: Word[];
22
+ }
23
+ export interface PageOCR {
24
+ lines: OcrLine[];
25
+ floats: OcrLine[];
26
+ pitch: number;
27
+ }
28
+ /** Tuning knobs for the OCR-path geometry pass (CLI: `--float-*`/`--para-gap`/
29
+ * `--heading-scale`/`--col-*`/`--line-*`). See DEFAULT_TUNING for defaults. */
30
+ export interface Tuning {
31
+ /** fragments with more words than this are body text, not decoration */
32
+ floatMaxWords: number;
33
+ /** fraction of page width above which a fragment is too wide to be
34
+ * decoration */
35
+ floatMaxWidth: number;
36
+ /** how far a fragment's left edge must sit from its column edge to be
37
+ * decoration */
38
+ floatMargin: number;
39
+ /** a vertical gap this many times the line pitch is a paragraph break */
40
+ paraGap: number;
41
+ /** lines taller than this times body height are headings */
42
+ headingScale: number;
43
+ /** boxes wider than this are excluded from gutter detection */
44
+ colMaxWidth: number;
45
+ /** fractional x of the two-column midpoint */
46
+ colSplit: number;
47
+ /** vertical distance within which two boxes are the same line */
48
+ lineYTol: number;
49
+ /** same-line boxes with a larger height ratio don't merge */
50
+ lineHeightRatio: number;
51
+ }
52
+ /** Measured defaults; derivation in `test/unit/tuning.test.ts`. lineHeightRatio
53
+ * 2.4 = pair-F1 plateau edge (0.924@1.6 -> 0.995@2.4, 9,471 pairs, 2026-08-16). */
54
+ export declare const DEFAULT_TUNING: Tuning;
55
+ export declare const MAX_GUTTER_INK_FRAC = 0.03;
56
+ export declare const MIN_COL_WORDS = 10;
57
+ export declare const MIN_COL_SHARE = 0.2;
58
+ export declare function buildPageOCR(words: Word[], tuning: Tuning): PageOCR;
59
+ export declare function bucket(h: number): number;
60
+ export declare function headingLevels(pages: PageOCR[], tuning: Tuning): {
61
+ bodyH: number;
62
+ levelOf: Map<number, number>;
63
+ };