bentopdf/tasks/lessons.md

• Compare tool overlay regressions: check shared CSS before changing page logic; global canvas positioning rules can hide rendered PDF content while leaving highlight layers visible.
• When hardening code after a type-safety follow-up, never leave empty catch {} blocks in the touched path. Either guard the risky call up front or catch the error into a variable and handle it intentionally with a safe fallback, warning, or typed default.
• When adding or refining form creator models, keep reusable types and interfaces in src/js/types instead of defining them inline in logic files or tests. Logic modules should import shared types rather than owning them.
• Shared app types must be exported from src/js/types/index.ts and imported through the @/types alias. Do not import shared types from individual type files or relative types/index paths in feature code or tests.
• After a user correction about type safety, capture the lesson immediately: never leave any in a bug fix if the surrounding library types can be modeled or narrowed. Prefer extracting the logic into a typed helper and adding regression tests for the corrected path.
• pdf.js assigns document-scoped font name prefixes (g_d0_, g_d1_, ...) per loaded document. Always normalize these before comparing font names across documents to avoid false positive style changes.
• LibreOffice PDF conversion support can depend on explicit import filters. Before concluding soffice or LibreOffice WASM cannot convert pdf -> docx/pptx, test the exact filtered path such as --infilter=writer_pdf_import or --infilter=impress_pdf_import and inspect wrapper code for hardcoded capability gates.
• LibreOfficeKit documentLoadWithOptions() is not the same as CLI --infilter. In the current WASM/LOK build, the options string is forwarded as FilterOptions, not media-descriptor FilterName, so passing FilterName=writer_pdf_import from JS does not force PDF to load as Writer or Impress.
• When a consolidated patch contains unrelated features (e.g. abort API + PDF filter fix), a compile failure in one breaks the whole build. Never bundle unrelated features in one patch — split by concern. If already bundled, surgically remove the broken feature from the single patch rather than layering a second "undo" patch on top.
• Never add new C++ APIs (enums, functions) to a WASM build patch without confirming the header declarations are visible at compile time in all translation units that use them. The OperationType enum was declared in lok.hxx but the .cxx failed because of include ordering or missing header propagation.
• When removing hunks from a unified diff patch: (1) update hunk line counts in @@ headers, (2) remove entire file sections if no +/- lines remain, (3) verify the old-side line numbers still match the actual source (removing earlier hunks shifts offsets), (4) verify the - lines match the actual source text character-for-character (e.g. xInteraction vs uno::Reference<task::XInteractionHandler2>(pInteraction)).
• ALWAYS check the existing API before rebuilding WASM or forking libraries. The matbee libreoffice-converter already had inputFilter support in ConversionOptions, browser.worker.ts, and buildLoadOptions(). The entire WASM rebuild was unnecessary and replacing browser.worker.global.js with a fork build caused a DeploymentException that broke all LibreOffice conversions.
• Never replace compiled vendor assets (browser.worker.global.js, soffice.wasm.gz, etc.) unless absolutely necessary. These are tightly coupled and a mismatched worker JS + WASM binary causes initialization failures.