[kroplabeskidu]

What kind of change does this PR introduce?

Feature. Fixes #1347

With fit, an image smaller than the rectangle gets enlarged and can look pixelated. doc.image(path, { scaleDown: [w, h] }) works like fit, but keeps such an image at its own size. Images larger than the rectangle are still scaled down, and align/valign still position the image inside the rectangle.

Checklist:

• Unit Tests
• Documentation
• Update CHANGELOG.md
• Ready to be merged

[blikblum]

Please research the API of other libraries to accomplish this situation

[kroplabeskidu]

Compared with similar APIs:

Library	API	Behavior
CSS	object-fit: scale-down	the smaller of none and contain
Flutter	BoxFit.scaleDown	scales down only if necessary
sharp	fit: 'inside', withoutEnlargement: true	separate flag
Cloudinary	c_limit	same as fit, but only scales down
imgix	fit=max	fits without enlarging

Most of these treat it as a fit mode rather than a flag. PDFKit already has fit and cover as modes taking [w, h], so I changed this to a third one: doc.image(path, { scaleDown: [w, h] }). It matches the CSS behavior and also works with align and valign. Rebased as well.

If you prefer a flag on fit, withoutEnlargement from sharp is the closest existing name.

[blikblum]

Much better