@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,102 @@
1
+ ---
2
+ name: pdf-to-md
3
+ description: "Convert a PDF to markdown with pdf-to-md and drive its QA loop to a lossless result: read the --json report's pageStats to find suspect pages, render pages to PNG as ground truth, re-extract targeted page ranges with tuning flags, and run the severity-1 word-loss audit before trusting the output. Use when converting a PDF to markdown with pdf-to-md, when a pdf-to-md conversion looks wrong (garbled reading order, misplaced text, misread words, a suspicious page), or when asked to verify a pdf-to-md conversion is lossless."
4
+ ---
5
+
6
+ # pdf-to-md
7
+
8
+ pdf-to-md converts PDFs to markdown: text layer via pdf.js, OCR (tesseract.js) fallback for
9
+ image-only or sparse pages. Its contract: recognized text is never silently dropped,
10
+ unrecoverable structure is marked (`> [review: ...]`) rather than guessed, and every claim the
11
+ output makes is mechanically checkable. This skill is the QA loop that contract is built for —
12
+ convert, read the report, verify against the real page, re-extract, audit.
13
+
14
+ ## 1. Convert
15
+
16
+ ```
17
+ pdf-to-md file.pdf --json
18
+ ```
19
+
20
+ Auto-detects the OCR need (falls back when the text layer is too sparse) and prints the QA report
21
+ alongside the markdown. `--ocr` forces the OCR path; `--no-ocr` suppresses the fallback and keeps
22
+ the sparse text-layer output. `--pages N[-M]` limits to a page range; `--stdout` writes markdown
23
+ to stdout instead of a file.
24
+
25
+ ## 2. Read the QA report
26
+
27
+ `report.pageStats` (one row per page) flags pages worth checking by hand:
28
+
29
+ - `danglingLong` — a paragraph broke off without terminal punctuation before the next one starts:
30
+ a likely invisible sentence split the geometry got wrong.
31
+ - `reviewBlocks` — count of `> [review: reason]` blocks: the geometry declined to guess an order
32
+ and labeled the block instead of guessing. Always worth reading.
33
+ - `lowConfidenceWords` / `lowConfidenceSample` — words the OCR engine itself scored below its
34
+ confidence threshold; the sample is the actual suspect tokens, worst first. Probable misreads.
35
+ - `junkHeadings` — lines promoted to headings by a font-size heuristic that are probably not
36
+ headings.
37
+ - `largeImages` (text path only) — a real text layer plus a large embedded image: text baked into
38
+ the image may duplicate or replace what the text layer extracted. Don't assume the text layer
39
+ is complete — compare it against `--pages N --ocr` on that page.
40
+
41
+ A page with none of these flags isn't proof it's correct, only that these particular detectors
42
+ found nothing — pair with step 3 for anything the report doesn't cover.
43
+
44
+ ## 3. Ground truth: render the page
45
+
46
+ ```
47
+ pdf-to-md render file.pdf N
48
+ ```
49
+
50
+ Renders page N to PNG at 288dpi — the same resolution the OCR path reads at (override with
51
+ `--dpi`) — into the current directory (or `--out DIR`). View the PNG next to the flagged markdown;
52
+ this is the only real ground truth, everything in the report is inference on top of it.
53
+
54
+ ## 4. Targeted re-extraction
55
+
56
+ Re-run just the flagged pages with an adjusted knob:
57
+
58
+ ```
59
+ pdf-to-md file.pdf --pages 27-31 --stdout --dpi 400
60
+ ```
61
+
62
+ Tuning flags (`--float-max-words`, `--para-gap`, `--heading-scale`, and the rest) are measured
63
+ defaults — read README's tuning table for what each one controls and its default rather than
64
+ guessing a value. Raising `--dpi` fixes chart/label corruption but can make scattered numerals on
65
+ the same page worse, not better — try it on the flagged page only and compare, don't assume higher
66
+ is strictly better.
67
+
68
+ ## 5. Severity-1 audit
69
+
70
+ Before trusting a conversion, run the audit — the only mechanically-checkable proof that no
71
+ recognized word was silently dropped:
72
+
73
+ ```
74
+ pdf-to-md file.pdf out.md --debug-words=words.jsonl
75
+ pdf-to-md audit words.jsonl out.md
76
+ ```
77
+
78
+ Exits 1 if any word from the dump is missing from the markdown; `MISSING=0` in the printed summary
79
+ line is the pass signal. `--debug-words` output is JSON Lines with no guaranteed key order —
80
+ parse each line as JSON, never grep the file for text.
81
+
82
+ ## 6. Machine-parseable markers
83
+
84
+ Two regex-matchable line prefixes carry content the geometry parked rather than lost:
85
+
86
+ ```
87
+ ^> \[(floats|review: [^\]]+)\] (.*)$
88
+ ```
89
+
90
+ `> [floats]` is a fragment (short line, margin text, etc.) set aside as decoration; `> [review:
91
+ reason]` is a block the geometry couldn't order, with the reason inline. Both are visible in the
92
+ markdown and safe to post-process (move, drop, re-attach) once matched.
93
+
94
+ For programmatic convergence instead of eyeballing, `--format raw` returns the full `Analysis` as
95
+ JSON: every word and block with its coordinates (normalized `[0,1]`, origin bottom-left, y up)
96
+ plus the same `report` `--json` prints. Feed that into your own re-ordering or merge logic instead
97
+ of re-parsing the markdown.
98
+
99
+ ## Reference
100
+
101
+ Full flag list: `pdf-to-md --help`. Tuning table and design contract: the package README. Every
102
+ exported function and option is documented at its declaration, visible in editor hover.