feat: extract and describe embedded images in DOCX files

[olearydj]

Summary

The DOCX converter currently uses mammoth's default HTML conversion which drops embedded images. This PR adds image extraction via mammoth's convertImage hook and a custom Turndown rule, giving DOCX files the same AI-powered image description capability that standalone image files and PPTX files (PR #6) already have.

Approach

Uses mammoth's images.imgElement callback to capture image buffers during HTML conversion, then a custom Turndown rule to convert placeholder <img> nodes into final markdown. This avoids post-Turndown string replacement, which breaks in structured contexts (tables, lists) and with escaped alt text.

Changes

• Accept options parameter in the DOCX converter's convert method
• Capture image buffers via mammoth's convertImage hook
• Resolve descriptions via options.describe before Turndown runs
• Custom Turndown rule emits markdown directly, preserving:
  • Structured context (table cells get <br> inline format)
  • Description markdown from the provider (passed through verbatim)
  • Escaped alt text (no regex matching against Turndown output)
• Local TurndownNodeLike type avoids DOM lib dependency in tsconfig
• 14 tests covering placeholders, alt text, describe callback, markdown preservation, $ sequence safety, error fallback, table cell images, and no raw placeholder tokens
• DOCX test fixture with images in body text and table cells

Behavior

Without API key: images produce *[Image: alt text]* placeholders or *[Image N]* when no alt text exists.

With configured provider: each embedded image is described via the same options.describe pipeline used by standalone image files, producing **[Image: label]** followed by the description markdown.

In table cells: output uses inline <br> format to avoid breaking table structure.

Error handling: if describe throws, falls back to placeholder text.

Test plan

• bun run build — clean tsc compilation
• bun test — 72 tests pass (58 existing + 14 new), 0 failures
• Manual test on DOCX with cat/dog images — descriptions generated correctly with Anthropic provider
• bun run check — biome passes

🤖 Generated with Claude Code

[Michaelliv]

thanks @olearydj! same as #6, added docx image extraction too. closing in favor of that, appreciate both PRs!

[olearydj]

Thanks for the clarification here. I understand and respect the choice to keep image handling extract-first by default.

One counter-proposal that might preserve that direction while covering a different workflow would be to make description-at-conversion-time an opt-in mode rather than a behavior change. It is something I commonly use in my workflows and had implemented in my own, less less sophisticated tool, but missed it here.

Something like:

• default stays extract
• add --image-mode extract|describe|both (or a narrower --describe-images flag)
• extract: current behavior unchanged
• describe: emit self-contained markdown descriptions/placeholders via the existing describe pipeline
• both: extract files and also emit descriptions

Why I think this could be worth supporting:

• no default behavior change
• supports self-contained markdown for downstream agents/indexing/search
• avoids repeated downstream vision passes for users who want one-shot conversion
• can reuse the existing describe hook instead of introducing a separate provider path

Let me know if you are open to that approach.