@nguyenphp/antigravity-marketing 1.0.18 → 1.0.20

package/templates/.agent/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Core/Samples/ImageSamples.cs

@@ -0,0 +1,917 @@
+// ============================================================================
+// ImageSamples.cs — Comprehensive OpenXML image handling reference
+// ============================================================================
+// EMU (English Metric Unit) is the universal measurement in DrawingML:
+//   1 inch   = 914400 EMU
+//   1 cm     = 360000 EMU
+//   1 px@96dpi = 9525 EMU  (914400 / 96 = 9525)
+//
+// Image architecture in OpenXML:
+//   Paragraph → Run → Drawing → DW.Inline (or DW.Anchor)
+//     → A.Graphic → A.GraphicData → PIC.Picture
+//       → PIC.BlipFill → A.Blip (references the image part via r:embed)
+//       → PIC.ShapeProperties → A.Transform2D → A.Extents (cx, cy)
+//
+// CRITICAL RULES:
+//   1. Extent.Cx/Cy on DW.Inline/DW.Anchor MUST match A.Extents.Cx/Cy
+//      on PIC.ShapeProperties. Mismatch causes rendering issues.
+//   2. Each Drawing element needs a unique DocProperties.Id within the document.
+//   3. ImagePart must be added to the PART that references it:
+//      - MainDocumentPart for images in body
+//      - HeaderPart for images in headers
+//      - FooterPart for images in footers
+//   4. Blip.Embed contains the relationship ID (rId) linking to the ImagePart.
+// ============================================================================
+
+using DocumentFormat.OpenXml;
+using DocumentFormat.OpenXml.Packaging;
+using DocumentFormat.OpenXml.Wordprocessing;
+
+using A = DocumentFormat.OpenXml.Drawing;
+using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
+using PIC = DocumentFormat.OpenXml.Drawing.Pictures;
+
+namespace MiniMaxAIDocx.Core.Samples;
+
+/// <summary>
+/// Reference implementations for every common image operation in OpenXML.
+/// All methods produce valid, Word-renderable markup.
+/// </summary>
+public static class ImageSamples
+{
+    // ── Constants ──────────────────────────────────────────────────────
+    private const long EmuPerInch = 914400L;
+    private const long EmuPerCm = 360000L;
+    private const long EmuPerPixel96Dpi = 9525L; // 914400 / 96
+
+    // GraphicData URI that tells Word "this is a picture"
+    private const string PicGraphicDataUri = "http://schemas.openxmlformats.org/drawingml/2006/picture";
+
+    // ── 1. Inline Image (most common) ──────────────────────────────────
+
+    /// <summary>
+    /// Inserts an inline image into the body. Inline images flow with text
+    /// and do not float. This is the most common image insertion pattern.
+    /// </summary>
+    /// <param name="mainPart">The MainDocumentPart to add the image relationship to.</param>
+    /// <param name="body">The Body element to append the paragraph to.</param>
+    /// <param name="imagePath">Filesystem path to the image file (png, jpg, etc.).</param>
+    /// <param name="widthPx">Desired display width in pixels (at 96 dpi).</param>
+    /// <param name="heightPx">Desired display height in pixels (at 96 dpi).</param>
+    public static void InsertInlineImage(
+        MainDocumentPart mainPart, Body body,
+        string imagePath, int widthPx, int heightPx)
+    {
+        // Step 1: Add the image file as a part. The ImagePartType must match
+        // the actual file format. AddImagePart returns the ImagePart; we then
+        // feed data into it.
+        var imageType = GetImagePartType(imagePath);
+        ImagePart imagePart = mainPart.AddImagePart(imageType);
+
+        using (FileStream stream = new FileStream(imagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+
+        // Step 2: Get the relationship ID that links the Blip to this ImagePart.
+        string relId = mainPart.GetIdOfPart(imagePart);
+
+        // Step 3: Convert pixel dimensions to EMU.
+        // Formula: pixels * 9525 = EMU (at 96 dpi, which is Word's assumption)
+        long cx = widthPx * EmuPerPixel96Dpi;
+        long cy = heightPx * EmuPerPixel96Dpi;
+
+        // Step 4: Build the Drawing element using the reusable helper.
+        // docPropId must be unique across the entire document.
+        Drawing drawing = BuildDrawingElement(
+            relId, cx, cy,
+            docPropId: 1U,
+            name: "Image1",
+            description: null);
+
+        // Step 5: Wrap in Paragraph → Run → Drawing
+        Paragraph para = new Paragraph(
+            new Run(drawing));
+
+        body.AppendChild(para);
+    }
+
+    // ── 2. Floating Image (Anchor) ─────────────────────────────────────
+
+    /// <summary>
+    /// Inserts a floating image with absolute positioning using DW.Anchor.
+    /// Floating images are positioned relative to a reference point (page,
+    /// column, paragraph, etc.) and text wraps around them.
+    /// </summary>
+    public static void InsertFloatingImage(
+        MainDocumentPart mainPart, Body body, string imagePath)
+    {
+        ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
+        using (FileStream stream = new FileStream(imagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+        string relId = mainPart.GetIdOfPart(imagePart);
+
+        long cx = (long)(3.0 * EmuPerInch); // 3 inches wide
+        long cy = (long)(2.0 * EmuPerInch); // 2 inches tall
+
+        // DW.Anchor is used instead of DW.Inline for floating images.
+        // Key differences from Inline:
+        //   - Has positioning (SimplePos, HorizontalPosition, VerticalPosition)
+        //   - Has wrapping mode (WrapSquare, WrapTight, WrapNone, etc.)
+        //   - Has BehindDoc and LayoutInCell flags
+        DW.Anchor anchor = new DW.Anchor(
+            // SimplePosition: when SimplePos=true, uses SimplePosition x/y directly.
+            // Normally false; we use HorizontalPosition/VerticalPosition instead.
+            new DW.SimplePosition { X = 0L, Y = 0L },
+
+            // HorizontalPosition: where the image sits horizontally.
+            // RelativeFrom can be: Column, Page, Margin, Character, LeftMargin, etc.
+            new DW.HorizontalPosition(
+                new DW.PositionOffset("914400") // 1 inch from reference
+            )
+            { RelativeFrom = DW.HorizontalRelativePositionValues.Column },
+
+            // VerticalPosition: where the image sits vertically.
+            new DW.VerticalPosition(
+                new DW.PositionOffset("457200") // 0.5 inch from reference
+            )
+            { RelativeFrom = DW.VerticalRelativePositionValues.Paragraph },
+
+            // Extent: overall size of the drawing object
+            new DW.Extent { Cx = cx, Cy = cy },
+
+            // EffectExtent: extra space for shadows, glow, etc. (0 if none)
+            new DW.EffectExtent
+            {
+                LeftEdge = 0L,
+                TopEdge = 0L,
+                RightEdge = 0L,
+                BottomEdge = 0L
+            },
+
+            // WrapSquare: text wraps in a square around the image bounding box.
+            new DW.WrapSquare { WrapText = DW.WrapTextValues.BothSides },
+
+            // DocProperties: unique ID + name for the drawing object
+            new DW.DocProperties { Id = 2U, Name = "FloatingImage1" },
+
+            // Non-visual graphic frame properties (required but usually empty)
+            new DW.NonVisualGraphicFrameDrawingProperties(
+                new A.GraphicFrameLocks { NoChangeAspect = true }),
+
+            // The actual graphic content
+            new A.Graphic(
+                new A.GraphicData(
+                    new PIC.Picture(
+                        new PIC.NonVisualPictureProperties(
+                            new PIC.NonVisualDrawingProperties
+                            {
+                                Id = 0U,
+                                Name = "FloatingImage1.png"
+                            },
+                            new PIC.NonVisualPictureDrawingProperties()),
+                        new PIC.BlipFill(
+                            new A.Blip { Embed = relId },
+                            new A.Stretch(new A.FillRectangle())),
+                        new PIC.ShapeProperties(
+                            new A.Transform2D(
+                                new A.Offset { X = 0L, Y = 0L },
+                                // CRITICAL: These cx/cy MUST match the Extent above
+                                new A.Extents { Cx = cx, Cy = cy }),
+                            new A.PresetGeometry(
+                                new A.AdjustValueList())
+                            { Preset = A.ShapeTypeValues.Rectangle }))
+                )
+                { Uri = PicGraphicDataUri })
+        )
+        {
+            // Anchor attributes
+            DistanceFromTop = 0U,
+            DistanceFromBottom = 0U,
+            DistanceFromLeft = 114300U,  // ~0.125 inch gap between text and image
+            DistanceFromRight = 114300U,
+            SimplePos = false,
+            RelativeHeight = 251658240U, // z-order; higher = in front
+            BehindDoc = false,           // true = behind text (like a watermark)
+            Locked = false,
+            LayoutInCell = true,
+            AllowOverlap = true
+        };
+
+        Paragraph para = new Paragraph(new Run(new Drawing(anchor)));
+        body.AppendChild(para);
+    }
+
+    // ── 3. Image with Various Text Wrapping ────────────────────────────
+
+    /// <summary>
+    /// Demonstrates the four main text wrapping modes for floating images.
+    /// Each wrapping mode controls how body text flows around the image.
+    /// </summary>
+    public static void InsertImageWithTextWrapping(
+        MainDocumentPart mainPart, Body body, string imagePath)
+    {
+        // All wrapping modes require DW.Anchor (not DW.Inline).
+        // The wrapping element is a direct child of the Anchor element.
+
+        ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
+        using (FileStream stream = new FileStream(imagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+        string relId = mainPart.GetIdOfPart(imagePart);
+
+        long cx = (long)(2.5 * EmuPerInch);
+        long cy = (long)(2.0 * EmuPerInch);
+
+        // ── WrapSquare ──
+        // Text wraps in a rectangular bounding box around the image.
+        // WrapText controls which sides text appears on.
+        var wrapSquare = new DW.WrapSquare
+        {
+            WrapText = DW.WrapTextValues.BothSides
+            // Other options: Left, Right, Largest
+        };
+
+        // ── WrapTight ──
+        // Text wraps tightly around the actual contour of the image.
+        // Uses a WrapPolygon to define the outline; Word can auto-generate this.
+        // The coordinates are in EMU relative to the image's top-left.
+        var wrapTight = new DW.WrapTight(
+            new DW.WrapPolygon(
+                new DW.StartPoint { X = 0L, Y = 0L },
+                new DW.LineTo { X = 0L, Y = 21600L },
+                new DW.LineTo { X = 21600L, Y = 21600L },
+                new DW.LineTo { X = 21600L, Y = 0L },
+                new DW.LineTo { X = 0L, Y = 0L }
+            )
+            { Edited = false }
+        )
+        {
+            WrapText = DW.WrapTextValues.BothSides
+        };
+
+        // ── WrapTopAndBottom ──
+        // No text appears beside the image. Text only above and below.
+        // This effectively makes the image act as a block-level element
+        // but still floating (not inline).
+        var wrapTopAndBottom = new DW.WrapTopBottom
+        {
+            DistanceFromTop = 0U,
+            DistanceFromBottom = 0U
+        };
+
+        // ── WrapNone ──
+        // No text wrapping at all. Image floats over or behind text.
+        // Combined with BehindDoc=true, this creates a watermark effect.
+        var wrapNone = new DW.WrapNone();
+
+        // Example: build anchor with WrapSquare (swap in any wrapping element above)
+        DW.Anchor anchor = BuildAnchorElement(
+            relId, cx, cy,
+            docPropId: 3U,
+            name: "WrappedImage",
+            wrapElement: wrapSquare,
+            behindDoc: false);
+
+        body.AppendChild(new Paragraph(new Run(new Drawing(anchor))));
+    }
+
+    // ── 4. Image with Border ───────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts an image with a visible outline/border. The border is applied
+    /// via A.Outline on the PIC.ShapeProperties element.
+    /// </summary>
+    public static void InsertImageWithBorder(
+        MainDocumentPart mainPart, Body body, string imagePath)
+    {
+        ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
+        using (FileStream stream = new FileStream(imagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+        string relId = mainPart.GetIdOfPart(imagePart);
+
+        long cx = (long)(3.0 * EmuPerInch);
+        long cy = (long)(2.0 * EmuPerInch);
+
+        // Build PIC.ShapeProperties with an Outline element for the border.
+        // Outline width is in EMU. 1pt = 12700 EMU.
+        var shapeProperties = new PIC.ShapeProperties(
+            new A.Transform2D(
+                new A.Offset { X = 0L, Y = 0L },
+                new A.Extents { Cx = cx, Cy = cy }),
+            new A.PresetGeometry(
+                new A.AdjustValueList())
+            { Preset = A.ShapeTypeValues.Rectangle },
+            // The Outline element defines the border
+            new A.Outline(
+                // SolidFill sets the border color
+                new A.SolidFill(
+                    new A.RgbColorModelHex { Val = "2F5496" }), // Dark blue
+                // PresetDash sets the line style (solid, dash, dot, etc.)
+                new A.PresetDash { Val = A.PresetLineDashValues.Solid }
+            )
+            {
+                Width = 25400, // 2pt border (12700 EMU per pt)
+                CompoundLineType = A.CompoundLineValues.Single
+            }
+        );
+
+        var picture = new PIC.Picture(
+            new PIC.NonVisualPictureProperties(
+                new PIC.NonVisualDrawingProperties { Id = 0U, Name = "BorderedImage.png" },
+                new PIC.NonVisualPictureDrawingProperties()),
+            new PIC.BlipFill(
+                new A.Blip { Embed = relId },
+                new A.Stretch(new A.FillRectangle())),
+            shapeProperties);
+
+        var drawing = new Drawing(
+            new DW.Inline(
+                new DW.Extent { Cx = cx, Cy = cy },
+                new DW.EffectExtent
+                {
+                    // Must account for border width in effect extent so it is not clipped
+                    LeftEdge = 25400L,
+                    TopEdge = 25400L,
+                    RightEdge = 25400L,
+                    BottomEdge = 25400L
+                },
+                new DW.DocProperties { Id = 4U, Name = "BorderedImage" },
+                new DW.NonVisualGraphicFrameDrawingProperties(
+                    new A.GraphicFrameLocks { NoChangeAspect = true }),
+                new A.Graphic(
+                    new A.GraphicData(picture)
+                    { Uri = PicGraphicDataUri })
+            )
+            {
+                DistanceFromTop = 0U,
+                DistanceFromBottom = 0U,
+                DistanceFromLeft = 0U,
+                DistanceFromRight = 0U
+            });
+
+        body.AppendChild(new Paragraph(new Run(drawing)));
+    }
+
+    // ── 5. Image with Alt Text ─────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts an image with alt text for accessibility. The alt text is set
+    /// on the DocProperties.Description attribute. Screen readers use this.
+    /// Word also shows it in the "Alt Text" pane.
+    /// </summary>
+    public static void InsertImageWithAltText(
+        MainDocumentPart mainPart, Body body, string imagePath)
+    {
+        ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
+        using (FileStream stream = new FileStream(imagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+        string relId = mainPart.GetIdOfPart(imagePart);
+
+        long cx = (long)(3.0 * EmuPerInch);
+        long cy = (long)(2.0 * EmuPerInch);
+
+        // DocProperties.Description is the standard alt text field.
+        // DocProperties.Title is an optional short title shown in some UIs.
+        Drawing drawing = BuildDrawingElement(
+            relId, cx, cy,
+            docPropId: 5U,
+            name: "AccessibleImage",
+            description: "A chart showing quarterly revenue growth from Q1 to Q4 2025");
+
+        body.AppendChild(new Paragraph(new Run(drawing)));
+    }
+
+    // ── 6. Image in Header ─────────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts an image into a header part. The image relationship MUST be
+    /// added to the HeaderPart, NOT the MainDocumentPart. If you add it
+    /// to MainDocumentPart, Word will show a broken image in the header
+    /// because relationship IDs are scoped to their containing part.
+    /// </summary>
+    public static void InsertImageInHeader(HeaderPart headerPart, string imagePath)
+    {
+        // CRITICAL: AddImagePart to headerPart, not mainDocumentPart!
+        // Each OpenXML part has its own relationship namespace.
+        // An rId in the header must point to a relationship in the header's .rels file.
+        ImagePart imagePart = headerPart.AddImagePart(GetImagePartType(imagePath));
+        using (FileStream stream = new FileStream(imagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+
+        // GetIdOfPart must also be called on headerPart
+        string relId = headerPart.GetIdOfPart(imagePart);
+
+        long cx = (long)(1.5 * EmuPerInch); // Company logo, typically small
+        long cy = (long)(0.5 * EmuPerInch);
+
+        Drawing drawing = BuildDrawingElement(
+            relId, cx, cy,
+            docPropId: 6U,
+            name: "HeaderLogo",
+            description: "Company logo");
+
+        // Headers use the Header element with Paragraph children (same as Body)
+        Header header = headerPart.Header;
+        Paragraph para = new Paragraph(
+            new ParagraphProperties(
+                new Justification { Val = JustificationValues.Center }),
+            new Run(drawing));
+
+        header.AppendChild(para);
+    }
+
+    // ── 7. Image in Table Cell ─────────────────────────────────────────
+
+    /// <summary>
+    /// Inserts an image into a table cell, sized to fit. Table cells constrain
+    /// content width, so we calculate appropriate dimensions to avoid overflow.
+    /// The image part is still added to MainDocumentPart (the cell is in the body).
+    /// </summary>
+    /// <param name="mainPart">MainDocumentPart (owns the relationship).</param>
+    /// <param name="cell">The TableCell to insert the image into.</param>
+    /// <param name="imagePath">Path to the image file.</param>
+    public static void InsertImageInTableCell(
+        MainDocumentPart mainPart, TableCell cell, string imagePath)
+    {
+        ImagePart imagePart = mainPart.AddImagePart(GetImagePartType(imagePath));
+        using (FileStream stream = new FileStream(imagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+        string relId = mainPart.GetIdOfPart(imagePart);
+
+        // Determine cell width from TableCellWidth if available.
+        // TableCellWidth.Width is in DXA (twentieths of a point).
+        // If not set, use a reasonable default (e.g., 2 inches).
+        long maxWidthEmu = (long)(2.0 * EmuPerInch); // default
+
+        TableCellProperties? tcPr = cell.GetFirstChild<TableCellProperties>();
+        TableCellWidth? tcWidth = tcPr?.GetFirstChild<TableCellWidth>();
+        if (tcWidth?.Width is not null && tcWidth.Type?.Value == TableWidthUnitValues.Dxa)
+        {
+            // Convert DXA to EMU: 1 DXA = 1/20 pt = 1/1440 inch = 914400/1440 EMU
+            int dxa = int.Parse(tcWidth.Width);
+            maxWidthEmu = (long)(dxa * (EmuPerInch / 1440.0));
+        }
+
+        // Calculate image dimensions to fit within the cell width
+        (long cx, long cy) = CalculateImageDimensions(imagePath, maxWidthEmu / (double)EmuPerInch);
+
+        Drawing drawing = BuildDrawingElement(
+            relId, cx, cy,
+            docPropId: 7U,
+            name: "CellImage",
+            description: null);
+
+        // A TableCell MUST contain at least one Paragraph.
+        // We add the image inside that paragraph.
+        Paragraph para = cell.GetFirstChild<Paragraph>() ?? cell.AppendChild(new Paragraph());
+        para.AppendChild(new Run(drawing));
+    }
+
+    // ── 8. Replace Existing Image ──────────────────────────────────────
+
+    /// <summary>
+    /// Replaces an existing image by updating the ImagePart data behind a
+    /// known relationship ID. The Blip.Embed attribute (rId) stays the same;
+    /// only the binary content changes. This avoids needing to rebuild the
+    /// entire Drawing XML tree.
+    /// </summary>
+    /// <param name="mainPart">The MainDocumentPart containing the image relationship.</param>
+    /// <param name="oldRelId">The existing relationship ID (e.g., "rId5") of the image to replace.</param>
+    /// <param name="newImagePath">Path to the replacement image file.</param>
+    public static void ReplaceExistingImage(
+        MainDocumentPart mainPart, string oldRelId, string newImagePath)
+    {
+        // Look up the existing ImagePart by its relationship ID
+        OpenXmlPart part = mainPart.GetPartById(oldRelId);
+        if (part is not ImagePart imagePart)
+        {
+            throw new InvalidOperationException(
+                $"Relationship {oldRelId} does not point to an ImagePart.");
+        }
+
+        // Feed new image data into the existing part.
+        // This replaces the binary content while keeping the same rId.
+        using (FileStream stream = new FileStream(newImagePath, FileMode.Open))
+        {
+            imagePart.FeedData(stream);
+        }
+
+        // NOTE: If the new image has different dimensions, you should also
+        // update the Extent.Cx/Cy and A.Extents.Cx/Cy in the Drawing element.
+        // Find all Blip elements referencing this relId:
+        //
+        //   var blips = mainPart.Document.Descendants<A.Blip>()
+        //       .Where(b => b.Embed == oldRelId);
+        //   foreach (var blip in blips)
+        //   {
+        //       // Navigate up to find the Extent and A.Extents to update dimensions
+        //   }
+    }
+
+    // ── 9. SVG with PNG Fallback ───────────────────────────────────────
+
+    /// <summary>
+    /// Inserts an SVG image with a PNG fallback for compatibility.
+    /// Word 2019+ supports SVG natively; older versions show the PNG.
+    /// The SVG is referenced via an extension element (SvgBlip) inside the Blip,
+    /// while the Blip.Embed itself points to the PNG fallback.
+    /// </summary>
+    public static void InsertSvgWithPngFallback(
+        MainDocumentPart mainPart, Body body,
+        string svgPath, string pngFallbackPath)
+    {
+        // Add PNG fallback as the primary image part
+        ImagePart pngPart = mainPart.AddImagePart(ImagePartType.Png);
+        using (FileStream pngStream = new FileStream(pngFallbackPath, FileMode.Open))
+        {
+            pngPart.FeedData(pngStream);
+        }
+        string pngRelId = mainPart.GetIdOfPart(pngPart);
+
+        // Add SVG as a separate image part
+        ImagePart svgPart = mainPart.AddImagePart(ImagePartType.Svg);
+        using (FileStream svgStream = new FileStream(svgPath, FileMode.Open))
+        {
+            svgPart.FeedData(svgStream);
+        }
+        string svgRelId = mainPart.GetIdOfPart(svgPart);
+
+        long cx = (long)(3.0 * EmuPerInch);
+        long cy = (long)(3.0 * EmuPerInch);
+
+        // The Blip.Embed points to the PNG fallback.
+        // The SVG is added as an extension element (asvg:svgBlip) inside the Blip.
+        // Namespace: http://schemas.microsoft.com/office/drawing/2016/SVG/main
+        var blip = new A.Blip { Embed = pngRelId };
+
+        // Add SVG extension to the Blip using BlipExtensionList
+        var svgExtension = new A.BlipExtensionList(
+            new A.BlipExtension(
+                // The SVG blip element references the SVG image part
+                new OpenXmlUnknownElement(
+                    "asvg", "svgBlip",
+                    "http://schemas.microsoft.com/office/drawing/2016/SVG/main")
+                // NOTE: In production, set the r:embed attribute on this element
+                // to svgRelId. OpenXmlUnknownElement requires manual attribute setting.
+            )
+            { Uri = "{96DAC541-7B7A-43D3-8B79-37D633B846F1}" }
+        );
+        blip.Append(svgExtension);
+
+        var picture = new PIC.Picture(
+            new PIC.NonVisualPictureProperties(
+                new PIC.NonVisualDrawingProperties { Id = 0U, Name = "SvgImage.svg" },
+                new PIC.NonVisualPictureDrawingProperties()),
+            new PIC.BlipFill(
+                blip,
+                new A.Stretch(new A.FillRectangle())),
+            new PIC.ShapeProperties(
+                new A.Transform2D(
+                    new A.Offset { X = 0L, Y = 0L },
+                    new A.Extents { Cx = cx, Cy = cy }),
+                new A.PresetGeometry(new A.AdjustValueList())
+                { Preset = A.ShapeTypeValues.Rectangle }));
+
+        var drawing = new Drawing(
+            new DW.Inline(
+                new DW.Extent { Cx = cx, Cy = cy },
+                new DW.EffectExtent
+                {
+                    LeftEdge = 0L, TopEdge = 0L,
+                    RightEdge = 0L, BottomEdge = 0L
+                },
+                new DW.DocProperties { Id = 9U, Name = "SvgImage" },
+                new DW.NonVisualGraphicFrameDrawingProperties(
+                    new A.GraphicFrameLocks { NoChangeAspect = true }),
+                new A.Graphic(
+                    new A.GraphicData(picture)
+                    { Uri = PicGraphicDataUri })
+            )
+            {
+                DistanceFromTop = 0U,
+                DistanceFromBottom = 0U,
+                DistanceFromLeft = 0U,
+                DistanceFromRight = 0U
+            });
+
+        body.AppendChild(new Paragraph(new Run(drawing)));
+    }
+
+    // ── 10. Calculate Image Dimensions ─────────────────────────────────
+
+    /// <summary>
+    /// Reads the actual pixel dimensions of an image file (PNG or JPEG) and
+    /// calculates EMU values that fit within a maximum width while maintaining
+    /// the original aspect ratio. Uses raw byte reading to avoid a dependency
+    /// on System.Drawing (which is Windows-only on modern .NET).
+    /// </summary>
+    /// <param name="imagePath">Path to a PNG or JPEG image file.</param>
+    /// <param name="maxWidthInches">Maximum allowed width in inches.</param>
+    /// <returns>Tuple of (cx, cy) in EMU, scaled to fit maxWidthInches.</returns>
+    /// <remarks>
+    /// For production use, consider SkiaSharp or SixLabors.ImageSharp for
+    /// cross-platform image metadata reading with broader format support.
+    /// This implementation handles PNG and JPEG only.
+    /// </remarks>
+    public static (long cx, long cy) CalculateImageDimensions(
+        string imagePath, double maxWidthInches)
+    {
+        // Read pixel dimensions from the image file header.
+        // We parse PNG IHDR or JPEG SOF0 markers directly to avoid
+        // pulling in System.Drawing.Common (Windows-only on .NET 6+).
+        (int widthPx, int heightPx, double dpiX, double dpiY) = ReadImageMetadata(imagePath);
+
+        // Calculate actual size in inches based on pixel count and DPI
+        double widthInches = widthPx / dpiX;
+        double heightInches = heightPx / dpiY;
+
+        // Scale down if wider than maxWidthInches, preserving aspect ratio
+        if (widthInches > maxWidthInches)
+        {
+            double scale = maxWidthInches / widthInches;
+            widthInches = maxWidthInches;
+            heightInches *= scale;
+        }
+
+        long cx = (long)(widthInches * EmuPerInch);
+        long cy = (long)(heightInches * EmuPerInch);
+
+        return (cx, cy);
+    }
+
+    /// <summary>
+    /// Reads width, height, and DPI from a PNG or JPEG file header.
+    /// Returns 96 DPI as default if DPI metadata is not found.
+    /// </summary>
+    private static (int widthPx, int heightPx, double dpiX, double dpiY) ReadImageMetadata(
+        string imagePath)
+    {
+        const double DefaultDpi = 96.0;
+        byte[] header = new byte[32];
+
+        using var fs = new FileStream(imagePath, FileMode.Open, FileAccess.Read);
+        int bytesRead = fs.Read(header, 0, header.Length);
+
+        // PNG: starts with 0x89 0x50 0x4E 0x47 (‰PNG)
+        // IHDR chunk is always first; width and height are at bytes 16-23 (big-endian)
+        if (bytesRead >= 24 &&
+            header[0] == 0x89 && header[1] == 0x50 &&
+            header[2] == 0x4E && header[3] == 0x47)
+        {
+            int width = (header[16] << 24) | (header[17] << 16) |
+                        (header[18] << 8) | header[19];
+            int height = (header[20] << 24) | (header[21] << 16) |
+                         (header[22] << 8) | header[23];
+            // PNG DPI is in the pHYs chunk (not in IHDR); use default for simplicity
+            return (width, height, DefaultDpi, DefaultDpi);
+        }
+
+        // JPEG: starts with 0xFF 0xD8
+        // Scan for SOF0 (0xFF 0xC0) marker to find dimensions
+        if (bytesRead >= 2 && header[0] == 0xFF && header[1] == 0xD8)
+        {
+            fs.Position = 2;
+            while (fs.Position < fs.Length - 1)
+            {
+                int b = fs.ReadByte();
+                if (b != 0xFF) continue;
+
+                int marker = fs.ReadByte();
+                if (marker == -1) break;
+
+                // SOF0 (0xC0) or SOF2 (0xC2, progressive)
+                if (marker == 0xC0 || marker == 0xC2)
+                {
+                    byte[] sof = new byte[7];
+                    if (fs.Read(sof, 0, 7) == 7)
+                    {
+                        // SOF structure: length(2) + precision(1) + height(2) + width(2)
+                        int height = (sof[3] << 8) | sof[4];
+                        int width = (sof[5] << 8) | sof[6];
+                        return (width, height, DefaultDpi, DefaultDpi);
+                    }
+                    break;
+                }
+
+                // Skip other markers: read 2-byte length and advance
+                if (marker is not (0xD0 or 0xD1 or 0xD2 or 0xD3 or 0xD4 or
+                    0xD5 or 0xD6 or 0xD7 or 0xD8 or 0xD9 or 0x01))
+                {
+                    byte[] lenBytes = new byte[2];
+                    if (fs.Read(lenBytes, 0, 2) < 2) break;
+                    int len = (lenBytes[0] << 8) | lenBytes[1];
+                    if (len < 2) break;
+                    fs.Position += len - 2;
+                }
+            }
+        }
+
+        // Fallback: cannot determine dimensions; return a reasonable default
+        // Caller should handle this gracefully.
+        return (300, 200, DefaultDpi, DefaultDpi);
+    }
+
+    // ── 11. Reusable Drawing Builder (Inline) ──────────────────────────
+
+    /// <summary>
+    /// Builds a complete Drawing element for an inline image. This is the
+    /// reusable core that most insertion methods delegate to.
+    /// </summary>
+    /// <param name="relId">Relationship ID pointing to the ImagePart (e.g., "rId4").</param>
+    /// <param name="cx">Image width in EMU. Must be positive.</param>
+    /// <param name="cy">Image height in EMU. Must be positive.</param>
+    /// <param name="docPropId">Unique ID for DocProperties within the document.
+    /// Each Drawing in a document must have a distinct DocProperties.Id.</param>
+    /// <param name="name">Name for DocProperties (shows in Word selection pane).</param>
+    /// <param name="description">Alt text for accessibility. Null if not needed.</param>
+    /// <returns>A fully constructed Drawing element ready to append to a Run.</returns>
+    public static Drawing BuildDrawingElement(
+        string relId, long cx, long cy,
+        uint docPropId, string name, string? description)
+    {
+        // ── Complete element hierarchy ──
+        // Drawing
+        //   └─ DW.Inline
+        //        ├─ DW.Extent (cx, cy)              ← bounding box size
+        //        ├─ DW.EffectExtent                  ← extra space for effects
+        //        ├─ DW.DocProperties (id, name, descr) ← identity + alt text
+        //        ├─ DW.NonVisualGraphicFrameDrawingProperties
+        //        │    └─ A.GraphicFrameLocks          ← lock aspect ratio
+        //        └─ A.Graphic
+        //             └─ A.GraphicData (uri = picture namespace)
+        //                  └─ PIC.Picture
+        //                       ├─ PIC.NonVisualPictureProperties
+        //                       │    ├─ PIC.NonVisualDrawingProperties
+        //                       │    └─ PIC.NonVisualPictureDrawingProperties
+        //                       ├─ PIC.BlipFill
+        //                       │    ├─ A.Blip (embed = relId)
+        //                       │    └─ A.Stretch → A.FillRectangle
+        //                       └─ PIC.ShapeProperties
+        //                            ├─ A.Transform2D
+        //                            │    ├─ A.Offset (0, 0)
+        //                            │    └─ A.Extents (cx, cy)  ← MUST match DW.Extent!
+        //                            └─ A.PresetGeometry (rect)
+
+        var docProps = new DW.DocProperties
+        {
+            Id = docPropId,
+            Name = name
+        };
+        if (description is not null)
+        {
+            docProps.Description = description;
+        }
+
+        var picture = new PIC.Picture(
+            new PIC.NonVisualPictureProperties(
+                new PIC.NonVisualDrawingProperties
+                {
+                    Id = 0U,
+                    Name = name
+                },
+                new PIC.NonVisualPictureDrawingProperties()),
+            new PIC.BlipFill(
+                new A.Blip
+                {
+                    Embed = relId,
+                    // CompressionState controls image quality vs file size.
+                    // Print = high quality, Screen = medium, Email = low, None = original
+                    CompressionState = A.BlipCompressionValues.Print
+                },
+                new A.Stretch(new A.FillRectangle())),
+            new PIC.ShapeProperties(
+                new A.Transform2D(
+                    new A.Offset { X = 0L, Y = 0L },
+                    new A.Extents { Cx = cx, Cy = cy }), // MUST match DW.Extent
+                new A.PresetGeometry(
+                    new A.AdjustValueList())
+                { Preset = A.ShapeTypeValues.Rectangle }));
+
+        var inline = new DW.Inline(
+            new DW.Extent { Cx = cx, Cy = cy }, // MUST match A.Extents
+            new DW.EffectExtent
+            {
+                LeftEdge = 0L,
+                TopEdge = 0L,
+                RightEdge = 0L,
+                BottomEdge = 0L
+            },
+            docProps,
+            new DW.NonVisualGraphicFrameDrawingProperties(
+                new A.GraphicFrameLocks { NoChangeAspect = true }),
+            new A.Graphic(
+                new A.GraphicData(picture)
+                { Uri = PicGraphicDataUri }))
+        {
+            DistanceFromTop = 0U,
+            DistanceFromBottom = 0U,
+            DistanceFromLeft = 0U,
+            DistanceFromRight = 0U
+        };
+
+        return new Drawing(inline);
+    }
+
+    // ── Private Helpers ────────────────────────────────────────────────
+
+    /// <summary>
+    /// Builds a DW.Anchor element for floating images with configurable wrapping.
+    /// </summary>
+    private static DW.Anchor BuildAnchorElement(
+        string relId, long cx, long cy,
+        uint docPropId, string name,
+        OpenXmlElement wrapElement,
+        bool behindDoc)
+    {
+        return new DW.Anchor(
+            new DW.SimplePosition { X = 0L, Y = 0L },
+            new DW.HorizontalPosition(
+                new DW.PositionOffset("0"))
+            { RelativeFrom = DW.HorizontalRelativePositionValues.Column },
+            new DW.VerticalPosition(
+                new DW.PositionOffset("0"))
+            { RelativeFrom = DW.VerticalRelativePositionValues.Paragraph },
+            new DW.Extent { Cx = cx, Cy = cy },
+            new DW.EffectExtent
+            {
+                LeftEdge = 0L,
+                TopEdge = 0L,
+                RightEdge = 0L,
+                BottomEdge = 0L
+            },
+            wrapElement,
+            new DW.DocProperties { Id = docPropId, Name = name },
+            new DW.NonVisualGraphicFrameDrawingProperties(
+                new A.GraphicFrameLocks { NoChangeAspect = true }),
+            new A.Graphic(
+                new A.GraphicData(
+                    new PIC.Picture(
+                        new PIC.NonVisualPictureProperties(
+                            new PIC.NonVisualDrawingProperties
+                            {
+                                Id = 0U,
+                                Name = name
+                            },
+                            new PIC.NonVisualPictureDrawingProperties()),
+                        new PIC.BlipFill(
+                            new A.Blip { Embed = relId },
+                            new A.Stretch(new A.FillRectangle())),
+                        new PIC.ShapeProperties(
+                            new A.Transform2D(
+                                new A.Offset { X = 0L, Y = 0L },
+                                new A.Extents { Cx = cx, Cy = cy }),
+                            new A.PresetGeometry(
+                                new A.AdjustValueList())
+                            { Preset = A.ShapeTypeValues.Rectangle }))
+                )
+                { Uri = PicGraphicDataUri })
+        )
+        {
+            DistanceFromTop = 0U,
+            DistanceFromBottom = 0U,
+            DistanceFromLeft = 114300U,
+            DistanceFromRight = 114300U,
+            SimplePos = false,
+            RelativeHeight = 251658240U,
+            BehindDoc = behindDoc,
+            Locked = false,
+            LayoutInCell = true,
+            AllowOverlap = true
+        };
+    }
+
+    /// <summary>
+    /// Maps file extensions to OpenXML PartTypeInfo values via ImagePartType.
+    /// In SDK 3.x, ImagePartType is a static class whose members return PartTypeInfo.
+    /// </summary>
+    private static PartTypeInfo GetImagePartType(string imagePath)
+    {
+        string ext = Path.GetExtension(imagePath).ToLowerInvariant();
+        return ext switch
+        {
+            ".png" => ImagePartType.Png,
+            ".jpg" or ".jpeg" => ImagePartType.Jpeg,
+            ".gif" => ImagePartType.Gif,
+            ".bmp" => ImagePartType.Bmp,
+            ".tif" or ".tiff" => ImagePartType.Tiff,
+            ".svg" => ImagePartType.Svg,
+            ".emf" => ImagePartType.Emf,
+            ".wmf" => ImagePartType.Wmf,
+            ".ico" => ImagePartType.Icon,
+            _ => throw new NotSupportedException(
+                $"Image format '{ext}' is not supported by OpenXML.")
+        };
+    }
+}