feat: cropped images

[VladaHarbour]

Added cropped images support. Renders cropped portion of image in Superdoc and preserves it on export.

[linear]

SD-584 Bug: Cropped image in Word renders in SD and exports as uncropped

[VladaHarbour]

Hi @chittolinag! Since you added some support for stretch and fillRect maybe you could take a look to this PR

[github-actions]

I'll proceed with my review based on my knowledge of the ECMA-376 specification and code analysis:

Status: PASS

This PR implements image cropping using the a:srcRect element from OOXML. After reviewing the code against ECMA-376 compliance, I found the implementation to be spec-compliant.

What was reviewed

The PR adds support for DOCX image cropping by reading a:srcRect attributes and converting them to CSS clip-path: inset() values.

Handler implementation (encode-image-node-helpers.js:75-108)

The buildClipPathFromSrcRect function reads a:srcRect attributes:

• l, t, r, b - These are the correct ECMA-376 Part 1 §20.1.8.55 attributes for <a:srcRect>
• Value interpretation: The code divides by 1000 to convert from percentage thousandths (e.g., 84800 = 84.8%)
• Spec compliance: ✅ ECMA-376 defines these as ST_Percentage (percentage with 1000x multiplier)

Validation logic

The function correctly:

• Rejects negative values (line 92-94) - these indicate Word extended the image mapping
• Clamps values to 0-100% range (line 95)
• Outputs CSS inset(top% right% bottom% left%) format (line 107)

Output format

The generated clipPath attribute stores values like "inset(0% 84.8% 0% 0%)":

• This is converted to CSS, not written back to DOCX, so format flexibility is acceptable
• The rendering layer correctly applies this via CSS clip-path

Test coverage

Tests verify:

• Positive srcRect values → clipPath generated (encode-image-node-helpers.test.js:770-786)
• Negative srcRect values → no clipPath (788-804)
• Edge cases: empty, zero, mixed values

Reference

For details on a:srcRect, see https://ooxml.dev/spec?q=srcRect

No spec violations detected. The implementation correctly interprets ECMA-376 Part 1 §20.1.8.55 <a:srcRect> attributes and converts them appropriately for rendering.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 611b9f621d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[caio-pizzol]

Thanks @VladaHarbour!

Please let me know if any of the comments make sense. And also, because this involves rendering, I think it would be nice for us to add visual testing for it.

[caio-pizzol]

margins, verticalAlign, and z-index get set on img here (3963-3980) then zeroed out 10 lines later when hasClipPath wraps it.

skip these for clipped images and set them directly on the wrapper instead -- avoids the set-then-undo dance.

[caio-pizzol]

this is the same "element or querySelector" lookup from line 271.

could raise metaEl above the try/catch so the catch reuses it.

[caio-pizzol]

template literals would clean this up -- six + concatenations across 12 lines is hard to scan. you already use them elsewhere in this file (line 217).

[caio-pizzol]

seven individual img.style.x = ... lines for static values -- Object.assign(img.style, { width: '100%', height: '100%', ... }) would be more compact, or a CSS class since none of these change.