alran 0.0.0-stage → 0.9.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 (506) hide show
  1. package/ALRAN_TOOLS_NOTICES.md +64 -0
  2. package/LICENSE +27 -0
  3. package/LICENSE-STATUS.md +21 -0
  4. package/NOTICE +6 -0
  5. package/README.md +289 -2
  6. package/THIRD_PARTY_NOTICES.md +113 -0
  7. package/alran-tools.js +3 -0
  8. package/assets/agents/_default/prompt-auto_classifier.md +185 -0
  9. package/assets/agents/_default/prompt-auto_classifier_extras.md +17 -0
  10. package/assets/agents/_default/prompt-base-all.md +133 -0
  11. package/assets/agents/_default/prompt-base-all.md.hbs +228 -0
  12. package/assets/agents/_default/prompt-base-windows.md +5 -0
  13. package/assets/agents/_default/prompt-base-windows.md.hbs +5 -0
  14. package/assets/agents/_default/prompt-base-worker.md +10 -0
  15. package/assets/agents/_default/prompt-base-worker.md.hbs +27 -0
  16. package/assets/agents/_default/prompt-compact.md +76 -0
  17. package/assets/agents/_default/prompt-compact_continue.md +9 -0
  18. package/assets/agents/_default/prompt-git.md +8 -0
  19. package/assets/agents/_default/prompt-goal.md +13 -0
  20. package/assets/agents/_default/prompt-session-branch.md +3 -0
  21. package/assets/agents/_default/prompt-session-branch.md.hbs +30 -0
  22. package/assets/agents/_default/prompt-session-root.md +3 -0
  23. package/assets/agents/_default/prompt-session-root.md.hbs +32 -0
  24. package/assets/agents/_default/prompt-title.md +11 -0
  25. package/assets/agents/_default/prompt-tool_agent.md +22 -0
  26. package/assets/agents/_migration/README.md +20 -0
  27. package/assets/agents/_migration/coder/PERSONA.md +11 -0
  28. package/assets/agents/_migration/coder/system-prompt.md.hbs +42 -0
  29. package/assets/agents/_migration/general/PERSONA.md +11 -0
  30. package/assets/agents/_migration/general/system-prompt.md.hbs +49 -0
  31. package/assets/agents/_v2/AGENT_CONTEXT.md.hbs +245 -0
  32. package/assets/agents/_v2/PTC_TOOL_CALLS.md.hbs +35 -0
  33. package/assets/agents/_v2/coding/SYSTEM.md.hbs +173 -0
  34. package/assets/agents/_v2/explore.md.hbs +38 -0
  35. package/assets/agents/_v2/tui/SYSTEM.md.hbs +211 -0
  36. package/assets/agents/_v2/verifier.md.hbs +32 -0
  37. package/assets/agents/_v2/work/SYSTEM.md.hbs +186 -0
  38. package/assets/agents/_v2/worker.md.hbs +27 -0
  39. package/assets/agents/alran/PERSONA.md +7 -0
  40. package/assets/agents/alran/features/cron.md.hbs +0 -0
  41. package/assets/agents/alran/features/delegation.md.hbs +56 -0
  42. package/assets/agents/alran/features/memory.md.hbs +61 -0
  43. package/assets/agents/alran/features/recoverable-deletion.md.hbs +10 -0
  44. package/assets/agents/alran/features/task-management.md.hbs +11 -0
  45. package/assets/agents/alran/features/web-search.md.hbs +11 -0
  46. package/assets/agents/alran/modes/coding/online/PERSONA.md.hbs +20 -0
  47. package/assets/agents/alran/modes/coding/online/SYSTEM.md.hbs +158 -0
  48. package/assets/agents/alran/modes/work/online/PERSONA.md.hbs +20 -0
  49. package/assets/agents/alran/modes/work/online/SYSTEM.md.hbs +160 -0
  50. package/assets/agents/alran/prompt-session-root.md +4 -0
  51. package/assets/agents/alran/prompt-session-root.md.hbs +4 -0
  52. package/assets/agents/alran/skills/alran-code-product/SKILL.md +72 -0
  53. package/assets/agents/alran/skills/alran-code-product/references/account-models.md +61 -0
  54. package/assets/agents/alran/skills/alran-code-product/references/agents.md +34 -0
  55. package/assets/agents/alran/skills/alran-code-product/references/extensions.md +46 -0
  56. package/assets/agents/alran/skills/alran-code-product/references/workflows.md +56 -0
  57. package/assets/agents/alran/skills/control-in-app-browser/SKILL.md +590 -0
  58. package/assets/agents/alran/system-prompt.md.hbs +97 -0
  59. package/assets/agents/builtin-agents.json +1 -0
  60. package/assets/agents/desktop-task/archive-title/system-en.md +1 -0
  61. package/assets/agents/desktop-task/checkpoint/system.md +19 -0
  62. package/assets/agents/desktop-task/output-revision/system.md +1 -0
  63. package/assets/agents/desktop-task/retry/continuation.md +4 -0
  64. package/assets/agents/desktop-task/session-title/system.md +41 -0
  65. package/assets/agents/explore/PERSONA.md +8 -0
  66. package/assets/agents/explore/agent.md +14 -0
  67. package/assets/agents/explore/system-prompt.md.hbs +35 -0
  68. package/assets/agents/greeting.md +61 -0
  69. package/assets/agents/managed-prompts.json +47 -0
  70. package/assets/agents/prompt-exemptions.json +36 -0
  71. package/assets/agents/verifier/PERSONA.md +8 -0
  72. package/assets/agents/verifier/agent.md +17 -0
  73. package/assets/agents/verifier/system-prompt.md.hbs +28 -0
  74. package/assets/agents/worker/PERSONA.md +8 -0
  75. package/assets/agents/worker/agent.md +18 -0
  76. package/assets/agents/worker/system-prompt.md.hbs +22 -0
  77. package/assets/agents/workflow/code-review/review-candidates.md +120 -0
  78. package/assets/agents/workflow/code-review/reviewer-system.md +75 -0
  79. package/assets/agents/workflow/goal/budget-limit.md +16 -0
  80. package/assets/agents/workflow/goal/continuation.md +62 -0
  81. package/assets/agents/workflow/goal/objective-updated.md +16 -0
  82. package/assets/agents/workflow/goal/recovery-terminal-audit.md +13 -0
  83. package/assets/agents/workflow/goal/recovery.md +11 -0
  84. package/assets/agents/workflow/goal/terminal-audit.md +10 -0
  85. package/assets/agents/workflow/plan-mode/agent-entry.md +72 -0
  86. package/assets/agents/workflow/prompt-hook/system.md +0 -0
  87. package/assets/models-dev-catalog.json.gz +0 -0
  88. package/assets/prompts/code-review/review-candidates.md +120 -0
  89. package/assets/prompts/code-review/reviewer-system.md +75 -0
  90. package/assets/skills/alran-tools-master/SKILL.md +127 -0
  91. package/assets/skills/code-review/SKILL.md +51 -0
  92. package/assets/skills/cu-desktop/SKILL.md +255 -0
  93. package/assets/skills/deep-research/SKILL.md +30 -0
  94. package/assets/skills/deploy-website/SKILL.md +52 -0
  95. package/assets/skills/docx/LICENSE +21 -0
  96. package/assets/skills/docx/SKILL.md +259 -0
  97. package/assets/skills/docx/assets/styles/academic_styles.xml +250 -0
  98. package/assets/skills/docx/assets/styles/corporate_styles.xml +284 -0
  99. package/assets/skills/docx/assets/styles/default_styles.xml +449 -0
  100. package/assets/skills/docx/assets/xsd/aesthetic-rules.xsd +470 -0
  101. package/assets/skills/docx/assets/xsd/business-rules.xsd +130 -0
  102. package/assets/skills/docx/assets/xsd/common-types.xsd +159 -0
  103. package/assets/skills/docx/assets/xsd/wml-subset.xsd +589 -0
  104. package/assets/skills/docx/docs/acceptance-checklists/create.md +7 -0
  105. package/assets/skills/docx/docs/acceptance-checklists/edit.md +6 -0
  106. package/assets/skills/docx/docs/acceptance-checklists/layout-repair.md +7 -0
  107. package/assets/skills/docx/docs/acceptance-checklists/template.md +6 -0
  108. package/assets/skills/docx/docs/acceptance.md +139 -0
  109. package/assets/skills/docx/docs/anti-patterns.md +14 -0
  110. package/assets/skills/docx/docs/backends.md +116 -0
  111. package/assets/skills/docx/docs/evidence.md +73 -0
  112. package/assets/skills/docx/docs/failure-taxonomy.md +71 -0
  113. package/assets/skills/docx/docs/index.md +50 -0
  114. package/assets/skills/docx/docs/rendered-delivery.md +125 -0
  115. package/assets/skills/docx/docs/router.md +122 -0
  116. package/assets/skills/docx/docs/tables-and-numbering.md +27 -0
  117. package/assets/skills/docx/docs/task-apply-template.md +141 -0
  118. package/assets/skills/docx/docs/task-compare-two-docx.md +48 -0
  119. package/assets/skills/docx/docs/task-create.md +124 -0
  120. package/assets/skills/docx/docs/task-edit-fill.md +69 -0
  121. package/assets/skills/docx/docs/task-read-content.md +148 -0
  122. package/assets/skills/docx/docs/task-read-rendered.md +78 -0
  123. package/assets/skills/docx/docs/task-read-structure.md +93 -0
  124. package/assets/skills/docx/docs/task-repair-layout.md +70 -0
  125. package/assets/skills/docx/docs/template-dsl.md +32 -0
  126. package/assets/skills/docx/docs/track-changes.md +15 -0
  127. package/assets/skills/docx/docs/xml-patch-dsl.md +33 -0
  128. package/assets/skills/docx/references/cjk_typography.md +357 -0
  129. package/assets/skills/docx/references/cjk_university_template_guide.md +184 -0
  130. package/assets/skills/docx/references/comments_guide.md +191 -0
  131. package/assets/skills/docx/references/design_good_bad_examples.md +829 -0
  132. package/assets/skills/docx/references/design_principles.md +819 -0
  133. package/assets/skills/docx/references/openxml_element_order.md +308 -0
  134. package/assets/skills/docx/references/openxml_encyclopedia_part1.md +4061 -0
  135. package/assets/skills/docx/references/openxml_encyclopedia_part2.md +2820 -0
  136. package/assets/skills/docx/references/openxml_encyclopedia_part3.md +3381 -0
  137. package/assets/skills/docx/references/openxml_namespaces.md +82 -0
  138. package/assets/skills/docx/references/openxml_units.md +72 -0
  139. package/assets/skills/docx/references/sample-patch-plans.json +22 -0
  140. package/assets/skills/docx/references/sample-task-intents.json +5 -0
  141. package/assets/skills/docx/references/sample-template-manifests.json +21 -0
  142. package/assets/skills/docx/references/scenario_a_create.md +284 -0
  143. package/assets/skills/docx/references/scenario_b_edit_content.md +295 -0
  144. package/assets/skills/docx/references/scenario_c_apply_template.md +456 -0
  145. package/assets/skills/docx/references/track_changes_guide.md +200 -0
  146. package/assets/skills/docx/references/troubleshooting.md +506 -0
  147. package/assets/skills/docx/references/typography_guide.md +294 -0
  148. package/assets/skills/docx/references/xsd_validation_guide.md +158 -0
  149. package/assets/skills/docx/scripts/build_patch_plan.py +29 -0
  150. package/assets/skills/docx/scripts/diff_docx_structure.py +61 -0
  151. package/assets/skills/docx/scripts/doc_to_docx.ps1 +85 -0
  152. package/assets/skills/docx/scripts/doc_to_docx.sh +40 -0
  153. package/assets/skills/docx/scripts/docx_preview.ps1 +76 -0
  154. package/assets/skills/docx/scripts/docx_preview.sh +37 -0
  155. package/assets/skills/docx/scripts/docx_to_pdf.py +87 -0
  156. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/AlranAIDocx.Cli.csproj +19 -0
  157. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/Program.cs +18 -0
  158. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/AlranAIDocx.Core.csproj +15 -0
  159. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/AnalyzeCommand.cs +147 -0
  160. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ApplyTemplateCommand.cs +322 -0
  161. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/CreateCommand.cs +324 -0
  162. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/DiffCommand.cs +155 -0
  163. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/EditContentCommand.cs +487 -0
  164. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/FixOrderCommand.cs +108 -0
  165. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/MergeRunsCommand.cs +122 -0
  166. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ValidateCommand.cs +107 -0
  167. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/CommentSynchronizer.cs +169 -0
  168. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/ElementOrder.cs +80 -0
  169. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/NamespaceConstants.cs +42 -0
  170. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/RunMerger.cs +81 -0
  171. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/StyleAnalyzer.cs +81 -0
  172. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/TrackChangesHelper.cs +99 -0
  173. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/UnitConverter.cs +23 -0
  174. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples.cs +1832 -0
  175. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs +910 -0
  176. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs +999 -0
  177. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs +1048 -0
  178. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs +1038 -0
  179. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/CharacterFormattingSamples.cs +1020 -0
  180. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/DocumentCreationSamples.cs +1121 -0
  181. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FieldAndTocSamples.cs +624 -0
  182. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FootnoteAndCommentSamples.cs +675 -0
  183. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/HeaderFooterSamples.cs +838 -0
  184. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ImageSamples.cs +917 -0
  185. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ListAndNumberingSamples.cs +826 -0
  186. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ParagraphFormattingSamples.cs +1199 -0
  187. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/StyleSystemSamples.cs +1487 -0
  188. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TableSamples.cs +1163 -0
  189. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TrackChangesSamples.cs +595 -0
  190. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/CjkHelper.cs +39 -0
  191. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/FontDefaults.cs +24 -0
  192. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/PageSizes.cs +20 -0
  193. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/BusinessRuleValidator.cs +224 -0
  194. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/GateCheckValidator.cs +148 -0
  195. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/ValidationResult.cs +23 -0
  196. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/XsdValidator.cs +69 -0
  197. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.slnx +4 -0
  198. package/assets/skills/docx/scripts/env_check.ps1 +327 -0
  199. package/assets/skills/docx/scripts/env_check.sh +340 -0
  200. package/assets/skills/docx/scripts/extract_docx_text.py +1075 -0
  201. package/assets/skills/docx/scripts/pack_docx.py +31 -0
  202. package/assets/skills/docx/scripts/read_docx_structure.py +1032 -0
  203. package/assets/skills/docx/scripts/render_docx_pages.py +147 -0
  204. package/assets/skills/docx/scripts/rendered_report.py +609 -0
  205. package/assets/skills/docx/scripts/setup.ps1 +542 -0
  206. package/assets/skills/docx/scripts/setup.sh +537 -0
  207. package/assets/skills/docx/scripts/unpack_docx.py +29 -0
  208. package/assets/skills/docx/scripts/validate_template_manifest.py +60 -0
  209. package/assets/skills/docx/scripts/verify_anchor_atomicity.py +87 -0
  210. package/assets/skills/edit-deployed-website/SKILL.md +27 -0
  211. package/assets/skills/init/SKILL.md +135 -0
  212. package/assets/skills/llm-call/SKILL.md +48 -0
  213. package/assets/skills/llm-call/scripts/llm_call.py +458 -0
  214. package/assets/skills/pdf/SKILL.md +280 -0
  215. package/assets/skills/pdf/docs/advanced-reference.md +711 -0
  216. package/assets/skills/pdf/docs/create-guide.md +437 -0
  217. package/assets/skills/pdf/docs/design-guide.md +204 -0
  218. package/assets/skills/pdf/docs/forms-guide.md +462 -0
  219. package/assets/skills/pdf/docs/html-pdf-spec.md +500 -0
  220. package/assets/skills/pdf/docs/latex-academic-thesis-guide.md +233 -0
  221. package/assets/skills/pdf/docs/latex-technical-book-guide.md +112 -0
  222. package/assets/skills/pdf/docs/pitfalls-index.md +792 -0
  223. package/assets/skills/pdf/docs/read-guide.md +358 -0
  224. package/assets/skills/pdf/docs/reformat-guide.md +238 -0
  225. package/assets/skills/pdf/docs/skill-readme-archive.md +151 -0
  226. package/assets/skills/pdf/docs/troubleshooting.md +86 -0
  227. package/assets/skills/pdf/docs/vision-guide.md +188 -0
  228. package/assets/skills/pdf/scripts/__init__.py +0 -0
  229. package/assets/skills/pdf/scripts/_pdf_read_lib.py +284 -0
  230. package/assets/skills/pdf/scripts/fill/__init__.py +0 -0
  231. package/assets/skills/pdf/scripts/fill/acroform_apply.py +153 -0
  232. package/assets/skills/pdf/scripts/fill/overlay_apply.py +109 -0
  233. package/assets/skills/pdf/scripts/lib/__init__.py +0 -0
  234. package/assets/skills/pdf/scripts/lib/acroform_io.py +170 -0
  235. package/assets/skills/pdf/scripts/lib/cli_utils.py +41 -0
  236. package/assets/skills/pdf/scripts/lib/geometry.py +79 -0
  237. package/assets/skills/pdf/scripts/make.sh +388 -0
  238. package/assets/skills/pdf/scripts/merge.py +112 -0
  239. package/assets/skills/pdf/scripts/pdf_inspect/__init__.py +0 -0
  240. package/assets/skills/pdf/scripts/pdf_inspect/acroform_inspect.py +52 -0
  241. package/assets/skills/pdf/scripts/pdf_inspect/acroform_probe.py +57 -0
  242. package/assets/skills/pdf/scripts/pdf_inspect/layout_scan.py +164 -0
  243. package/assets/skills/pdf/scripts/read_pdf_vision.py +473 -0
  244. package/assets/skills/pdf/scripts/reformat_parse.py +181 -0
  245. package/assets/skills/pdf/scripts/render/__init__.py +0 -0
  246. package/assets/skills/pdf/scripts/render/overlay_preview.py +86 -0
  247. package/assets/skills/pdf/scripts/render/page_rasterize.py +85 -0
  248. package/assets/skills/pdf/scripts/render_html.cjs +205 -0
  249. package/assets/skills/pdf/scripts/validate/__init__.py +0 -0
  250. package/assets/skills/pdf/scripts/validate/geometry_lint.py +124 -0
  251. package/assets/skills/pdf/templates/INDEX.md +90 -0
  252. package/assets/skills/pdf/templates/bilingual-menu-premium/README.md +175 -0
  253. package/assets/skills/pdf/templates/bilingual-menu-premium/skeleton.html +343 -0
  254. package/assets/skills/pdf/templates/brand-guide-2page/README.md +140 -0
  255. package/assets/skills/pdf/templates/brand-guide-2page/skeleton.html +264 -0
  256. package/assets/skills/pdf/templates/data-viz-report/README.md +234 -0
  257. package/assets/skills/pdf/templates/data-viz-report/skeleton.html +835 -0
  258. package/assets/skills/pdf/templates/form-fill-acroform/README.md +195 -0
  259. package/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json +118 -0
  260. package/assets/skills/pdf/templates/latex-academic-thesis/README.md +146 -0
  261. package/assets/skills/pdf/templates/latex-academic-thesis/source.tex +334 -0
  262. package/assets/skills/pdf/templates/latex-technical-book/README.md +130 -0
  263. package/assets/skills/pdf/templates/latex-technical-book/README.template-source.md +62 -0
  264. package/assets/skills/pdf/templates/latex-technical-book/source.tex +439 -0
  265. package/assets/skills/pdf/templates/multi-article-aggregator/README.md +148 -0
  266. package/assets/skills/pdf/templates/multi-article-aggregator/pipeline.md +223 -0
  267. package/assets/skills/pdf/templates/multilang-research-report/README.md +136 -0
  268. package/assets/skills/pdf/templates/multilang-research-report/skeleton.html +242 -0
  269. package/assets/skills/pdf/templates/reformat-default/README.md +136 -0
  270. package/assets/skills/pdf/templates/reformat-default/skeleton.html +204 -0
  271. package/assets/skills/pdf/templates/translate-preserve-layout/README.md +136 -0
  272. package/assets/skills/pdf/templates/translate-preserve-layout/skeleton.html +96 -0
  273. package/assets/skills/pdf/templates/translate-preserve-layout/terminology.template.json +66 -0
  274. package/assets/skills/pptx/SKILL.md +283 -0
  275. package/assets/skills/pptx/references/design-system.md +424 -0
  276. package/assets/skills/pptx/references/editing.md +162 -0
  277. package/assets/skills/pptx/references/element-map.md +229 -0
  278. package/assets/skills/pptx/references/pitfalls.md +205 -0
  279. package/assets/skills/pptx/references/pptxgenjs.md +420 -0
  280. package/assets/skills/pptx/references/preview-selection-writeback.md +65 -0
  281. package/assets/skills/pptx/references/python-pptx-recipes.md +63 -0
  282. package/assets/skills/pptx/references/slide-types.md +413 -0
  283. package/assets/skills/pptx/scripts/alran-ppt-map.cjs +280 -0
  284. package/assets/skills/pptx/scripts/audit_pptx.py +708 -0
  285. package/assets/skills/pptx/scripts/extract_comments.py +468 -0
  286. package/assets/skills/pptx/scripts/extract_images.py +226 -0
  287. package/assets/skills/pptx/scripts/extract_pptx.py +285 -0
  288. package/assets/skills/pptx/scripts/pdf2png.swift +203 -0
  289. package/assets/skills/pptx/scripts/pptx-screenshot.sh +105 -0
  290. package/assets/skills/resume-codex/SKILL.md +53 -0
  291. package/assets/skills/resume-codex/scripts/session-reader.mjs +445 -0
  292. package/assets/skills/skill-creator/SKILL.md +188 -0
  293. package/assets/skills/skill-creator/references/anti-patterns.md +149 -0
  294. package/assets/skills/skill-creator/references/commands-macos-linux.md +38 -0
  295. package/assets/skills/skill-creator/references/commands-windows-powershell.md +48 -0
  296. package/assets/skills/skill-creator/references/description-rubric.md +83 -0
  297. package/assets/skills/skill-creator/references/skill-template.md +101 -0
  298. package/assets/skills/skill-creator/references/when-to-bundle-scripts.md +139 -0
  299. package/assets/skills/skill-creator/scripts/lint-skill.js +226 -0
  300. package/assets/skills/skill-refiner/SKILL.md +137 -0
  301. package/assets/skills/visual-page/SKILL.md +194 -0
  302. package/assets/skills/x-link-reader/SKILL.md +108 -0
  303. package/assets/skills/xlsx/SKILL.md +498 -0
  304. package/assets/skills/xlsx/docs/advanced-reference.md +410 -0
  305. package/assets/skills/xlsx/docs/conventions-guide.md +217 -0
  306. package/assets/skills/xlsx/docs/create-edit-guide.md +410 -0
  307. package/assets/skills/xlsx/docs/pitfalls-index.md +759 -0
  308. package/assets/skills/xlsx/docs/raw-xml-escape-hatch.md +201 -0
  309. package/assets/skills/xlsx/docs/recalc-guide.md +295 -0
  310. package/assets/skills/xlsx/scripts/office/helpers/__init__.py +0 -0
  311. package/assets/skills/xlsx/scripts/office/helpers/merge_runs.py +199 -0
  312. package/assets/skills/xlsx/scripts/office/helpers/simplify_redlines.py +197 -0
  313. package/assets/skills/xlsx/scripts/office/pack.py +159 -0
  314. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
  315. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
  316. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
  317. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
  318. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
  319. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
  320. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
  321. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
  322. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
  323. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
  324. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
  325. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
  326. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
  327. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
  328. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
  329. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
  330. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
  331. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
  332. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
  333. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
  334. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
  335. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
  336. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
  337. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
  338. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
  339. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
  340. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
  341. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
  342. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
  343. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
  344. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
  345. package/assets/skills/xlsx/scripts/office/schemas/mce/mc.xsd +75 -0
  346. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd +560 -0
  347. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd +67 -0
  348. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd +14 -0
  349. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd +20 -0
  350. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd +13 -0
  351. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
  352. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd +8 -0
  353. package/assets/skills/xlsx/scripts/office/soffice.py +191 -0
  354. package/assets/skills/xlsx/scripts/office/unpack.py +132 -0
  355. package/assets/skills/xlsx/scripts/office/validate.py +117 -0
  356. package/assets/skills/xlsx/scripts/office/validators/__init__.py +15 -0
  357. package/assets/skills/xlsx/scripts/office/validators/base.py +851 -0
  358. package/assets/skills/xlsx/scripts/office/validators/docx.py +446 -0
  359. package/assets/skills/xlsx/scripts/office/validators/pptx.py +275 -0
  360. package/assets/skills/xlsx/scripts/office/validators/redlining.py +247 -0
  361. package/assets/skills/xlsx/scripts/recalc.py +450 -0
  362. package/chunks/account-commands-JZ6NXTTK.js +2 -0
  363. package/chunks/anthropic-MN33DP4E.js +2 -0
  364. package/chunks/application-ITGAJ4HC.js +2 -0
  365. package/chunks/auth-command-V3RVPLZO.js +2 -0
  366. package/chunks/azure-openai-responses-OWHMUNKC.js +2 -0
  367. package/chunks/chunk-2TF6JAQM.js +2 -0
  368. package/chunks/chunk-33CNY6GP.js +2 -0
  369. package/chunks/chunk-3AODGLMF.js +2 -0
  370. package/chunks/chunk-44VPC5LA.js +38 -0
  371. package/chunks/chunk-4CN3IJFH.js +2 -0
  372. package/chunks/chunk-4PDIO3M6.js +2 -0
  373. package/chunks/chunk-4X22UJQH.js +164 -0
  374. package/chunks/chunk-6255CZPL.js +2 -0
  375. package/chunks/chunk-6P4UKHGR.js +2 -0
  376. package/chunks/chunk-7QLAXRD2.js +1085 -0
  377. package/chunks/chunk-7XYOYZX2.js +2 -0
  378. package/chunks/chunk-A7GMJNA2.js +29 -0
  379. package/chunks/chunk-AGUSPIUP.js +2 -0
  380. package/chunks/chunk-BQ3CF3KE.js +2 -0
  381. package/chunks/chunk-C3CMJAAV.js +3 -0
  382. package/chunks/chunk-CJM7ZJ6W.js +7 -0
  383. package/chunks/chunk-CSOUJVKM.js +2 -0
  384. package/chunks/chunk-D66ZSHXR.js +2 -0
  385. package/chunks/chunk-D7MGU75P.js +2 -0
  386. package/chunks/chunk-E3GLGDGC.js +5 -0
  387. package/chunks/chunk-ENHOPPS7.js +16 -0
  388. package/chunks/chunk-EOR6EDNR.js +2 -0
  389. package/chunks/chunk-EYK25HWR.js +2 -0
  390. package/chunks/chunk-F46IELF5.js +2 -0
  391. package/chunks/chunk-FC4M2B7E.js +2 -0
  392. package/chunks/chunk-FSNYOJPJ.js +2 -0
  393. package/chunks/chunk-FUERW2DW.js +3 -0
  394. package/chunks/chunk-FXOH6TEQ.js +21 -0
  395. package/chunks/chunk-GP52JZMY.js +2 -0
  396. package/chunks/chunk-GRXX6I72.js +2 -0
  397. package/chunks/chunk-GSYHBK5Q.js +6 -0
  398. package/chunks/chunk-HNWBFJNO.js +2 -0
  399. package/chunks/chunk-IIE366LR.js +6706 -0
  400. package/chunks/chunk-IWK7PZP7.js +207 -0
  401. package/chunks/chunk-J3KCPYZT.js +2 -0
  402. package/chunks/chunk-KCLRJQ53.js +59 -0
  403. package/chunks/chunk-LU4RPLJ3.js +2 -0
  404. package/chunks/chunk-LZJYNT32.js +2 -0
  405. package/chunks/chunk-M7GW4VMR.js +27 -0
  406. package/chunks/chunk-MACBL5HF.js +2 -0
  407. package/chunks/chunk-N5NTXCJI.js +2 -0
  408. package/chunks/chunk-N5SVBCUB.js +7 -0
  409. package/chunks/chunk-N6W7ZL26.js +2 -0
  410. package/chunks/chunk-NWB7LFOK.js +131 -0
  411. package/chunks/chunk-OIQ336YE.js +16 -0
  412. package/chunks/chunk-OQNU3VPS.js +30 -0
  413. package/chunks/chunk-OTDNOWXG.js +16 -0
  414. package/chunks/chunk-PNXZWSWT.js +3 -0
  415. package/chunks/chunk-QFUV5PX6.js +2 -0
  416. package/chunks/chunk-QIN5ZBE2.js +2 -0
  417. package/chunks/chunk-QKBN5CGI.js +2 -0
  418. package/chunks/chunk-QPGTKSIQ.js +2 -0
  419. package/chunks/chunk-SIOLUFGG.js +2 -0
  420. package/chunks/chunk-TW23QKAD.js +3 -0
  421. package/chunks/chunk-U3RMPDXU.js +2 -0
  422. package/chunks/chunk-U7U3DJHF.js +2 -0
  423. package/chunks/chunk-VLXX22YO.js +2 -0
  424. package/chunks/chunk-WHD2XVT2.js +2 -0
  425. package/chunks/chunk-WTAJMYF2.js +249 -0
  426. package/chunks/chunk-WWNUAU4P.js +29 -0
  427. package/chunks/chunk-WYANV3IX.js +4 -0
  428. package/chunks/chunk-XAGZ6ZEU.js +9 -0
  429. package/chunks/chunk-XFCC2CI2.js +24 -0
  430. package/chunks/chunk-XQK7JM66.js +2 -0
  431. package/chunks/chunk-YLQXZBEL.js +2 -0
  432. package/chunks/chunk-YPV2X2RG.js +2 -0
  433. package/chunks/chunk-Z6BHCXKT.js +25 -0
  434. package/chunks/chunk-Z6HBNJCA.js +8 -0
  435. package/chunks/chunk-ZQKVUPKA.js +2 -0
  436. package/chunks/chunk-ZQOALVGL.js +2 -0
  437. package/chunks/clipboard-image-PQPC4EHR.js +2 -0
  438. package/chunks/data-dir-LDVKDCJ2.js +2 -0
  439. package/chunks/dist-2BRD4JFU.js +11 -0
  440. package/chunks/dist-EXKHRFQO.js +5 -0
  441. package/chunks/emscripten-module-RD6P2XH5.js +2 -0
  442. package/chunks/emscripten-module-WYNDFH3N.js +2 -0
  443. package/chunks/emscripten-module-XPTEOIWW.js +2 -0
  444. package/chunks/emscripten-module-ZS3PMSDF.js +2 -0
  445. package/chunks/ffi-IO7WZQNG.js +2 -0
  446. package/chunks/ffi-M5UP5J6C.js +2 -0
  447. package/chunks/ffi-ORLOPBB3.js +2 -0
  448. package/chunks/ffi-OUPK6AY6.js +2 -0
  449. package/chunks/google-UJAPMFAB.js +2 -0
  450. package/chunks/google-vertex-VLSF55PW.js +2 -0
  451. package/chunks/install-source-JTIUC4G4.js +2 -0
  452. package/chunks/launcher-FCZ3EDBF.js +61 -0
  453. package/chunks/lifecycle-GY435YMF.js +2 -0
  454. package/chunks/main-TQGGRHTS.js +13 -0
  455. package/chunks/mistral-ZJZUEF2X.js +3 -0
  456. package/chunks/module-6F3E5H7Y-BN7QWGYB.js +2 -0
  457. package/chunks/module-asyncify-R6PWJ6ZV-P4FWSBAY.js +2 -0
  458. package/chunks/multipart-parser-L6M455MS.js +2 -0
  459. package/chunks/network-proxy-U72JCK2I.js +2 -0
  460. package/chunks/openai-codex-responses-FPCDNRL5.js +2 -0
  461. package/chunks/openai-completions-D32YW6KL.js +2 -0
  462. package/chunks/openai-responses-ZCGSENM4.js +2 -0
  463. package/chunks/openrouter-G2EHY5BD.js +2 -0
  464. package/chunks/otel-OHXIZ666.js +2 -0
  465. package/chunks/package-contract-GVXTMJ3N.js +2 -0
  466. package/chunks/pdfjs-SHZAF7PF.js +107 -0
  467. package/chunks/photon_rs-C52RL4CI.js +3 -0
  468. package/chunks/plugin-command-OSAFHS7C.js +2 -0
  469. package/chunks/provider-command-SKTCHD4E.js +2 -0
  470. package/chunks/questionnaire-bridge-ISQOCYWY.js +2 -0
  471. package/chunks/run-acp-command-SG2BDMFJ.js +2 -0
  472. package/chunks/run-exec-command-5ADSQR2Z.js +15 -0
  473. package/chunks/skills-command-XXXEZAG6.js +2 -0
  474. package/chunks/src-DNIDEMVV.js +2 -0
  475. package/chunks/src-IBHIRTD7.js +2 -0
  476. package/chunks/telemetry-J7ZLGF5X.js +2 -0
  477. package/chunks/telemetry-command-COQG2AKK.js +5 -0
  478. package/chunks/tools-WDBB2JKV.js +2 -0
  479. package/chunks/undici-TUGHZJSA.js +2 -0
  480. package/chunks/update-NB6OD572.js +14 -0
  481. package/chunks/update-hint-ED7O67WU.js +3 -0
  482. package/chunks/wechat-onboard-UWXQW2HT.js +2 -0
  483. package/cli.js +5 -0
  484. package/configs/data-minimal.yaml +50 -0
  485. package/embedded/alran-tools/cli.mjs +4961 -0
  486. package/embedded/alran-tools/manifest.json +25 -0
  487. package/emscripten-module.wasm +0 -0
  488. package/image-preview-worker.js +2 -0
  489. package/internal-bin/alran-tools +9 -0
  490. package/internal-bin/alran-tools.cmd +8 -0
  491. package/matrix-mcp-stdio.js +4 -0
  492. package/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node +0 -0
  493. package/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node +0 -0
  494. package/native/win32/prebuilds/win32-arm64/win32-console-mode.node +0 -0
  495. package/native/win32/prebuilds/win32-x64/win32-console-mode.node +0 -0
  496. package/package.json +38 -4
  497. package/photon_rs_bg.wasm +0 -0
  498. package/quickjs-worker.js +152 -0
  499. package/vendor/java-proxy-agent/build.ts +97 -0
  500. package/vendor/java-proxy-agent/srt-proxy-agent.jar +0 -0
  501. package/vendor/seccomp/arm64/apply-seccomp +0 -0
  502. package/vendor/seccomp/build.ts +74 -0
  503. package/vendor/seccomp/x64/apply-seccomp +0 -0
  504. package/vendor/srt-win/arm64/srt-win.exe +0 -0
  505. package/vendor/srt-win/build.ts +40 -0
  506. package/vendor/srt-win/x64/srt-win.exe +0 -0
@@ -0,0 +1,711 @@
1
+ # Advanced Reference
2
+
3
+ Maintained by Alran (MIT). This reference collects PDF features and
4
+ libraries that are too situational for the main `SKILL.md`. Reach for
5
+ it when the standard recipes in `create-guide.md` / `forms-guide.md` /
6
+ `read-guide.md` are not enough.
7
+
8
+ All in-tree script invocations live under `scripts/` and are dispatched
9
+ through `bash scripts/make.sh ...`. The fill / pdf_inspect / render / validate
10
+ subpackages can also be run directly as `python -m scripts.<group>.<name>`
11
+ from the skill root when you need fine-grained control.
12
+
13
+ Global navigation rule for every mutation path: when you merge, split, rotate,
14
+ crop, watermark, encrypt, annotate, sign, or otherwise rebuild a PDF, preserve
15
+ existing TOC links, named destinations, outlines/bookmarks, and `/Link`
16
+ annotations whenever possible. If page order or page offsets change, update the
17
+ visible TOC/index, outlines, and link destinations so they still land on the
18
+ correct pages. For any newly assembled multi-page output, add clickable
19
+ TOC/index navigation before delivery; do not ship a merged packet whose first
20
+ page is an inert list of page numbers.
21
+
22
+ > **Note on the `pdf_inspect/` directory name.** It is deliberately
23
+ > *not* called `inspect/`. Python ≥ 3.11 colourised tracebacks pull
24
+ > ``inspect.signature`` in via ``argparse → _colorize → dataclasses``, and
25
+ > any package named ``inspect`` placed first on ``sys.path`` (which the
26
+ > CPython "script directory at index 0" rule does for entry-point
27
+ > scripts) shadows the stdlib module and breaks every renderer that
28
+ > transitively touches it (reportlab → PIL → typing_extensions). The
29
+ > rename is structural insulation against that whole class of bugs.
30
+
31
+ ---
32
+
33
+ ## 1. pypdfium2 — High-Performance Rendering
34
+
35
+ `pypdfium2` is the Python binding for PDFium (Chromium's PDF engine).
36
+ It is the fastest mainstream renderer in the Python ecosystem.
37
+
38
+ ### 1.1 Render a page to PIL
39
+
40
+ ```python
41
+ import pypdfium2 as pdfium
42
+ src_doc = pdfium.PdfDocument("invoice.pdf")
43
+ pg = src_doc[0]
44
+ bitmap = pg.render(scale=2.0, rotation=0)
45
+ bitmap.to_pil().save("invoice_page_1.png", "PNG")
46
+ ```
47
+
48
+ ### 1.2 Render every page to JPEG
49
+
50
+ ```python
51
+ import pypdfium2 as pdfium
52
+ src_doc = pdfium.PdfDocument("payslip.pdf")
53
+ for i, pg in enumerate(src_doc):
54
+ pg.render(scale=1.5).to_pil().save(f"payslip_{i + 1}.jpg", "JPEG", quality=90)
55
+ ```
56
+
57
+ ### 1.3 Cheap text extraction
58
+
59
+ ```python
60
+ import pypdfium2 as pdfium
61
+ src_doc = pdfium.PdfDocument("payslip.pdf")
62
+ for i, pg in enumerate(src_doc):
63
+ body = pg.get_text()
64
+ print(f"page {i + 1}: {len(body)} chars")
65
+ ```
66
+
67
+ ---
68
+
69
+ ## 2. JavaScript Libraries
70
+
71
+ These are useful when the surrounding application is a Node service or
72
+ a browser front-end. They are listed here only for completeness; the
73
+ in-tree scripts are pure Python.
74
+
75
+ ### 2.1 pdf-lib (MIT)
76
+
77
+ `pdf-lib` works in any JavaScript runtime — Node, Deno, browsers — and
78
+ preserves form structure better than most alternatives.
79
+
80
+ #### Manipulate an existing document
81
+
82
+ ```javascript
83
+ import { PDFDocument } from 'pdf-lib';
84
+ import fs from 'fs';
85
+
86
+ async function tweak() {
87
+ const bytes = fs.readFileSync('invoice.pdf');
88
+ const doc = await PDFDocument.load(bytes);
89
+
90
+ console.log(`pages: ${doc.getPageCount()}`);
91
+ const pg = doc.addPage([600, 400]);
92
+ pg.drawText('Added by pdf-lib', { x: 100, y: 300, size: 16 });
93
+
94
+ fs.writeFileSync('invoice-modified.pdf', await doc.save());
95
+ }
96
+ ```
97
+
98
+ #### Author from scratch
99
+
100
+ ```javascript
101
+ import { PDFDocument, rgb, StandardFonts } from 'pdf-lib';
102
+ import fs from 'fs';
103
+
104
+ async function makeInvoice() {
105
+ const doc = await PDFDocument.create();
106
+ const bold = await doc.embedFont(StandardFonts.HelveticaBold);
107
+ const pg = doc.addPage([595, 842]);
108
+ const { width, height } = pg.getSize();
109
+
110
+ pg.drawText('Invoice 2026-04-21', {
111
+ x: 50, y: height - 50, size: 18, font: bold, color: rgb(0.2, 0.2, 0.8),
112
+ });
113
+ pg.drawRectangle({
114
+ x: 40, y: height - 100, width: width - 80, height: 30,
115
+ color: rgb(0.9, 0.9, 0.9),
116
+ });
117
+
118
+ fs.writeFileSync('invoice-new.pdf', await doc.save());
119
+ }
120
+ ```
121
+
122
+ #### Merge selected pages
123
+
124
+ ```javascript
125
+ import { PDFDocument } from 'pdf-lib';
126
+ import fs from 'fs';
127
+
128
+ async function combine() {
129
+ const merged = await PDFDocument.create();
130
+
131
+ const a = await PDFDocument.load(fs.readFileSync('a.pdf'));
132
+ const b = await PDFDocument.load(fs.readFileSync('b.pdf'));
133
+
134
+ (await merged.copyPages(a, a.getPageIndices()))
135
+ .forEach(pg => merged.addPage(pg));
136
+ (await merged.copyPages(b, [0, 2, 4]))
137
+ .forEach(pg => merged.addPage(pg));
138
+
139
+ fs.writeFileSync('combined.pdf', await merged.save());
140
+ }
141
+ ```
142
+
143
+ ### 2.2 pdfjs-dist (Apache)
144
+
145
+ Mozilla's PDF.js, packaged for npm. Used primarily inside browsers.
146
+
147
+ ```javascript
148
+ import * as pdfjsLib from 'pdfjs-dist';
149
+ pdfjsLib.GlobalWorkerOptions.workerSrc = './pdf.worker.js';
150
+
151
+ async function show() {
152
+ const pdf = await pdfjsLib.getDocument('invoice.pdf').promise;
153
+ const pg = await pdf.getPage(1);
154
+ const vp = pg.getViewport({ scale: 1.5 });
155
+
156
+ const cv = document.createElement('canvas');
157
+ cv.width = vp.width;
158
+ cv.height = vp.height;
159
+ await pg.render({ canvasContext: cv.getContext('2d'), viewport: vp }).promise;
160
+ document.body.appendChild(cv);
161
+ }
162
+ ```
163
+
164
+ Extract text with coordinates:
165
+
166
+ ```javascript
167
+ async function harvest() {
168
+ const pdf = await pdfjsLib.getDocument('invoice.pdf').promise;
169
+ for (let i = 1; i <= pdf.numPages; i++) {
170
+ const pg = await pdf.getPage(i);
171
+ const txt = await pg.getTextContent();
172
+ const items = txt.items.map(it => ({
173
+ text: it.str,
174
+ x: it.transform[4],
175
+ y: it.transform[5],
176
+ w: it.width,
177
+ h: it.height,
178
+ }));
179
+ console.log(`page ${i} - ${items.length} runs`);
180
+ }
181
+ }
182
+ ```
183
+
184
+ Pull form/annotation metadata:
185
+
186
+ ```javascript
187
+ async function annotations() {
188
+ const pdf = await pdfjsLib.getDocument('annotated.pdf').promise;
189
+ for (let i = 1; i <= pdf.numPages; i++) {
190
+ const pg = await pdf.getPage(i);
191
+ for (const a of await pg.getAnnotations()) {
192
+ console.log(a.subtype, a.contents, a.rect);
193
+ }
194
+ }
195
+ }
196
+ ```
197
+
198
+ ---
199
+
200
+ ## 3. Heavy CLI Recipes
201
+
202
+ ### 3.1 poppler-utils (advanced)
203
+
204
+ ```bash
205
+ # Text + bounding boxes (XML)
206
+ pdftotext -bbox-layout invoice.pdf invoice.xml
207
+
208
+ # Render with explicit DPI
209
+ pdftoppm -png -r 300 invoice.pdf out_prefix
210
+
211
+ # Range with high resolution
212
+ pdftoppm -png -r 600 -f 1 -l 3 invoice.pdf high_res
213
+
214
+ # JPEG with quality knob
215
+ pdftoppm -jpeg -jpegopt quality=85 -r 200 invoice.pdf jpeg_out
216
+
217
+ # Pull all images, with metadata
218
+ pdfimages -j -p invoice.pdf images/
219
+
220
+ # List images without extracting
221
+ pdfimages -list invoice.pdf
222
+
223
+ # Original-format extraction
224
+ pdfimages -all invoice.pdf images/img
225
+ ```
226
+
227
+ ### 3.2 qpdf (advanced)
228
+
229
+ ```bash
230
+ # Split into N-page chunks
231
+ qpdf --split-pages=3 invoice.pdf out_%02d.pdf
232
+
233
+ # Custom page picks
234
+ qpdf invoice.pdf --pages invoice.pdf 1,3-5,8,10-end -- subset.pdf
235
+
236
+ # Cross-document merge with per-source ranges
237
+ qpdf --empty --pages a.pdf 1-3 b.pdf 5-7 c.pdf 2,4 -- combined.pdf
238
+
239
+ # Linearise for streaming
240
+ qpdf --linearize invoice.pdf invoice-web.pdf
241
+
242
+ # Optimisation
243
+ qpdf --optimize-level=all invoice.pdf invoice-small.pdf
244
+
245
+ # Repair
246
+ qpdf --check broken.pdf
247
+ qpdf --fix-qdf damaged.pdf repaired.pdf
248
+
249
+ # Encryption with explicit permissions
250
+ qpdf --encrypt user_pw owner_pw 256 --print=none --modify=none -- in.pdf out.pdf
251
+
252
+ # Inspection
253
+ qpdf --show-encryption out.pdf
254
+ qpdf --password=pw --decrypt out.pdf clear.pdf
255
+ qpdf --show-all-pages invoice.pdf > structure.txt
256
+ ```
257
+
258
+ ### 3.3 pdftk (fallback when qpdf is unavailable)
259
+
260
+ `pdftk` predates qpdf and survives on systems where qpdf is hard to install
261
+ (some old Linux distros, locked-down corporate machines). Recipes are coarser
262
+ than qpdf but the binary is widely packaged.
263
+
264
+ ```bash
265
+ # Merge
266
+ pdftk a.pdf b.pdf cat output merged.pdf
267
+
268
+ # Split into one file per page
269
+ pdftk input.pdf burst # produces pg_0001.pdf, pg_0002.pdf, ...
270
+
271
+ # Rotate single pages (east = +90 clockwise, west = -90, south = 180)
272
+ pdftk input.pdf rotate 1east output rotated.pdf
273
+
274
+ # Concatenate selected page ranges across files
275
+ pdftk A=a.pdf B=b.pdf cat A1-3 B5-7 output combined.pdf
276
+
277
+ # Encrypt (AES-128)
278
+ pdftk input.pdf output secured.pdf owner_pw owner_pass user_pw user_pass
279
+
280
+ # Decrypt (requires owner password)
281
+ pdftk secured.pdf input_pw owner_pass output clear.pdf
282
+ ```
283
+
284
+ Prefer qpdf where both are installed: qpdf has finer optimisation knobs,
285
+ better repair, and AES-256 support; pdftk is the safety net.
286
+
287
+ ---
288
+
289
+ ## 4. Advanced Python
290
+
291
+ ### 4.1 pdfplumber — coordinate-aware extraction
292
+
293
+ ```python
294
+ import pdfplumber
295
+ with pdfplumber.open("payslip.pdf") as src_doc:
296
+ pg = src_doc.pages[0]
297
+ for ch in pg.chars[:10]:
298
+ print(ch["text"], ch["x0"], ch["top"])
299
+ region = pg.within_bbox((100, 100, 400, 200)).extract_text()
300
+ ```
301
+
302
+ Custom table strategy:
303
+
304
+ ```python
305
+ import pdfplumber
306
+ import pandas as pd
307
+
308
+ with pdfplumber.open("complex_table.pdf") as src_doc:
309
+ pg = src_doc.pages[0]
310
+ settings = {
311
+ "vertical_strategy": "lines",
312
+ "horizontal_strategy": "lines",
313
+ "snap_tolerance": 3,
314
+ "intersection_tolerance": 15,
315
+ }
316
+ tbls = pg.extract_tables(settings)
317
+ pg.to_image(resolution=150).save("debug.png")
318
+ ```
319
+
320
+ ### 4.2 reportlab — styled tables
321
+
322
+ ```python
323
+ from reportlab.platypus import (
324
+ SimpleDocTemplate, Table, TableStyle, Paragraph,
325
+ )
326
+ from reportlab.lib.styles import getSampleStyleSheet
327
+ from reportlab.lib import colors
328
+
329
+ rows = [
330
+ ["Product", "Q1", "Q2", "Q3", "Q4"],
331
+ ["Widgets", "120", "135", "142", "158"],
332
+ ["Gadgets", "85", "92", "98", "105"],
333
+ ]
334
+
335
+ doc = SimpleDocTemplate("sales.pdf")
336
+ story = [Paragraph("Quarterly Sales", getSampleStyleSheet()["Title"])]
337
+ tbl = Table(rows)
338
+ tbl.setStyle(TableStyle([
339
+ ("BACKGROUND", (0, 0), (-1, 0), colors.grey),
340
+ ("TEXTCOLOR", (0, 0), (-1, 0), colors.whitesmoke),
341
+ ("ALIGN", (0, 0), (-1, -1), "CENTER"),
342
+ ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
343
+ ("FONTSIZE", (0, 0), (-1, 0), 14),
344
+ ("BOTTOMPADDING", (0, 0), (-1, 0), 12),
345
+ ("BACKGROUND", (0, 1), (-1, -1), colors.beige),
346
+ ("GRID", (0, 0), (-1, -1), 1, colors.black),
347
+ ]))
348
+ story.append(tbl)
349
+ doc.build(story)
350
+ ```
351
+
352
+ ---
353
+
354
+ ## 5. Annotations, Signatures, and Text Overlay
355
+
356
+ Three related mutation routes for annotating an existing PDF without
357
+ rebuilding the page. All keep the original content stream intact and
358
+ either add an annotation object or stack an overlay on top.
359
+
360
+ ### 5.1 Sticky note annotations (`/Text` subtype)
361
+
362
+ Sticky notes show as a clickable icon in Adobe Acrobat / macOS Preview;
363
+ the comment text appears when the icon is opened.
364
+
365
+ ```python
366
+ from pypdf import PdfReader, PdfWriter
367
+ from pypdf.generic import (
368
+ DictionaryObject, ArrayObject, FloatObject,
369
+ NameObject, TextStringObject, NumberObject, BooleanObject,
370
+ )
371
+
372
+ def make_sticky_note(x, y, w, h, *, subject, contents, color=(1, 1, 0)):
373
+ annot = DictionaryObject()
374
+ annot[NameObject("/Type")] = NameObject("/Annot")
375
+ annot[NameObject("/Subtype")] = NameObject("/Text")
376
+ annot[NameObject("/Rect")] = ArrayObject([
377
+ FloatObject(x), FloatObject(y),
378
+ FloatObject(x + w), FloatObject(y + h),
379
+ ])
380
+ annot[NameObject("/T")] = TextStringObject("Reviewer")
381
+ annot[NameObject("/Subj")] = TextStringObject(subject)
382
+ annot[NameObject("/Contents")] = TextStringObject(contents)
383
+ annot[NameObject("/Open")] = BooleanObject(False)
384
+ annot[NameObject("/C")] = ArrayObject([FloatObject(c) for c in color])
385
+ annot[NameObject("/F")] = NumberObject(4) # Print flag
386
+ annot[NameObject("/Name")] = NameObject("/Note")
387
+ return annot
388
+
389
+ reader = PdfReader("input.pdf")
390
+ writer = PdfWriter()
391
+ for pg in reader.pages:
392
+ writer.add_page(pg)
393
+
394
+ page = writer.pages[0]
395
+ page_h = float(page.mediabox.height)
396
+
397
+ # pdfplumber `top` is from the page TOP; pypdf y is from the page BOTTOM:
398
+ # pypdf_y = page_h - pdfplumber_top
399
+ note = make_sticky_note(54, page_h - 270, 20, 20,
400
+ subject="Review", contents="Must order!")
401
+ note_ref = writer._add_object(note)
402
+
403
+ # Append to the existing /Annots, never overwrite:
404
+ existing = page.get("/Annots")
405
+ existing_list = list(existing) if existing else []
406
+ existing_list.append(note_ref)
407
+ page[NameObject("/Annots")] = ArrayObject(existing_list)
408
+
409
+ with open("output.pdf", "wb") as fp:
410
+ writer.write(fp)
411
+ ```
412
+
413
+ Notes:
414
+
415
+ - `/F` = 4 sets the Print flag — without it some viewers omit the
416
+ annotation when printing.
417
+ - `/C` is a 0-1 RGB tuple, not 0-255.
418
+ - Chromium's built-in PDF viewer ignores annotations; verify with
419
+ Acrobat, Preview, or `pdftotext -annotate`.
420
+
421
+ ### 5.2 Visible signatures and stamps (`/FreeText` subtype)
422
+
423
+ `FreeText` renders text directly on the page (no click-to-open icon) —
424
+ the standard way to add a visible signature, date stamp, or watermark
425
+ without rebuilding the page.
426
+
427
+ ```python
428
+ sig = DictionaryObject()
429
+ sig[NameObject("/Type")] = NameObject("/Annot")
430
+ sig[NameObject("/Subtype")] = NameObject("/FreeText")
431
+ sig[NameObject("/Rect")] = ArrayObject([
432
+ FloatObject(x), FloatObject(y),
433
+ FloatObject(x + width), FloatObject(y + height),
434
+ ])
435
+ sig[NameObject("/Contents")] = TextStringObject("J. Doe\n2026.04.21")
436
+ # /DA = "/FontName Size Tf R G B rg" (RGB are 0-1)
437
+ sig[NameObject("/DA")] = TextStringObject("/Helvetica 16 Tf 0.1 0.1 0.35 rg")
438
+ sig[NameObject("/F")] = NumberObject(4)
439
+ sig[NameObject("/C")] = ArrayObject([]) # no border
440
+ sig[NameObject("/IC")] = ArrayObject([]) # transparent fill
441
+ sig[NameObject("/BS")] = DictionaryObject({
442
+ NameObject("/W"): FloatObject(0),
443
+ })
444
+ sig[NameObject("/Q")] = NumberObject(2) # 0=left, 1=center, 2=right
445
+ ```
446
+
447
+ Notes:
448
+
449
+ - `/DA` font names are limited to PDF built-ins (`/Helvetica`,
450
+ `/Times-Roman`, `/Courier`). **Built-ins do not cover CJK** — for
451
+ Chinese / Japanese / Korean signatures, drop down to the overlay
452
+ route in §5.3.
453
+ - `/Q` is text alignment: 0/1/2 = left/center/right.
454
+ - Set `/IC` to `[r, g, b]` instead of `[]` if you want a coloured fill
455
+ behind the text (e.g. a yellow highlight).
456
+
457
+ ### 5.3 Replace text via white-out + overlay (works with CJK)
458
+
459
+ PDF text lives inside compressed content streams; editing it in place
460
+ is impractical. The reliable approach is **white box on top of the
461
+ original + new text on top of the white box, all merged as an overlay
462
+ page**:
463
+
464
+ 1. Locate the original text with `pdfplumber` (gives x0/x1/top/bottom).
465
+ 2. Build an overlay page in `reportlab` with a white rectangle and the
466
+ replacement text.
467
+ 3. Call `merge_page(overlay)` to stack the overlay above the original.
468
+
469
+ ```python
470
+ import io
471
+ import pdfplumber
472
+ from reportlab.pdfgen import canvas
473
+ from reportlab.pdfbase import pdfmetrics
474
+ from reportlab.pdfbase.ttfonts import TTFont
475
+ from pypdf import PdfReader, PdfWriter
476
+
477
+ # 1. Find the source coordinates.
478
+ with pdfplumber.open("menu.pdf") as src:
479
+ pg = src.pages[0]
480
+ page_w, page_h = float(pg.width), float(pg.height)
481
+ target = next(w for w in pg.extract_words() if "胡麻豆腐" in w["text"])
482
+ # target = {"text": "胡麻豆腐", "x0": 54.75, "x1": 97.58,
483
+ # "top": 255.77, "bottom": 266.48, ...}
484
+
485
+ # Convert pdfplumber-top to reportlab-y (origin at page bottom):
486
+ rl_y_bottom = page_h - target["bottom"]
487
+ rl_y_top = page_h - target["top"]
488
+
489
+ # 2. Draw the overlay (white box + new text).
490
+ pdfmetrics.registerFont(TTFont(
491
+ "DroidSans", "/usr/share/fonts/truetype/droid/DroidSansFallbackFull.ttf",
492
+ ))
493
+ packet = io.BytesIO()
494
+ c = canvas.Canvas(packet, pagesize=(page_w, page_h))
495
+ c.setFillColorRGB(1, 1, 1)
496
+ c.rect(target["x0"] - 2, rl_y_bottom - 2,
497
+ (target["x1"] - target["x0"]) + 4,
498
+ (rl_y_top - rl_y_bottom) + 4,
499
+ fill=1, stroke=0) # pad ~2pt to swallow ink fringes
500
+ c.setFont("DroidSans", 11)
501
+ c.setFillColorRGB(0.18, 0.12, 0.05) # match the original ink colour
502
+ c.drawString(target["x0"], rl_y_bottom + 2, "世东豆腐")
503
+ c.save()
504
+ packet.seek(0)
505
+
506
+ # 3. Merge the overlay into the original page.
507
+ reader = PdfReader("menu.pdf")
508
+ overlay = PdfReader(packet).pages[0]
509
+ writer = PdfWriter()
510
+ for i, page in enumerate(reader.pages):
511
+ if i == 0:
512
+ page.merge_page(overlay) # overlay stacks ABOVE original
513
+ writer.add_page(page)
514
+ with open("menu_patched.pdf", "wb") as fp:
515
+ writer.write(fp)
516
+ ```
517
+
518
+ Coordinate cheat sheet:
519
+
520
+ ```
521
+ pdfplumber top -> distance from page TOP (top axis)
522
+ reportlab y -> distance from page BOTTOM (bottom axis)
523
+ pypdf y -> distance from page BOTTOM (bottom axis)
524
+
525
+ reportlab_y = page_height - pdfplumber_top
526
+ ```
527
+
528
+ Notes:
529
+
530
+ - Pad the white rectangle by 2-4pt on each side to swallow
531
+ anti-aliasing fringes on the original glyphs.
532
+ - For colour match, render the source page to PNG (use
533
+ `python -m scripts.render.page_rasterize`), sample the ink with any
534
+ colour picker, and divide each channel by 255 to get the reportlab
535
+ triplet (e.g. RGB(46, 30, 13) -> `(0.18, 0.12, 0.05)`).
536
+ - CJK text needs a TTF font registered via `TTFont(...)` — built-in
537
+ fonts only cover Latin-1.
538
+ - `merge_page(overlay)` stacks `overlay` **above** the original in the
539
+ content stream — that is what makes the white box hide the original
540
+ ink and the new text sit on top of the white box.
541
+
542
+ ### 5.4 Common pitfalls
543
+
544
+ | Symptom | Likely cause | Fix |
545
+ |---|---|---|
546
+ | Annotation invisible when printing | `/F` flag missing or wrong | set `/F` to `4` (Print) |
547
+ | Sticky note disappears after a second pass | `/Annots` was overwritten, not appended | `list(page.get("/Annots") or [])` then append |
548
+ | Chinese characters render as boxes in `/FreeText` | built-in fonts don't cover CJK | switch to the overlay route in §5.3 |
549
+ | White box covers the wrong region | mixed up pdfplumber top vs reportlab y | `reportlab_y = page_h - pdfplumber_top` |
550
+ | Original ink shows through the edges of the white box | rectangle too tight | pad by 2-4pt on each side |
551
+ | Overlay text appears underneath the white box | `merge_page` direction reversed | call `original.merge_page(overlay)` so the overlay goes on top |
552
+
553
+ ---
554
+
555
+ ## 6. Workflows
556
+
557
+ ### 5.1 Extract figures from a PDF
558
+
559
+ Fast path with poppler:
560
+
561
+ ```bash
562
+ pdfimages -all invoice.pdf images/img
563
+ ```
564
+
565
+ Detect-and-crop with pypdfium2 plus numpy:
566
+
567
+ ```python
568
+ import pypdfium2 as pdfium
569
+ import numpy as np
570
+
571
+ def figures(pdf_path):
572
+ src_doc = pdfium.PdfDocument(pdf_path)
573
+ for i, pg in enumerate(src_doc):
574
+ bitmap = pg.render(scale=3.0)
575
+ arr = np.array(bitmap.to_pil())
576
+ non_white = np.any(arr != [255, 255, 255], axis=2)
577
+ # Plug your favourite contour finder in here.
578
+ yield i, non_white.sum()
579
+ ```
580
+
581
+ ### 5.2 Batch processing with error handling
582
+
583
+ ```python
584
+ import glob, logging, os
585
+ from pypdf import PdfReader, PdfWriter
586
+
587
+ logging.basicConfig(level=logging.INFO)
588
+ log = logging.getLogger(__name__)
589
+
590
+ def merge(folder):
591
+ out_doc = PdfWriter()
592
+ for path in glob.glob(os.path.join(folder, "*.pdf")):
593
+ try:
594
+ for pg in PdfReader(path).pages:
595
+ out_doc.add_page(pg)
596
+ log.info("ok %s", path)
597
+ except Exception as exc: # noqa: BLE001
598
+ log.error("skip %s: %s", path, exc)
599
+ with open("merged.pdf", "wb") as fp:
600
+ out_doc.write(fp)
601
+
602
+ def dump_text(folder):
603
+ for path in glob.glob(os.path.join(folder, "*.pdf")):
604
+ try:
605
+ text = "".join(pg.extract_text() for pg in PdfReader(path).pages)
606
+ with open(path.replace(".pdf", ".txt"), "w", encoding="utf-8") as fp:
607
+ fp.write(text)
608
+ except Exception as exc: # noqa: BLE001
609
+ log.error("skip %s: %s", path, exc)
610
+ ```
611
+
612
+ ### 5.3 Crop pages
613
+
614
+ ```python
615
+ from pypdf import PdfReader, PdfWriter
616
+
617
+ src_doc = PdfReader("invoice.pdf")
618
+ out_doc = PdfWriter()
619
+
620
+ pg = src_doc.pages[0]
621
+ pg.mediabox.left = 50
622
+ pg.mediabox.bottom = 50
623
+ pg.mediabox.right = 550
624
+ pg.mediabox.top = 750
625
+ out_doc.add_page(pg)
626
+
627
+ with open("invoice_cropped.pdf", "wb") as fp:
628
+ out_doc.write(fp)
629
+ ```
630
+
631
+ ---
632
+
633
+ ## 7. Performance Tips
634
+
635
+ 1. **Large PDFs** — stream pages with `pypdf`/`pypdfium2`, never load
636
+ the entire file in RAM. Use `qpdf --split-pages` to chunk.
637
+ 2. **Text extraction** — `pdftotext -bbox-layout` is fastest for plain
638
+ text; `pdfplumber` is the right tool when you need tables;
639
+ `pypdf.extract_text()` is the slowest option for big documents.
640
+ 3. **Image extraction** — `pdfimages` is faster than rendering each
641
+ page yourself; render only when you actually need the rasterised
642
+ pixels (e.g. for OCR or visual overlay).
643
+ 4. **Form filling** — pre-validate the input config (the bundled
644
+ `geometry_lint` does this for the overlay path); for AcroForm,
645
+ trust `acroform_apply` to validate against the discovered schema.
646
+ 5. **Memory management** — process pages in chunks:
647
+
648
+ ```python
649
+ from pypdf import PdfReader, PdfWriter
650
+
651
+ def chunked(path, chunk=10):
652
+ src_doc = PdfReader(path)
653
+ total = len(src_doc.pages)
654
+ for start in range(0, total, chunk):
655
+ out_doc = PdfWriter()
656
+ for i in range(start, min(start + chunk, total)):
657
+ out_doc.add_page(src_doc.pages[i])
658
+ with open(f"chunk_{start // chunk}.pdf", "wb") as fp:
659
+ out_doc.write(fp)
660
+ ```
661
+
662
+ ---
663
+
664
+ ## 8. Troubleshooting
665
+
666
+ ### Encrypted PDFs
667
+
668
+ ```python
669
+ from pypdf import PdfReader
670
+
671
+ src_doc = PdfReader("encrypted.pdf")
672
+ if src_doc.is_encrypted:
673
+ src_doc.decrypt("password")
674
+ ```
675
+
676
+ ### Corrupted PDFs
677
+
678
+ ```bash
679
+ qpdf --check corrupted.pdf
680
+ qpdf --replace-input corrupted.pdf
681
+ ```
682
+
683
+ ### Scanned PDFs (no text layer)
684
+
685
+ ```python
686
+ import pytesseract
687
+ from pdf2image import convert_from_path
688
+
689
+ def ocr(pdf_path):
690
+ return "".join(
691
+ pytesseract.image_to_string(img)
692
+ for img in convert_from_path(pdf_path)
693
+ )
694
+ ```
695
+
696
+ ---
697
+
698
+ ## 9. Third-Party Library Licenses
699
+
700
+ | Library | License |
701
+ | ------------ | --------- |
702
+ | pypdf | BSD |
703
+ | pdfplumber | MIT |
704
+ | pypdfium2 | Apache/BSD |
705
+ | reportlab | BSD |
706
+ | pdf2image | MIT |
707
+ | Pillow | HPND (PIL) |
708
+ | poppler-utils | GPL-2 |
709
+ | qpdf | Apache |
710
+ | pdf-lib | MIT |
711
+ | pdfjs-dist | Apache |