docxmlater 10.1.4 → 10.1.6

package/src/elements/Image.ts

@@ -1,1756 +1,1982 @@
-/**
- * Image - Represents an embedded image in a Word document
- *
- * Images use DrawingML (a:) and WordprocessingML Drawing (wp:) namespaces
- * for proper positioning and formatting in Word documents.
- */
-
-import { promises as fs } from 'fs';
-import { defaultLogger } from '../utils/logger';
-import { inchesToEmus, UNITS } from '../utils/units';
-import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
-
-/**
- * Supported image formats
- */
-export type ImageFormat = 'png' | 'jpeg' | 'jpg' | 'gif' | 'bmp' | 'tiff' | 'svg' | 'emf' | 'wmf';
-
-/**
- * Preset geometry shape type (ECMA-376 §20.1.9.18)
- */
-export type PresetGeometry = 'rect' | 'roundRect' | 'ellipse' | string;
-
-/**
- * Blip compression state (ECMA-376 §20.1.8.15)
- */
-export type BlipCompressionState = 'none' | 'print' | 'email' | 'hqprint' | 'screen';
-
-/**
- * Picture lock attribute names (ECMA-376 §20.1.2.2.31)
- */
-export type PicLockAttribute = 'noChangeAspect' | 'noChangeArrowheads' | 'noSelect' | 'noMove'
-  | 'noResize' | 'noEditPoints' | 'noAdjustHandles' | 'noRot' | 'noChangeShapeType'
-  | 'noCrop' | 'noGrp';
-
-/**
- * Non-visual picture properties (ECMA-376 §19.3.1.12)
- */
-export interface PicNonVisualProperties {
-  id: string;
-  name: string;
-  descr: string;
-}
-
-/**
- * Image border definition (full a:ln support per ECMA-376)
- */
-export interface ImageBorder {
-  /** Border width in points */
-  width: number;
-  /** Line cap style */
-  cap?: 'flat' | 'rnd' | 'sq';
-  /** Compound line type */
-  compound?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
-  /** Alignment relative to shape */
-  alignment?: 'ctr' | 'in';
-  /** Fill specification */
-  fill?: {
-    type: 'srgbClr' | 'schemeClr';
-    value: string;
-    modifiers?: { name: string; val: string }[];
-  };
-  /** Raw XML for non-solid fills (gradFill, pattFill, etc.) */
-  rawFillXml?: string;
-  /** Preset dash pattern */
-  dashPattern?: string;
-  /** Line join style */
-  join?: 'round' | 'bevel' | 'miter';
-  /** Miter limit (percentage * 1000) */
-  miterLimit?: number;
-  /** Head end decoration */
-  headEnd?: { type?: string; width?: string; length?: string };
-  /** Tail end decoration */
-  tailEnd?: { type?: string; width?: string; length?: string };
-}
-
-/**
- * Image extent (dimensions)
- */
-export interface ImageExtent {
-  /** Width in EMUs */
-  width: number;
-  /** Height in EMUs */
-  height: number;
-}
-
-/**
- * Effect extent (additional space for shadows, reflections, glows)
- * Specifies additional space to add to each edge to prevent clipping of effects
- */
-export interface EffectExtent {
-  /** Left extent in EMUs */
-  left: number;
-  /** Top extent in EMUs */
-  top: number;
-  /** Right extent in EMUs */
-  right: number;
-  /** Bottom extent in EMUs */
-  bottom: number;
-}
-
-/**
- * Text wrapping type
- */
-export type WrapType = 'square' | 'tight' | 'through' | 'topAndBottom' | 'none';
-
-/**
- * Text wrapping side
- */
-export type WrapSide = 'bothSides' | 'left' | 'right' | 'largest';
-
-/**
- * Text wrap settings
- */
-export interface TextWrapSettings {
-  /** Wrap type */
-  type: WrapType;
-  /** Which side(s) to wrap text */
-  side?: WrapSide;
-  /** Distance from top in EMUs */
-  distanceTop?: number;
-  /** Distance from bottom in EMUs */
-  distanceBottom?: number;
-  /** Distance from left in EMUs */
-  distanceLeft?: number;
-  /** Distance from right in EMUs */
-  distanceRight?: number;
-}
-
-/**
- * Position anchor type (what to position relative to)
- */
-export type PositionAnchor = 'page' | 'margin' | 'column' | 'character' | 'paragraph';
-
-/**
- * Horizontal alignment options
- */
-export type HorizontalAlignment = 'left' | 'center' | 'right' | 'inside' | 'outside';
-
-/**
- * Vertical alignment options
- */
-export type VerticalAlignment = 'top' | 'center' | 'bottom' | 'inside' | 'outside';
-
-/**
- * Image position configuration
- */
-export interface ImagePosition {
-  /** Horizontal positioning */
-  horizontal: {
-    /** Anchor point */
-    anchor: PositionAnchor;
-    /** Offset in EMUs (absolute positioning) */
-    offset?: number;
-    /** Alignment (relative positioning) */
-    alignment?: HorizontalAlignment;
-  };
-  /** Vertical positioning */
-  vertical: {
-    /** Anchor point */
-    anchor: PositionAnchor;
-    /** Offset in EMUs (absolute positioning) */
-    offset?: number;
-    /** Alignment (relative positioning) */
-    alignment?: VerticalAlignment;
-  };
-}
-
-/**
- * Image anchor configuration (floating images)
- */
-export interface ImageAnchor {
-  /** Position behind text */
-  behindDoc: boolean;
-  /** Lock anchor (prevent movement) */
-  locked: boolean;
-  /** Layout in table cell */
-  layoutInCell: boolean;
-  /** Allow overlap with other objects */
-  allowOverlap: boolean;
-  /** Z-order (higher = in front) */
-  relativeHeight: number;
-  /** Use simple positioning (wp:simplePos coordinates) */
-  simplePos?: boolean;
-  /** Distance from text - top (EMUs) */
-  distT?: number;
-  /** Distance from text - bottom (EMUs) */
-  distB?: number;
-  /** Distance from text - left (EMUs) */
-  distL?: number;
-  /** Distance from text - right (EMUs) */
-  distR?: number;
-}
-
-/**
- * Image crop settings (percentage-based)
- */
-export interface ImageCrop {
-  /** Left crop percentage (0-100) */
-  left: number;
-  /** Top crop percentage (0-100) */
-  top: number;
-  /** Right crop percentage (0-100) */
-  right: number;
-  /** Bottom crop percentage (0-100) */
-  bottom: number;
-}
-
-/**
- * Image visual effects
- */
-export interface ImageEffects {
-  /** Brightness adjustment (-100 to +100) */
-  brightness?: number;
-  /** Contrast adjustment (-100 to +100) */
-  contrast?: number;
-  /** Convert to grayscale */
-  grayscale?: boolean;
-  /** Transparency (0-100, percentage) via a:alphaModFix */
-  transparency?: number;
-}
-
-/**
- * Image properties
- */
-export interface ImageProperties {
-  /** Image source (file path or buffer) */
-  source: string | Buffer;
-  /** Image width in EMUs (optional - will auto-detect) */
-  width?: number;
-  /** Image height in EMUs (optional - will auto-detect) */
-  height?: number;
-  /** Maintain aspect ratio when resizing */
-  maintainAspectRatio?: boolean;
-  /** Alt text / description */
-  description?: string;
-  /** Image name/title */
-  name?: string;
-  /** Image title (wp:docPr title attribute for accessibility) */
-  title?: string;
-  /** Relationship ID (will be set by ImageManager) */
-  relationshipId?: string;
-  /** Effect extent (space for shadows/glows) */
-  effectExtent?: EffectExtent;
-  /** Text wrapping configuration */
-  wrap?: TextWrapSettings;
-  /** Position configuration (floating images) */
-  position?: ImagePosition;
-  /** Anchor configuration (floating images) */
-  anchor?: ImageAnchor;
-  /** Crop settings */
-  crop?: ImageCrop;
-  /** Visual effects */
-  effects?: ImageEffects;
-  /** Border settings */
-  border?: ImageBorder | { width: number };
-  /** Rotation angle in degrees (0-360) */
-  rotation?: number;
-  /** Horizontal flip (ECMA-376 §20.1.7.6) */
-  flipH?: boolean;
-  /** Vertical flip (ECMA-376 §20.1.7.6) */
-  flipV?: boolean;
-  /** Preset geometry shape (ECMA-376 §20.1.9.18) */
-  presetGeometry?: PresetGeometry;
-  /** Blip compression state (ECMA-376 §20.1.8.15) */
-  compressionState?: BlipCompressionState;
-  /** Black-and-white mode (ECMA-376 §20.1.2.2.35) */
-  bwMode?: string;
-  /** Inline distance from text - top (EMUs, ECMA-376 §20.4.2.8) */
-  inlineDistT?: number;
-  /** Inline distance from text - bottom (EMUs) */
-  inlineDistB?: number;
-  /** Inline distance from text - left (EMUs) */
-  inlineDistL?: number;
-  /** Inline distance from text - right (EMUs) */
-  inlineDistR?: number;
-  /** Whether aspect ratio lock is enabled (ECMA-376 §20.4.2.4) */
-  noChangeAspect?: boolean;
-  /** Hidden attribute on docPr (ECMA-376 §20.4.2.3) */
-  hidden?: boolean;
-  /** BlipFill DPI override (ECMA-376 §20.1.8.14) */
-  blipFillDpi?: number;
-  /** BlipFill rotate with shape flag (ECMA-376 §20.1.8.14) */
-  blipFillRotWithShape?: boolean;
-  /** Picture locks (ECMA-376 §20.1.2.2.31) */
-  picLocks?: Partial<Record<PicLockAttribute, boolean>>;
-  /** Non-visual picture properties (ECMA-376 §19.3.1.12) */
-  picNonVisualProps?: PicNonVisualProperties;
-  /** Whether image is linked (r:link) vs embedded (r:embed) */
-  isLinked?: boolean;
-  /** SVG relationship ID for Word 365 dual-relationship approach */
-  svgRelationshipId?: string;
-}
-
-/**
- * Image validation result
- */
-export interface ValidationResult {
-  valid: boolean;
-  error?: string;
-}
-
-export class Image {
-  private source: string | Buffer;
-  private width: number;
-  private height: number;
-  private description: string;
-  private name: string;
-  private title?: string;
-  private relationshipId?: string;
-  private imageData?: Buffer;
-  private extension: string;
-  private docPrId = 1;
-  private dpi = 96;  // Default DPI
-
-  // Advanced image properties
-  private effectExtent?: EffectExtent;
-  private wrap?: TextWrapSettings;
-  private position?: ImagePosition;
-  private anchor?: ImageAnchor;
-  private crop?: ImageCrop;
-  private effects?: ImageEffects;
-  private rotation = 0;
-  private flipH = false;
-  private flipV = false;
-  private border?: ImageBorder;
-
-  // Group A: Simple attribute preservation (ECMA-376 compliance)
-  private presetGeometry: PresetGeometry = 'rect';
-  private compressionState: BlipCompressionState = 'none';
-  private bwMode = 'auto';
-  private inlineDistT = 0;
-  private inlineDistB = 0;
-  private inlineDistL = 0;
-  private inlineDistR = 0;
-  private noChangeAspect = true;
-  private hidden = false;
-  private blipFillDpi?: number;
-  private blipFillRotWithShape?: boolean;
-  private picLocks: Partial<Record<PicLockAttribute, boolean>> = {
-    noChangeAspect: true,
-    noChangeArrowheads: true,
-  };
-  private picNonVisualProps: PicNonVisualProperties = { id: '0', name: '', descr: '' };
-  private isLinked = false;
-  private svgRelationshipId?: string;
-
-  // Group B: Raw XML passthrough for complex subtrees
-  private _rawPassthrough = new Map<string, string>();
-
-  /**
-   * Creates a new image from file path (async factory)
-   * @param path File path
-   * @param properties Additional properties
-   * @returns Promise<Image>
-   */
-  static async fromFile(path: string, properties: Partial<ImageProperties> = {}): Promise<Image> {
-    const image = new Image({ source: path, ...properties });
-    await image.loadImageDataForDimensions();
-    return image;
-  }
-
-  /**
-   * Creates a new image from buffer (async factory)
-   * Supports both modern and legacy API signatures
-   *
-   * @param buffer Image buffer
-   * @param mimeTypeOrProperties MIME type string ('png', 'jpeg', etc.) or properties object
-   * @param width Optional width in EMUs (legacy API)
-   * @param height Optional height in EMUs (legacy API)
-   * @returns Promise<Image>
-   *
-   * @example
-   * // Modern API (recommended)
-   * const img = await Image.fromBuffer(buffer, { mimeType: 'png', width: 914400, height: 914400 });
-   *
-   * // Legacy API (still supported)
-   * const img = await Image.fromBuffer(buffer, 'png', 914400, 914400);
-   */
-  static async fromBuffer(
-    buffer: Buffer,
-    mimeTypeOrProperties?: string | Partial<ImageProperties>,
-    width?: number,
-    height?: number
-  ): Promise<Image> {
-    let properties: Partial<ImageProperties>;
-
-    // Detect API signature
-    if (typeof mimeTypeOrProperties === 'string') {
-      // Legacy 4-parameter signature: fromBuffer(buffer, 'png', 914400, 914400)
-      // Note: mimeType is ignored - extension is auto-detected from buffer
-      properties = {
-        width: width,
-        height: height
-      };
-    } else {
-      // Modern API: fromBuffer(buffer, { width: 914400, height: 914400 })
-      properties = mimeTypeOrProperties || {};
-    }
-
-    const image = new Image({ source: buffer, ...properties });
-    await image.loadImageDataForDimensions();
-    return image;
-  }
-
-  /**
-   * Unified create method for images (async factory)
-   * @param properties Image properties including source (path or buffer)
-   * @returns Promise<Image>
-   */
-  static async create(properties: ImageProperties): Promise<Image> {
-    if (Buffer.isBuffer(properties.source)) {
-      return Image.fromBuffer(properties.source, properties);
-    } else if (typeof properties.source === 'string') {
-      return Image.fromFile(properties.source, properties);
-    } else {
-      throw new Error('Invalid source: must be file path or Buffer');
-    }
-  }
-
-  /**
-   * Private constructor
-   * @param properties Image properties
-   */
-  private constructor(properties: ImageProperties) {
-    this.source = properties.source;
-    this.description = properties.description || 'Image';
-    this.name = properties.name || 'image';
-    this.title = properties.title;
-    this.relationshipId = properties.relationshipId;
-
-    // Detect image extension
-    this.extension = this.detectExtension();
-
-    // Set default dimensions (6 inches x 4 inches) if not provided
-    this.width = properties.width || inchesToEmus(6);
-    this.height = properties.height || inchesToEmus(4);
-
-    // Initialize advanced properties
-    this.effectExtent = properties.effectExtent;
-    this.wrap = properties.wrap;
-    this.position = properties.position;
-    this.anchor = properties.anchor;
-    this.crop = properties.crop;
-    this.effects = properties.effects;
-    // Border: accept both legacy { width } and full ImageBorder
-    if (properties.border) {
-      this.border = properties.border as ImageBorder;
-    }
-    // Apply rotation if provided (normalize to 0-360)
-    if (properties.rotation !== undefined && properties.rotation !== 0) {
-      this.rotation = ((properties.rotation % 360) + 360) % 360;
-    }
-    // Apply flip attributes (ECMA-376 §20.1.7.6)
-    this.flipH = properties.flipH || false;
-    this.flipV = properties.flipV || false;
-
-    // Group A: Simple attribute preservation
-    if (properties.presetGeometry !== undefined) this.presetGeometry = properties.presetGeometry;
-    if (properties.compressionState !== undefined) this.compressionState = properties.compressionState;
-    if (properties.bwMode !== undefined) this.bwMode = properties.bwMode;
-    if (properties.inlineDistT !== undefined) this.inlineDistT = properties.inlineDistT;
-    if (properties.inlineDistB !== undefined) this.inlineDistB = properties.inlineDistB;
-    if (properties.inlineDistL !== undefined) this.inlineDistL = properties.inlineDistL;
-    if (properties.inlineDistR !== undefined) this.inlineDistR = properties.inlineDistR;
-    if (properties.noChangeAspect !== undefined) this.noChangeAspect = properties.noChangeAspect;
-    if (properties.hidden !== undefined) this.hidden = properties.hidden;
-    if (properties.blipFillDpi !== undefined) this.blipFillDpi = properties.blipFillDpi;
-    if (properties.blipFillRotWithShape !== undefined) this.blipFillRotWithShape = properties.blipFillRotWithShape;
-    if (properties.picLocks !== undefined) this.picLocks = properties.picLocks;
-    if (properties.picNonVisualProps !== undefined) this.picNonVisualProps = properties.picNonVisualProps;
-    if (properties.isLinked !== undefined) this.isLinked = properties.isLinked;
-    if (properties.svgRelationshipId !== undefined) this.svgRelationshipId = properties.svgRelationshipId;
-
-    // Set default DPI
-    this.dpi = 96;
-  }
-
-  /**
-   * Loads image data temporarily for dimension detection only
-   * Data is released after detection to save memory
-   * @private
-   */
-  private async loadImageDataForDimensions(): Promise<void> {
-    let tempData: Buffer | undefined;
-
-    try {
-      if (Buffer.isBuffer(this.source)) {
-        tempData = this.source;
-      } else if (typeof this.source === 'string') {
-        await fs.access(this.source);
-        tempData = await fs.readFile(this.source);
-      }
-
-      if (tempData) {
-        this.imageData = tempData; // Temporarily store
-
-        // Only auto-detect dimensions if they weren't explicitly provided
-        // This preserves wp:extent values from parsed documents
-        const defaultWidth = inchesToEmus(6);
-        const defaultHeight = inchesToEmus(4);
-        const hasExplicitDimensions = this.width !== defaultWidth || this.height !== defaultHeight;
-
-        if (!hasExplicitDimensions) {
-          const dimensions = this.detectDimensions();
-          if (dimensions) {
-            this.dpi = this.detectDPI() || 96;
-            const emuPerInch = 914400;
-            const pixelsPerInch = this.dpi;
-            this.width = Math.round((dimensions.width / pixelsPerInch) * emuPerInch);
-            this.height = Math.round((dimensions.height / pixelsPerInch) * emuPerInch);
-          }
-        }
-
-        if (typeof this.source === 'string') {
-          this.imageData = undefined; // Release
-        }
-      }
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
-      defaultLogger.error(`Failed to load image for dimensions: ${message}`);
-      throw new Error(`Image loading failed: ${message}`);
-    }
-  }
-
-  /**
-   * Ensures image data is loaded (lazy loading)
-   */
-  async ensureDataLoaded(): Promise<void> {
-    if (this.imageData) return;
-
-    try {
-      if (Buffer.isBuffer(this.source)) {
-        this.imageData = this.source;
-      } else if (typeof this.source === 'string') {
-        await fs.access(this.source);
-        this.imageData = await fs.readFile(this.source);
-      } else {
-        throw new Error('Invalid image source');
-      }
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
-      defaultLogger.error(`Failed to load image data: ${message}`);
-      throw new Error(`Image data loading failed: ${message}`);
-    }
-  }
-
-  /**
-   * Releases image data from memory
-   */
-  releaseData(): void {
-    if (typeof this.source === 'string') {
-      this.imageData = undefined;
-    }
-  }
-
-  /**
-   * Validates the image data integrity
-   */
-  validateImageData(): ValidationResult {
-    // Skip validation for linked images (no data in package)
-    if (this.isLinked) {
-      return { valid: true };
-    }
-
-    if (!this.imageData || this.imageData.length === 0) {
-      return { valid: false, error: 'Empty image data' };
-    }
-
-    // Skip signature validation for text-based formats (SVG)
-    if (this.extension === 'svg') {
-      return { valid: true };
-    }
-
-    const signatures: Record<string, number[]> = {
-      png: [0x89, 0x50, 0x4E, 0x47],
-      jpg: [0xFF, 0xD8],
-      jpeg: [0xFF, 0xD8],
-      gif: [0x47, 0x49, 0x46],
-      bmp: [0x42, 0x4D],
-      tiff: [0x49, 0x49, 0x2A, 0x00],
-      tif: [0x49, 0x49, 0x2A, 0x00]
-    };
-
-    // EMF: check for ENHMETAHEADER signature at offset 40
-    if (this.extension === 'emf') {
-      if (this.imageData.length >= 44 &&
-          this.imageData[40] === 0x20 && this.imageData[41] === 0x45 &&
-          this.imageData[42] === 0x4D && this.imageData[43] === 0x46) {
-        return { valid: true };
-      }
-      return { valid: false, error: 'Invalid EMF signature' };
-    }
-
-    // WMF: check for placeable or standard header
-    if (this.extension === 'wmf') {
-      if (this.imageData.length >= 4) {
-        // Placeable WMF
-        if (this.imageData[0] === 0xD7 && this.imageData[1] === 0xCD &&
-            this.imageData[2] === 0xC6 && this.imageData[3] === 0x9A) {
-          return { valid: true };
-        }
-        // Standard WMF
-        if (this.imageData[0] === 0x01 && this.imageData[1] === 0x00 &&
-            this.imageData[2] === 0x09 && this.imageData[3] === 0x00) {
-          return { valid: true };
-        }
-      }
-      return { valid: false, error: 'Invalid WMF signature' };
-    }
-
-    const sig = signatures[this.extension];
-    if (sig) {
-      for (let i = 0; i < sig.length; i++) {
-        if (this.imageData[i] !== sig[i]) {
-          return { valid: false, error: `Invalid ${this.extension.toUpperCase()} signature` };
-        }
-      }
-    }
-
-    return { valid: true };
-  }
-
-  /**
-   * Detects image extension from source (path or buffer)
-   */
-  private detectExtension(): string {
-    // Try path-based detection first
-    if (typeof this.source === 'string') {
-      const match = /\.([a-z]+)$/i.exec(this.source);
-      if (match?.[1]) {
-        return match[1].toLowerCase();
-      }
-    }
-
-    // Buffer-based detection using magic bytes
-    if (Buffer.isBuffer(this.source) && this.source.length >= 4) {
-      const buf = this.source;
-      // PNG
-      if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4E && buf[3] === 0x47) return 'png';
-      // JPEG
-      if (buf[0] === 0xFF && buf[1] === 0xD8) return 'jpeg';
-      // GIF
-      if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46) return 'gif';
-      // BMP
-      if (buf[0] === 0x42 && buf[1] === 0x4D) return 'bmp';
-      // TIFF LE
-      if (buf[0] === 0x49 && buf[1] === 0x49 && buf[2] === 0x2A && buf[3] === 0x00) return 'tiff';
-      // TIFF BE
-      if (buf[0] === 0x4D && buf[1] === 0x4D && buf[2] === 0x00 && buf[3] === 0x2A) return 'tiff';
-      // EMF: byte 0 = 0x01,0x00,0x00,0x00 AND ' EMF' at offset 40
-      if (buf.length >= 44 && buf[0] === 0x01 && buf[1] === 0x00 && buf[2] === 0x00 && buf[3] === 0x00 &&
-          buf[40] === 0x20 && buf[41] === 0x45 && buf[42] === 0x4D && buf[43] === 0x46) return 'emf';
-      // WMF placeable
-      if (buf[0] === 0xD7 && buf[1] === 0xCD && buf[2] === 0xC6 && buf[3] === 0x9A) return 'wmf';
-      // WMF standard
-      if (buf[0] === 0x01 && buf[1] === 0x00 && buf[2] === 0x09 && buf[3] === 0x00) return 'wmf';
-      // SVG: starts with '<' or UTF-8 BOM + '<'
-      if (buf[0] === 0x3C || (buf[0] === 0xEF && buf[1] === 0xBB && buf[2] === 0xBF && buf.length > 3 && buf[3] === 0x3C)) return 'svg';
-    }
-
-    return 'png';
-  }
-
-  /**
-   * Attempts to detect image dimensions from buffer
-   */
-  private detectDimensions(): { width: number; height: number } | null {
-    if (!this.imageData || this.imageData.length < 24) return null;
-
-    if (this.imageData[0] === 0x89 && this.imageData[1] === 0x50 && this.imageData[2] === 0x4e && this.imageData[3] === 0x47) {
-      return this.detectPngDimensions();
-    }
-    if (this.imageData[0] === 0xff && this.imageData[1] === 0xd8) {
-      return this.detectJpegDimensions();
-    }
-    if (this.imageData[0] === 0x47 && this.imageData[1] === 0x49 && this.imageData[2] === 0x46) {
-      return this.detectGifDimensions();
-    }
-    if (this.imageData[0] === 0x42 && this.imageData[1] === 0x4d) {
-      return this.detectBmpDimensions();
-    }
-    if ((this.imageData[0] === 0x49 && this.imageData[1] === 0x49 && this.imageData[2] === 0x2a) ||
-        (this.imageData[0] === 0x4d && this.imageData[1] === 0x4d && this.imageData[2] === 0x00)) {
-      return this.detectTiffDimensions();
-    }
-    // EMF: ENHMETAHEADER has ' EMF' at offset 40
-    if (this.imageData.length >= 44 &&
-        this.imageData[40] === 0x20 && this.imageData[41] === 0x45 &&
-        this.imageData[42] === 0x4D && this.imageData[43] === 0x46) {
-      return this.detectEmfDimensions();
-    }
-    // WMF placeable
-    if (this.imageData[0] === 0xD7 && this.imageData[1] === 0xCD &&
-        this.imageData[2] === 0xC6 && this.imageData[3] === 0x9A) {
-      return this.detectWmfDimensions();
-    }
-    // SVG (text-based)
-    if (this.imageData[0] === 0x3C ||
-        (this.imageData[0] === 0xEF && this.imageData[1] === 0xBB && this.imageData[2] === 0xBF)) {
-      return this.detectSvgDimensions();
-    }
-    return null;
-  }
-
-  // Dimension detection helpers (as before, keeping them the same)
-
-  private detectPngDimensions(): { width: number; height: number } | null {
-    if (!this.imageData || this.imageData.length < 24) return null;
-    const width = this.imageData.readUInt32BE(16);
-    const height = this.imageData.readUInt32BE(20);
-    return { width, height };
-  }
-
-  private detectGifDimensions(): { width: number; height: number } | null {
-    if (!this.imageData || this.imageData.length < 10) return null;
-    const width = this.imageData.readUInt16LE(6);
-    const height = this.imageData.readUInt16LE(8);
-    if (width > 0 && height > 0) return { width, height };
-    return null;
-  }
-
-  private detectBmpDimensions(): { width: number; height: number } | null {
-    if (!this.imageData || this.imageData.length < 26) return null;
-    const width = this.imageData.readInt32LE(18);
-    const height = Math.abs(this.imageData.readInt32LE(22));
-    if (width > 0 && height > 0) return { width, height };
-    return null;
-  }
-
-  private detectTiffDimensions(): { width: number; height: number } | null {
-    // Implementation as before
-    if (!this.imageData || this.imageData.length < 14) return null;
-    const isLittleEndian = this.imageData[0] === 0x49;
-    const ifdOffset = isLittleEndian ? this.imageData.readUInt32LE(4) : this.imageData.readUInt32BE(4);
-    if (ifdOffset + 14 > this.imageData.length) return null;
-    const numEntries = isLittleEndian ? this.imageData.readUInt16LE(ifdOffset) : this.imageData.readUInt16BE(ifdOffset);
-    let width = 0;
-    let height = 0;
-    for (let i = 0; i < numEntries; i++) {
-      const entryOffset = ifdOffset + 2 + i * 12;
-      if (entryOffset + 12 > this.imageData.length) break;
-      const tag = isLittleEndian ? this.imageData.readUInt16LE(entryOffset) : this.imageData.readUInt16BE(entryOffset);
-      const value = isLittleEndian ? this.imageData.readUInt32LE(entryOffset + 8) : this.imageData.readUInt32BE(entryOffset + 8);
-      if (tag === 256) width = value;
-      if (tag === 257) height = value;
-      if (width > 0 && height > 0) break;
-    }
-    if (width > 0 && height > 0) return { width, height };
-    return null;
-  }
-
-  private detectJpegDimensions(): { width: number; height: number } | null {
-    // Implementation as before
-    if (!this.imageData || this.imageData.length < 12) return null;
-    let offset = 2;
-    while (offset < this.imageData.length - 1) {
-      if (this.imageData[offset] !== 0xff) break;
-  const marker = this.imageData[offset + 1];
-  if (marker === undefined) break;
-  if (marker === 0x00 || marker === 0xff) {
-    offset++;
-    continue;
-  }
-  const isSOF = (marker >= 0xc0 && marker <= 0xcf) && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
-      if (isSOF) {
-        if (offset + 9 > this.imageData.length) break;
-        const height = this.imageData.readUInt16BE(offset + 5);
-        const width = this.imageData.readUInt16BE(offset + 7);
-        if (width > 0 && height > 0) return { width, height };
-      }
-      if (marker === 0xda || marker === 0xd9) break;
-      const segmentLength = this.imageData.readUInt16BE(offset + 2);
-      if (segmentLength < 2 || offset + 2 + segmentLength > this.imageData.length) break;
-      offset += 2 + segmentLength;
-    }
-    return null;
-  }
-
-  /**
-   * Detects SVG dimensions from width/height attributes or viewBox
-   */
-  private detectSvgDimensions(): { width: number; height: number } | null {
-    if (!this.imageData) return null;
-    try {
-      const svgText = this.imageData.toString('utf-8').substring(0, 2000);
-      // Try width/height attributes on <svg> element
-      const widthMatch = /<svg[^>]*\bwidth\s*=\s*["']?(\d+(?:\.\d+)?)/i.exec(svgText);
-      const heightMatch = /<svg[^>]*\bheight\s*=\s*["']?(\d+(?:\.\d+)?)/i.exec(svgText);
-      if (widthMatch?.[1] && heightMatch?.[1]) {
-        return { width: Math.round(parseFloat(widthMatch[1])), height: Math.round(parseFloat(heightMatch[1])) };
-      }
-      // Try viewBox attribute
-      const viewBoxMatch = /<svg[^>]*\bviewBox\s*=\s*["']?\s*[\d.]+\s+[\d.]+\s+([\d.]+)\s+([\d.]+)/i.exec(svgText);
-      if (viewBoxMatch?.[1] && viewBoxMatch?.[2]) {
-        return { width: Math.round(parseFloat(viewBoxMatch[1])), height: Math.round(parseFloat(viewBoxMatch[2])) };
-      }
-    } catch {
-      // SVG parsing failed
-    }
-    return null;
-  }
-
-  /**
-   * Detects EMF dimensions from ENHMETAHEADER rclFrame (offsets 24-36, 0.01mm units)
-   */
-  private detectEmfDimensions(): { width: number; height: number } | null {
-    if (!this.imageData || this.imageData.length < 40) return null;
-    try {
-      // rclFrame: left(24), top(28), right(32), bottom(36) in 0.01mm units
-      const left = this.imageData.readInt32LE(24);
-      const top = this.imageData.readInt32LE(28);
-      const right = this.imageData.readInt32LE(32);
-      const bottom = this.imageData.readInt32LE(36);
-      const widthMm = (right - left) / 100;
-      const heightMm = (bottom - top) / 100;
-      // Convert mm to pixels at 96 DPI (1 inch = 25.4mm)
-      const width = Math.round((widthMm / 25.4) * 96);
-      const height = Math.round((heightMm / 25.4) * 96);
-      if (width > 0 && height > 0) return { width, height };
-    } catch {
-      // EMF header parsing failed
-    }
-    return null;
-  }
-
-  /**
-   * Detects WMF dimensions from placeable WMF header bounding box (offsets 6-14)
-   */
-  private detectWmfDimensions(): { width: number; height: number } | null {
-    if (!this.imageData || this.imageData.length < 22) return null;
-    try {
-      // Placeable WMF header: left(6), top(8), right(10), bottom(12), inch(14)
-      const left = this.imageData.readInt16LE(6);
-      const top = this.imageData.readInt16LE(8);
-      const right = this.imageData.readInt16LE(10);
-      const bottom = this.imageData.readInt16LE(12);
-      const unitsPerInch = this.imageData.readUInt16LE(14);
-      if (unitsPerInch > 0) {
-        const width = Math.round(((right - left) / unitsPerInch) * 96);
-        const height = Math.round(((bottom - top) / unitsPerInch) * 96);
-        if (width > 0 && height > 0) return { width, height };
-      }
-    } catch {
-      // WMF header parsing failed
-    }
-    return null;
-  }
-
-  /**
-   * Gets the image data buffer asynchronously
-   */
-  async getImageDataAsync(): Promise<Buffer> {
-    await this.ensureDataLoaded();
-    if (!this.imageData) throw new Error('Failed to load image data');
-    return this.imageData;
-  }
-
-  /**
-   * Gets the image data buffer synchronously
-   */
-  getImageData(): Buffer {
-    if (!this.imageData) throw new Error('Image data not loaded. Call ensureDataLoaded first.');
-    return this.imageData;
-  }
-
-  getExtension(): string {
-    return this.extension;
-  }
-
-  getDPI(): number {
-    return this.dpi;
-  }
-
-  getWidth(): number {
-    return this.width;
-  }
-
-  getHeight(): number {
-    return this.height;
-  }
-
-  getImageDataSafe(): Buffer | null {
-    return this.imageData ?? null;
-  }
-
-  setWidth(width: number, maintainAspectRatio = true): this {
-    if (maintainAspectRatio && this.height > 0) {
-      const ratio = this.height / this.width;
-      this.height = Math.round(width * ratio);
-    }
-    this.width = width;
-    return this;
-  }
-
-  setHeight(height: number, maintainAspectRatio = true): this {
-    if (maintainAspectRatio && this.width > 0) {
-      const ratio = this.width / this.height;
-      this.width = Math.round(height * ratio);
-    }
-    this.height = height;
-    return this;
-  }
-
-  setSize(width: number, height: number): this {
-    this.width = width;
-    this.height = height;
-    return this;
-  }
-
-  async updateImageData(newSource: string | Buffer): Promise<void> {
-    this.source = newSource;
-    this.imageData = undefined;
-    await this.loadImageDataForDimensions();
-    this.extension = this.detectExtension();
-    this.dpi = this.detectDPI() || 96;
-  }
-
-  setRelationshipId(relationshipId: string): this {
-    this.relationshipId = relationshipId;
-    return this;
-  }
-
-  getRelationshipId(): string | undefined {
-    return this.relationshipId;
-  }
-
-  setDocPrId(id: number): this {
-    this.docPrId = id;
-    return this;
-  }
-
-  setAltText(altText: string): this {
-    this.description = altText;
-    return this;
-  }
-
-  getAltText(): string {
-    return this.description;
-  }
-
-  setTitle(title: string): this {
-    this.title = title;
-    return this;
-  }
-
-  getTitle(): string | undefined {
-    return this.title;
-  }
-
-  rotate(degrees: number): this {
-    this.rotation = ((degrees % 360) + 360) % 360;
-    if (this.rotation === 90 || this.rotation === 270) {
-      [this.width, this.height] = [this.height, this.width];
-    }
-    return this;
-  }
-
-  getRotation(): number {
-    return this.rotation;
-  }
-
-  setFlipH(flip: boolean): this {
-    this.flipH = flip;
-    return this;
-  }
-
-  getFlipH(): boolean {
-    return this.flipH;
-  }
-
-  setFlipV(flip: boolean): this {
-    this.flipV = flip;
-    return this;
-  }
-
-  getFlipV(): boolean {
-    return this.flipV;
-  }
-
-  // --- Group A: Simple attribute getters/setters ---
-
-  getPresetGeometry(): PresetGeometry { return this.presetGeometry; }
-  setPresetGeometry(geom: PresetGeometry): this { this.presetGeometry = geom; return this; }
-
-  getCompressionState(): BlipCompressionState { return this.compressionState; }
-  setCompressionState(state: BlipCompressionState): this { this.compressionState = state; return this; }
-
-  getBwMode(): string { return this.bwMode; }
-  setBwMode(mode: string): this { this.bwMode = mode; return this; }
-
-  getInlineDistT(): number { return this.inlineDistT; }
-  getInlineDistB(): number { return this.inlineDistB; }
-  getInlineDistL(): number { return this.inlineDistL; }
-  getInlineDistR(): number { return this.inlineDistR; }
-  setInlineDist(distT: number, distB: number, distL: number, distR: number): this {
-    this.inlineDistT = distT;
-    this.inlineDistB = distB;
-    this.inlineDistL = distL;
-    this.inlineDistR = distR;
-    return this;
-  }
-
-  getNoChangeAspect(): boolean { return this.noChangeAspect; }
-  setNoChangeAspect(val: boolean): this { this.noChangeAspect = val; return this; }
-
-  getHidden(): boolean { return this.hidden; }
-  setHidden(val: boolean): this { this.hidden = val; return this; }
-
-  getBlipFillDpi(): number | undefined { return this.blipFillDpi; }
-  setBlipFillDpi(dpi: number | undefined): this { this.blipFillDpi = dpi; return this; }
-
-  getBlipFillRotWithShape(): boolean | undefined { return this.blipFillRotWithShape; }
-  setBlipFillRotWithShape(val: boolean | undefined): this { this.blipFillRotWithShape = val; return this; }
-
-  getPicLocks(): Partial<Record<PicLockAttribute, boolean>> { return { ...this.picLocks }; }
-  setPicLocks(locks: Partial<Record<PicLockAttribute, boolean>>): this { this.picLocks = locks; return this; }
-
-  getPicNonVisualProps(): PicNonVisualProperties { return { ...this.picNonVisualProps }; }
-  setPicNonVisualProps(props: PicNonVisualProperties): this { this.picNonVisualProps = props; return this; }
-
-  getIsLinked(): boolean { return this.isLinked; }
-  setIsLinked(val: boolean): this { this.isLinked = val; return this; }
-
-  getSvgRelationshipId(): string | undefined { return this.svgRelationshipId; }
-  setSvgRelationshipId(id: string | undefined): this { this.svgRelationshipId = id; return this; }
-
-  // --- Group B: Raw passthrough storage ---
-
-  /** @internal */
-  _setRawPassthrough(slot: string, xml: string): void {
-    this._rawPassthrough.set(slot, xml);
-  }
-
-  /** @internal */
-  _getRawPassthrough(slot: string): string | undefined {
-    return this._rawPassthrough.get(slot);
-  }
-
-  /** @internal */
-  _hasRawPassthrough(slot: string): boolean {
-    return this._rawPassthrough.has(slot);
-  }
-
-  // --- Group C: Enhanced border ---
-
-  getBorder(): ImageBorder | undefined { return this.border; }
-
-  setEffectExtent(left: number, top: number, right: number, bottom: number): this {
-    this.effectExtent = { left, top, right, bottom };
-    return this;
-  }
-
-  getEffectExtent(): EffectExtent | undefined {
-    return this.effectExtent;
-  }
-
-  setWrap(type: WrapType, side?: WrapSide, distances?: { top?: number; bottom?: number; left?: number; right?: number }): this {
-    this.wrap = {
-      type,
-      side,
-      distanceTop: distances?.top,
-      distanceBottom: distances?.bottom,
-      distanceLeft: distances?.left,
-      distanceRight: distances?.right,
-    };
-    return this;
-  }
-
-  getWrap(): TextWrapSettings | undefined {
-    return this.wrap;
-  }
-
-  /**
-   * Validates a position offset value
-   * @param offset - Offset value in EMUs
-   * @param axis - 'horizontal' or 'vertical' for error messages
-   * @throws {Error} If offset exceeds maximum reasonable value
-   * @private
-   */
-  private validatePositionOffset(offset: number | undefined, axis: string): void {
-    if (offset === undefined) return;
-
-    // Maximum reasonable offset: 50 inches = 45,720,000 EMUs
-    const MAX_OFFSET_EMUS = 45720000;
-    if (Math.abs(offset) > MAX_OFFSET_EMUS) {
-      throw new Error(
-        `Invalid ${axis} position offset: ${offset} EMUs exceeds maximum of ${MAX_OFFSET_EMUS} EMUs (50 inches).`
-      );
-    }
-  }
-
-  /**
-   * Sets the position for a floating image
-   *
-   * Position can be specified using either:
-   * - Absolute offset (in EMUs from the anchor point)
-   * - Relative alignment (left, center, right / top, center, bottom)
-   *
-   * @param horizontal - Horizontal positioning configuration
-   * @param vertical - Vertical positioning configuration
-   * @returns This image for chaining
-   * @throws {Error} If offset values exceed maximum
-   *
-   * @example
-   * ```typescript
-   * // Absolute positioning (100,000 EMUs from page edges)
-   * image.setPosition(
-   *   { anchor: 'page', offset: 100000 },
-   *   { anchor: 'page', offset: 100000 }
-   * );
-   *
-   * // Relative alignment (centered on page)
-   * image.setPosition(
-   *   { anchor: 'page', alignment: 'center' },
-   *   { anchor: 'page', alignment: 'center' }
-   * );
-   * ```
-   */
-  setPosition(horizontal: ImagePosition['horizontal'], vertical: ImagePosition['vertical']): this {
-    // Validate offset values
-    this.validatePositionOffset(horizontal.offset, 'horizontal');
-    this.validatePositionOffset(vertical.offset, 'vertical');
-
-    this.position = { horizontal, vertical };
-    return this;
-  }
-
-  getPosition(): ImagePosition | undefined {
-    return this.position;
-  }
-
-  /**
-   * Validates the current image position configuration
-   *
-   * Checks for common configuration issues:
-   * - Missing anchor when offset is used
-   * - Conflicting offset and alignment values
-   * - Invalid combinations
-   *
-   * @returns Validation result with details
-   *
-   * @example
-   * ```typescript
-   * const result = image.validatePosition();
-   * if (!result.isValid) {
-   *   console.log(result.warnings); // Array of warning messages
-   * }
-   * ```
-   */
-  validatePosition(): {
-    isValid: boolean;
-    warnings: string[];
-  } {
-    const warnings: string[] = [];
-
-    if (!this.position) {
-      return { isValid: true, warnings };
-    }
-
-    // Check if both offset and alignment are specified (unusual but not invalid)
-    if (this.position.horizontal.offset !== undefined && this.position.horizontal.alignment) {
-      warnings.push(
-        'Horizontal position has both offset and alignment. Word will use alignment and ignore offset.'
-      );
-    }
-
-    if (this.position.vertical.offset !== undefined && this.position.vertical.alignment) {
-      warnings.push(
-        'Vertical position has both offset and alignment. Word will use alignment and ignore offset.'
-      );
-    }
-
-    // Check for floating image without anchor settings
-    if (this.position && !this.anchor) {
-      warnings.push(
-        'Position is set but anchor is not. Consider setting anchor properties for proper floating behavior.'
-      );
-    }
-
-    return {
-      isValid: warnings.length === 0,
-      warnings,
-    };
-  }
-
-  setAnchor(options: ImageAnchor): this {
-    this.anchor = options;
-    return this;
-  }
-
-  getAnchor(): ImageAnchor | undefined {
-    return this.anchor;
-  }
-
-  setCrop(left: number, top: number, right: number, bottom: number): this {
-    const clamp = (val: number) => Math.max(0, Math.min(100, val));
-    this.crop = { left: clamp(left), top: clamp(top), right: clamp(right), bottom: clamp(bottom) };
-    return this;
-  }
-
-  getCrop(): ImageCrop | undefined {
-    return this.crop;
-  }
-
-  setEffects(options: ImageEffects): this {
-    const clamp = (val?: number) => val !== undefined ? Math.max(-100, Math.min(100, val)) : undefined;
-    this.effects = { brightness: clamp(options.brightness), contrast: clamp(options.contrast), grayscale: options.grayscale, transparency: options.transparency !== undefined ? Math.max(0, Math.min(100, options.transparency)) : undefined };
-    return this;
-  }
-
-  getEffects(): ImageEffects | undefined {
-    return this.effects;
-  }
-
-  private detectDPI(): number | undefined {
-    if (!this.imageData) return undefined;
-
-    try {
-      if (this.extension === 'png') {
-        const physIndex = this.imageData.indexOf(Buffer.from([0x70, 0x48, 0x59, 0x73]));
-        if (physIndex !== -1 && physIndex + 12 < this.imageData.length) {
-          const xPixelsPerMeter = this.imageData.readUInt32BE(physIndex + 4);
-          const yPixelsPerMeter = this.imageData.readUInt32BE(physIndex + 8);
-          const unit = this.imageData[physIndex + 12];
-          if (unit === 1) {
-            const dpiX = Math.round(xPixelsPerMeter * 0.0254);
-            const dpiY = Math.round(yPixelsPerMeter * 0.0254);
-            return Math.min(dpiX, dpiY);
-          }
-        }
-      } else if (this.extension === 'jpg' || this.extension === 'jpeg') {
-        let offset = 2;
-        while (offset < this.imageData.length) {
-          if (this.imageData[offset] !== 0xFF) break;
-          const marker = this.imageData[offset + 1];
-          if (marker === 0xE0) {
-            const length = this.imageData.readUInt16BE(offset + 2);
-            if (length >= 16 && this.imageData.slice(offset + 4, offset + 9).toString('ascii') === 'JFIF\0') {
-              const units = this.imageData[offset + 11];
-              const xDensity = this.imageData.readUInt16BE(offset + 12);
-              const yDensity = this.imageData.readUInt16BE(offset + 14);
-              if (units === 1) return Math.min(xDensity, yDensity);
-              if (units === 2) return Math.min(Math.round(xDensity * 2.54), Math.round(yDensity * 2.54));
-            }
-            offset += 2 + length;
-            continue;
-          }
-          offset += 2 + this.imageData.readUInt16BE(offset + 2);
-        }
-      }
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
-      defaultLogger.warn(`DPI detection failed: ${message}`);
-    }
-    return undefined;
-  }
-
-  isFloating(): boolean {
-    return !!this.anchor || !!this.position;
-  }
-
-  floatTopLeft(marginTop = 0, marginLeft = 0): this {
-    this.setPosition(
-      { anchor: 'page', offset: marginLeft },
-      { anchor: 'page', offset: marginTop }
-    );
-    this.setAnchor({
-      behindDoc: false,
-      locked: false,
-      layoutInCell: true,
-      allowOverlap: true,
-      relativeHeight: 251658240
-    });
-    this.setWrap('square', 'bothSides');
-    return this;
-  }
-
-  floatTopRight(marginTop = 0, marginRight = 0): this {
-    this.setPosition(
-      { anchor: 'page', alignment: 'right', offset: -marginRight },
-      { anchor: 'page', offset: marginTop }
-    );
-    this.setAnchor({
-      behindDoc: false,
-      locked: false,
-      layoutInCell: true,
-      allowOverlap: true,
-      relativeHeight: 251658240
-    });
-    this.setWrap('square', 'bothSides');
-    return this;
-  }
-
-  floatCenter(): this {
-    this.setPosition(
-      { anchor: 'page', alignment: 'center' },
-      { anchor: 'page', alignment: 'center' }
-    );
-    this.setAnchor({
-      behindDoc: false,
-      locked: false,
-      layoutInCell: true,
-      allowOverlap: true,
-      relativeHeight: 251658240
-    });
-    this.setWrap('square', 'bothSides');
-    return this;
-  }
-
-  setBehindText(behind = true): this {
-    if (this.anchor) {
-      this.anchor.behindDoc = behind;
-    } else {
-      this.setAnchor({
-        behindDoc: behind,
-        locked: false,
-        layoutInCell: true,
-        allowOverlap: true,
-        relativeHeight: 251658240
-      });
-    }
-    return this;
-  }
-
-  /**
-   * Applies a border around the image
-   * @param thicknessOrOptions Border thickness in points (number) or full ImageBorder options
-   * @returns This image for chaining
-   *
-   * Note: effectExtent is set to accommodate the border width so it renders
-   * properly without being clipped. The border is drawn centered on the image
-   * edge, so half the border width extends outside the image bounds.
-   */
-  setBorder(thicknessOrOptions: number | ImageBorder = 2): this {
-    if (typeof thicknessOrOptions === 'number') {
-      this.border = { width: thicknessOrOptions };
-    } else {
-      this.border = thicknessOrOptions;
-    }
-
-    // Calculate space needed for border (half-width on each side)
-    // Border is drawn centered on the edge
-    const borderEmu = this.border.width * UNITS.EMUS_PER_POINT;
-    const halfBorderEmu = Math.ceil(borderEmu / 2);
-
-    // Ensure effectExtent has at least enough space for the border
-    if (!this.effectExtent) {
-      this.effectExtent = { left: 0, top: 0, right: 0, bottom: 0 };
-    }
-    this.effectExtent.left = Math.max(this.effectExtent.left, halfBorderEmu);
-    this.effectExtent.top = Math.max(this.effectExtent.top, halfBorderEmu);
-    this.effectExtent.right = Math.max(this.effectExtent.right, halfBorderEmu);
-    this.effectExtent.bottom = Math.max(this.effectExtent.bottom, halfBorderEmu);
-
-    return this;
-  }
-
-  /**
-   * Removes the border from the image
-   * @returns This image for chaining
-   */
-  removeBorder(): this {
-    this.border = undefined;
-    return this;
-  }
-
-  /**
-   * @deprecated Use setBorder() instead. This method will be removed in a future version.
-   * Applies a 2-point black border around the image.
-   * @returns This image for chaining
-   */
-  applyTwoPixelBlackBorder(): this {
-    return this.setBorder(2);
-  }
-
-  toXML(): XMLElement {
-    const isFloating = this.isFloating();
-
-    // Common elements - must include wp: namespace prefix
-    const extent = XMLBuilder.wp('extent', { cx: this.width.toString(), cy: this.height.toString() });
-
-    // --- Build blip element with effects ---
-    const blipChildren: XMLElement[] = [];
-
-    // Add luminance effect for brightness/contrast (per ECMA-376 §20.1.8.43)
-    if (this.effects?.brightness !== undefined || this.effects?.contrast !== undefined) {
-      const lumAttrs: Record<string, string> = {};
-      if (this.effects.brightness !== undefined) {
-        lumAttrs.bright = Math.round(this.effects.brightness * 1000).toString();
-      }
-      if (this.effects.contrast !== undefined) {
-        lumAttrs.contrast = Math.round(this.effects.contrast * 1000).toString();
-      }
-      blipChildren.push(XMLBuilder.aSelf('lum', lumAttrs));
-    }
-
-    // Add grayscale effect (per ECMA-376 §20.1.8.37)
-    if (this.effects?.grayscale) {
-      blipChildren.push(XMLBuilder.aSelf('grayscl'));
-    }
-
-    // Add transparency effect via a:alphaModFix (ECMA-376 §20.1.8.4)
-    if (this.effects?.transparency !== undefined && this.effects.transparency > 0) {
-      // transparency is 0-100%, alphaModFix amt is in 1/1000ths of percent
-      // e.g., 50% transparency = 50000 amt (= 50% opacity)
-      const amt = Math.round((100 - this.effects.transparency) * 1000);
-      blipChildren.push(XMLBuilder.aSelf('alphaModFix', { amt: amt.toString() }));
-    }
-
-    // Group B: Inject raw blip effects passthrough (a:clrChange, a:duotone, etc.)
-    if (this._rawPassthrough.has('blip-effects')) {
-      blipChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('blip-effects')! } as XMLElement);
-    }
-
-    // Group B: Inject raw blip extLst passthrough (must come last per schema)
-    if (this._rawPassthrough.has('blip-extLst')) {
-      blipChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('blip-extLst')! } as XMLElement);
-    } else if (this.svgRelationshipId) {
-      // SVG dual-relationship: add asvg:svgBlip reference in extLst
-      blipChildren.push({
-        name: '__rawXml',
-        rawXml: `<a:extLst><a:ext uri="{96DAC541-7B7A-43D3-8B79-37D633B846F1}"><asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG/main" r:embed="${this.svgRelationshipId}"/></a:ext></a:extLst>`,
-      } as XMLElement);
-    }
-
-    // Build blip attributes: r:embed or r:link, cstate
-    const blipAttrs: Record<string, string | undefined> = {
-      cstate: this.compressionState,
-    };
-    if (this.isLinked) {
-      blipAttrs['r:link'] = this.relationshipId;
-    } else {
-      blipAttrs['r:embed'] = this.relationshipId;
-    }
-
-    const blip = blipChildren.length > 0
-      ? XMLBuilder.a('blip', blipAttrs, blipChildren)
-      : XMLBuilder.a('blip', blipAttrs);
-
-    // --- Build transform (a:xfrm) ---
-    const xfrmAttrs: Record<string, string> | undefined = (() => {
-      const attrs: Record<string, string> = {};
-      if (this.rotation > 0) attrs.rot = Math.round(this.rotation * 60000).toString();
-      if (this.flipH) attrs.flipH = '1';
-      if (this.flipV) attrs.flipV = '1';
-      return Object.keys(attrs).length > 0 ? attrs : undefined;
-    })();
-    const xfrm = XMLBuilder.a('xfrm', xfrmAttrs, [
-      XMLBuilder.a('off', { x: '0', y: '0' }),
-      XMLBuilder.a('ext', { cx: this.width.toString(), cy: this.height.toString() })
-    ]);
-
-    // --- Build shape properties (pic:spPr) ---
-    const spPrChildren: XMLElement[] = [xfrm];
-
-    // Geometry: use passthrough for custGeom or prstGeom with avLst, otherwise default
-    if (this._rawPassthrough.has('geometry')) {
-      spPrChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('geometry')! } as XMLElement);
-    } else {
-      spPrChildren.push(XMLBuilder.a('prstGeom', { prst: this.presetGeometry }, [
-        XMLBuilder.a('avLst')
-      ]));
-    }
-
-    // Border (a:ln) - full model (Group C)
-    if (this.border) {
-      // Add noFill element before the border line (required by Word)
-      spPrChildren.push(XMLBuilder.a('noFill'));
-
-      const ptToEmu = 12700;
-      const widthEmu = this.border.width * ptToEmu;
-      const lnAttrs: Record<string, string> = { w: widthEmu.toString() };
-      if (this.border.cap) lnAttrs.cap = this.border.cap;
-      if (this.border.compound) lnAttrs.cmpd = this.border.compound;
-      if (this.border.alignment) lnAttrs.algn = this.border.alignment;
-
-      const lnChildren: XMLElement[] = [];
-
-      // Fill
-      if (this.border.rawFillXml) {
-        lnChildren.push({ name: '__rawXml', rawXml: this.border.rawFillXml } as XMLElement);
-      } else if (this.border.fill) {
-        const colorChildren: XMLElement[] = [];
-        if (this.border.fill.modifiers) {
-          for (const mod of this.border.fill.modifiers) {
-            colorChildren.push(XMLBuilder.aSelf(mod.name, { val: mod.val }));
-          }
-        }
-        const colorEl = colorChildren.length > 0
-          ? XMLBuilder.a(this.border.fill.type, { val: this.border.fill.value }, colorChildren)
-          : XMLBuilder.a(this.border.fill.type, { val: this.border.fill.value });
-        lnChildren.push(XMLBuilder.a('solidFill', undefined, [colorEl]));
-      } else {
-        // Default: scheme color tx1 (backward compat)
-        lnChildren.push(XMLBuilder.a('solidFill', undefined, [
-          XMLBuilder.a('schemeClr', { val: 'tx1' })
-        ]));
-      }
-
-      // Dash pattern
-      if (this.border.dashPattern) {
-        lnChildren.push(XMLBuilder.aSelf('prstDash', { val: this.border.dashPattern }));
-      }
-
-      // Join
-      if (this.border.join === 'round') {
-        lnChildren.push(XMLBuilder.aSelf('round'));
-      } else if (this.border.join === 'bevel') {
-        lnChildren.push(XMLBuilder.aSelf('bevel'));
-      } else if (this.border.join === 'miter') {
-        const miterAttrs: Record<string, string> = {};
-        if (this.border.miterLimit) miterAttrs.lim = this.border.miterLimit.toString();
-        lnChildren.push(XMLBuilder.aSelf('miter', miterAttrs));
-      }
-
-      // Head/tail end
-      if (this.border.headEnd) {
-        lnChildren.push(XMLBuilder.aSelf('headEnd', this.border.headEnd as Record<string, string>));
-      }
-      if (this.border.tailEnd) {
-        lnChildren.push(XMLBuilder.aSelf('tailEnd', this.border.tailEnd as Record<string, string>));
-      }
-
-      spPrChildren.push(XMLBuilder.a('ln', lnAttrs, lnChildren));
-    }
-
-    // Group B: Inject raw spPr effects passthrough (effectLst, scene3d, sp3d, etc.)
-    if (this._rawPassthrough.has('spPr-effects')) {
-      spPrChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('spPr-effects')! } as XMLElement);
-    }
-
-    // --- Build pic:cNvPr with passthrough ---
-    const cNvPrChildren: XMLElement[] = [];
-    if (this._rawPassthrough.has('cNvPr-extra')) {
-      cNvPrChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('cNvPr-extra')! } as XMLElement);
-    }
-    const cNvPr = cNvPrChildren.length > 0
-      ? XMLBuilder.pic('cNvPr', {
-          id: this.picNonVisualProps.id,
-          name: this.picNonVisualProps.name,
-          descr: this.picNonVisualProps.descr,
-        }, cNvPrChildren)
-      : XMLBuilder.pic('cNvPr', {
-          id: this.picNonVisualProps.id,
-          name: this.picNonVisualProps.name,
-          descr: this.picNonVisualProps.descr,
-        });
-
-    // --- Build picLocks from map ---
-    const picLocksAttrs: Record<string, string> = {};
-    for (const [key, val] of Object.entries(this.picLocks)) {
-      if (val) picLocksAttrs[key] = '1';
-    }
-
-    // --- Build blipFill ---
-    const blipFillAttrs: Record<string, string> = {};
-    if (this.blipFillDpi !== undefined) blipFillAttrs.dpi = this.blipFillDpi.toString();
-    if (this.blipFillRotWithShape !== undefined) blipFillAttrs.rotWithShape = this.blipFillRotWithShape ? '1' : '0';
-
-    const blipFillChildren: XMLElement[] = [blip];
-    // Crop values are stored as percentages (0-100), serialized as per-mille (0-100000)
-    if (this.crop) {
-      blipFillChildren.push(XMLBuilder.a('srcRect', {
-        l: Math.round(this.crop.left * 1000).toString(),
-        t: Math.round(this.crop.top * 1000).toString(),
-        r: Math.round(this.crop.right * 1000).toString(),
-        b: Math.round(this.crop.bottom * 1000).toString(),
-      }));
-    }
-    // Group B: Use tile passthrough instead of stretch when present
-    if (this._rawPassthrough.has('blipFill-extra')) {
-      blipFillChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('blipFill-extra')! } as XMLElement);
-    } else {
-      blipFillChildren.push(XMLBuilder.a('stretch', undefined, [XMLBuilder.a('fillRect')]));
-    }
-
-    const blipFillAttrsObj = Object.keys(blipFillAttrs).length > 0 ? blipFillAttrs : undefined;
-
-    const graphicData = XMLBuilder.a('graphicData', { uri: 'http://schemas.openxmlformats.org/drawingml/2006/picture' }, [
-      XMLBuilder.pic('pic', undefined, [
-        XMLBuilder.pic('nvPicPr', undefined, [
-          cNvPr,
-          XMLBuilder.pic('cNvPicPr', undefined, [
-            XMLBuilder.a('picLocks', Object.keys(picLocksAttrs).length > 0 ? picLocksAttrs : undefined)
-          ])
-        ]),
-        XMLBuilder.pic('blipFill', blipFillAttrsObj, blipFillChildren),
-        XMLBuilder.pic('spPr', { bwMode: this.bwMode }, spPrChildren)
-      ])
-    ]);
-
-    const graphic = XMLBuilder.a('graphic', undefined, [graphicData]);
-
-    // --- Build docPr element (shared between inline and floating) ---
-    const buildDocPr = (idVal: string | number): XMLElement => {
-      const attrs: Record<string, any> = { id: idVal, name: this.name, descr: this.description };
-      if (this.title) attrs.title = this.title;
-      if (this.hidden) attrs.hidden = '1';
-      const children: XMLElement[] = [];
-      if (this._rawPassthrough.has('docPr-extra')) {
-        children.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('docPr-extra')! } as XMLElement);
-      }
-      return children.length > 0
-        ? XMLBuilder.wp('docPr', attrs, children)
-        : XMLBuilder.wp('docPr', attrs);
-    };
-
-    // --- Build cNvGraphicFramePr element (shared between inline and floating) ---
-    const buildCNvGraphicFramePr = (): XMLElement => {
-      return XMLBuilder.wp('cNvGraphicFramePr', undefined, [
-        XMLBuilder.a('graphicFrameLocks', {
-          'xmlns:a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
-          noChangeAspect: this.noChangeAspect ? '1' : '0',
-        })
-      ]);
-    };
-
-    if (isFloating) {
-      // Floating image (anchor)
-      const positionHChildren: XMLElement[] = [];
-      if (this.position?.horizontal.alignment) {
-        positionHChildren.push(XMLBuilder.wp('align', undefined, [this.position.horizontal.alignment]));
-      } else {
-        positionHChildren.push(XMLBuilder.wp('posOffset', undefined, [(this.position?.horizontal.offset || 0).toString()]));
-      }
-      const positionH = XMLBuilder.wp('positionH', { relativeFrom: this.position?.horizontal.anchor || 'page' }, positionHChildren);
-
-      const positionVChildren: XMLElement[] = [];
-      if (this.position?.vertical.alignment) {
-        positionVChildren.push(XMLBuilder.wp('align', undefined, [this.position.vertical.alignment]));
-      } else {
-        positionVChildren.push(XMLBuilder.wp('posOffset', undefined, [(this.position?.vertical.offset || 0).toString()]));
-      }
-      const positionV = XMLBuilder.wp('positionV', { relativeFrom: this.position?.vertical.anchor || 'page' }, positionVChildren);
-
-      // Effect extent for floating images (required by Word)
-      const floatEffectExt = this.effectExtent || { left: 0, top: 0, right: 0, bottom: 0 };
-      const effectExtentElement = XMLBuilder.wp('effectExtent', {
-        t: floatEffectExt.top.toString(),
-        r: floatEffectExt.right.toString(),
-        b: floatEffectExt.bottom.toString(),
-        l: floatEffectExt.left.toString()
-      });
-
-      const anchorChildren: XMLElement[] = [
-        positionH,
-        positionV,
-        extent,
-        effectExtentElement
-      ];
-
-      // Wrap element (required by CT_Anchor per ECMA-376 — defaults to wrapNone)
-      if (this.wrap) {
-        const wrapAttrs: Record<string, any> = {};
-        if (this.wrap.distanceTop !== undefined) wrapAttrs.distT = this.wrap.distanceTop;
-        if (this.wrap.distanceBottom !== undefined) wrapAttrs.distB = this.wrap.distanceBottom;
-        if (this.wrap.distanceLeft !== undefined) wrapAttrs.distL = this.wrap.distanceLeft;
-        if (this.wrap.distanceRight !== undefined) wrapAttrs.distR = this.wrap.distanceRight;
-        if (this.wrap.side) wrapAttrs.wrapText = this.wrap.side;
-
-        let wrapElementName: string;
-        switch (this.wrap.type) {
-          case 'square': wrapElementName = 'wrapSquare'; break;
-          case 'tight': wrapElementName = 'wrapTight'; break;
-          case 'through': wrapElementName = 'wrapThrough'; break;
-          case 'topAndBottom': wrapElementName = 'wrapTopAndBottom'; break;
-          case 'none': wrapElementName = 'wrapNone'; break;
-          default: wrapElementName = 'wrapSquare';
-        }
-
-        // Group B: Include wrap polygon passthrough as children
-        const wrapChildren: XMLElement[] = [];
-        if (this._rawPassthrough.has('wrap-polygon')) {
-          wrapChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('wrap-polygon')! } as XMLElement);
-        } else if (wrapElementName === 'wrapTight' || wrapElementName === 'wrapThrough') {
-          // CT_WrapTight/CT_WrapThrough require a wp:wrapPolygon child.
-          // Generate a default rectangular polygon covering the full image extents.
-          wrapChildren.push({
-            name: 'wp:wrapPolygon',
-            attributes: { edited: '0' },
-            children: [
-              { name: 'wp:start', attributes: { x: '0', y: '0' }, selfClosing: true },
-              { name: 'wp:lineTo', attributes: { x: '21600', y: '0' }, selfClosing: true },
-              { name: 'wp:lineTo', attributes: { x: '21600', y: '21600' }, selfClosing: true },
-              { name: 'wp:lineTo', attributes: { x: '0', y: '21600' }, selfClosing: true },
-              { name: 'wp:lineTo', attributes: { x: '0', y: '0' }, selfClosing: true },
-            ],
-          });
-        }
-
-        anchorChildren.push(
-          wrapChildren.length > 0
-            ? XMLBuilder.wp(wrapElementName, wrapAttrs, wrapChildren)
-            : XMLBuilder.wp(wrapElementName, wrapAttrs)
-        );
-      } else {
-        // Default: wrapNone (required choice element per CT_Anchor)
-        anchorChildren.push(XMLBuilder.wp('wrapNone', {}));
-      }
-
-      anchorChildren.push(buildDocPr(this.docPrId));
-      anchorChildren.push(buildCNvGraphicFramePr());
-      anchorChildren.push(graphic);
-
-      // Group B: Inject anchor extras (wp14:sizeRelH, wp14:sizeRelV)
-      if (this._rawPassthrough.has('anchor-extra')) {
-        anchorChildren.push({ name: '__rawXml', rawXml: this._rawPassthrough.get('anchor-extra')! } as XMLElement);
-      }
-
-      // Build anchor attributes including simplePos and distance from text
-      const anchorAttrs: Record<string, any> = {
-        behindDoc: this.anchor?.behindDoc ? 1 : 0,
-        locked: this.anchor?.locked ? 1 : 0,
-        layoutInCell: this.anchor?.layoutInCell ? 1 : 0,
-        allowOverlap: this.anchor?.allowOverlap ? 1 : 0,
-        relativeHeight: this.anchor?.relativeHeight,
-        simplePos: this.anchor?.simplePos ? '1' : '0',
-        distT: (this.anchor?.distT ?? 0).toString(),
-        distB: (this.anchor?.distB ?? 0).toString(),
-        distL: (this.anchor?.distL ?? 0).toString(),
-        distR: (this.anchor?.distR ?? 0).toString(),
-      };
-      if (this.hidden) anchorAttrs.hidden = '1';
-
-      // Add wp:simplePos child element (required by ECMA-376 even when simplePos="0")
-      anchorChildren.unshift(XMLBuilder.wp('simplePos', { x: '0', y: '0' }));
-
-      return XMLBuilder.w('drawing', undefined, [
-        XMLBuilder.wp('anchor', anchorAttrs, anchorChildren)
-      ]);
-    } else {
-      // Inline image
-      const effectExt = this.effectExtent || { left: 0, top: 0, right: 0, bottom: 0 };
-
-      return XMLBuilder.w('drawing', undefined, [
-        XMLBuilder.wp('inline', {
-          distT: this.inlineDistT.toString(),
-          distB: this.inlineDistB.toString(),
-          distL: this.inlineDistL.toString(),
-          distR: this.inlineDistR.toString(),
-        }, [
-          extent,
-          XMLBuilder.wp('effectExtent', {
-            t: effectExt.top.toString(),
-            r: effectExt.right.toString(),
-            b: effectExt.bottom.toString(),
-            l: effectExt.left.toString()
-          }),
-          buildDocPr(this.docPrId.toString()),
-          buildCNvGraphicFramePr(),
-          graphic
-        ])
-      ]);
-    }
-  }
-}
+/**
+ * Image - Represents an embedded image in a Word document
+ *
+ * Images use DrawingML (a:) and WordprocessingML Drawing (wp:) namespaces
+ * for proper positioning and formatting in Word documents.
+ */
+
+import { promises as fs } from 'fs';
+import { defaultLogger } from '../utils/logger';
+import { inchesToEmus, UNITS } from '../utils/units';
+import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
+
+/**
+ * Supported image formats
+ */
+export type ImageFormat = 'png' | 'jpeg' | 'jpg' | 'gif' | 'bmp' | 'tiff' | 'svg' | 'emf' | 'wmf';
+
+/**
+ * Preset geometry shape type (ECMA-376 §20.1.9.18)
+ */
+export type PresetGeometry = 'rect' | 'roundRect' | 'ellipse' | string;
+
+/**
+ * Blip compression state (ECMA-376 §20.1.8.15)
+ */
+export type BlipCompressionState = 'none' | 'print' | 'email' | 'hqprint' | 'screen';
+
+/**
+ * Picture lock attribute names (ECMA-376 §20.1.2.2.31)
+ */
+export type PicLockAttribute =
+  | 'noChangeAspect'
+  | 'noChangeArrowheads'
+  | 'noSelect'
+  | 'noMove'
+  | 'noResize'
+  | 'noEditPoints'
+  | 'noAdjustHandles'
+  | 'noRot'
+  | 'noChangeShapeType'
+  | 'noCrop'
+  | 'noGrp';
+
+/**
+ * Non-visual picture properties (ECMA-376 §19.3.1.12)
+ */
+export interface PicNonVisualProperties {
+  id: string;
+  name: string;
+  descr: string;
+}
+
+/**
+ * Image border definition (full a:ln support per ECMA-376)
+ */
+export interface ImageBorder {
+  /** Border width in points */
+  width: number;
+  /** Line cap style */
+  cap?: 'flat' | 'rnd' | 'sq';
+  /** Compound line type */
+  compound?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri';
+  /** Alignment relative to shape */
+  alignment?: 'ctr' | 'in';
+  /** Fill specification */
+  fill?: {
+    type: 'srgbClr' | 'schemeClr';
+    value: string;
+    modifiers?: { name: string; val: string }[];
+  };
+  /** Raw XML for non-solid fills (gradFill, pattFill, etc.) */
+  rawFillXml?: string;
+  /** Preset dash pattern */
+  dashPattern?: string;
+  /** Line join style */
+  join?: 'round' | 'bevel' | 'miter';
+  /** Miter limit (percentage * 1000) */
+  miterLimit?: number;
+  /** Head end decoration */
+  headEnd?: { type?: string; width?: string; length?: string };
+  /** Tail end decoration */
+  tailEnd?: { type?: string; width?: string; length?: string };
+}
+
+/**
+ * Image extent (dimensions)
+ */
+export interface ImageExtent {
+  /** Width in EMUs */
+  width: number;
+  /** Height in EMUs */
+  height: number;
+}
+
+/**
+ * Effect extent (additional space for shadows, reflections, glows)
+ * Specifies additional space to add to each edge to prevent clipping of effects
+ */
+export interface EffectExtent {
+  /** Left extent in EMUs */
+  left: number;
+  /** Top extent in EMUs */
+  top: number;
+  /** Right extent in EMUs */
+  right: number;
+  /** Bottom extent in EMUs */
+  bottom: number;
+}
+
+/**
+ * Text wrapping type
+ */
+export type WrapType = 'square' | 'tight' | 'through' | 'topAndBottom' | 'none';
+
+/**
+ * Text wrapping side
+ */
+export type WrapSide = 'bothSides' | 'left' | 'right' | 'largest';
+
+/**
+ * Text wrap settings
+ */
+export interface TextWrapSettings {
+  /** Wrap type */
+  type: WrapType;
+  /** Which side(s) to wrap text */
+  side?: WrapSide;
+  /** Distance from top in EMUs */
+  distanceTop?: number;
+  /** Distance from bottom in EMUs */
+  distanceBottom?: number;
+  /** Distance from left in EMUs */
+  distanceLeft?: number;
+  /** Distance from right in EMUs */
+  distanceRight?: number;
+}
+
+/**
+ * Position anchor type (what to position relative to)
+ */
+export type PositionAnchor = 'page' | 'margin' | 'column' | 'character' | 'paragraph';
+
+/**
+ * Horizontal alignment options
+ */
+export type HorizontalAlignment = 'left' | 'center' | 'right' | 'inside' | 'outside';
+
+/**
+ * Vertical alignment options
+ */
+export type VerticalAlignment = 'top' | 'center' | 'bottom' | 'inside' | 'outside';
+
+/**
+ * Image position configuration
+ */
+export interface ImagePosition {
+  /** Horizontal positioning */
+  horizontal: {
+    /** Anchor point */
+    anchor: PositionAnchor;
+    /** Offset in EMUs (absolute positioning) */
+    offset?: number;
+    /** Alignment (relative positioning) */
+    alignment?: HorizontalAlignment;
+  };
+  /** Vertical positioning */
+  vertical: {
+    /** Anchor point */
+    anchor: PositionAnchor;
+    /** Offset in EMUs (absolute positioning) */
+    offset?: number;
+    /** Alignment (relative positioning) */
+    alignment?: VerticalAlignment;
+  };
+}
+
+/**
+ * Image anchor configuration (floating images)
+ */
+export interface ImageAnchor {
+  /** Position behind text */
+  behindDoc: boolean;
+  /** Lock anchor (prevent movement) */
+  locked: boolean;
+  /** Layout in table cell */
+  layoutInCell: boolean;
+  /** Allow overlap with other objects */
+  allowOverlap: boolean;
+  /** Z-order (higher = in front) */
+  relativeHeight: number;
+  /** Use simple positioning (wp:simplePos coordinates) */
+  simplePos?: boolean;
+  /** Distance from text - top (EMUs) */
+  distT?: number;
+  /** Distance from text - bottom (EMUs) */
+  distB?: number;
+  /** Distance from text - left (EMUs) */
+  distL?: number;
+  /** Distance from text - right (EMUs) */
+  distR?: number;
+}
+
+/**
+ * Image crop settings (percentage-based)
+ */
+export interface ImageCrop {
+  /** Left crop percentage (0-100) */
+  left: number;
+  /** Top crop percentage (0-100) */
+  top: number;
+  /** Right crop percentage (0-100) */
+  right: number;
+  /** Bottom crop percentage (0-100) */
+  bottom: number;
+}
+
+/**
+ * Image visual effects
+ */
+export interface ImageEffects {
+  /** Brightness adjustment (-100 to +100) */
+  brightness?: number;
+  /** Contrast adjustment (-100 to +100) */
+  contrast?: number;
+  /** Convert to grayscale */
+  grayscale?: boolean;
+  /** Transparency (0-100, percentage) via a:alphaModFix */
+  transparency?: number;
+}
+
+/**
+ * Image properties
+ */
+export interface ImageProperties {
+  /** Image source (file path or buffer) */
+  source: string | Buffer;
+  /** Image width in EMUs (optional - will auto-detect) */
+  width?: number;
+  /** Image height in EMUs (optional - will auto-detect) */
+  height?: number;
+  /** Maintain aspect ratio when resizing */
+  maintainAspectRatio?: boolean;
+  /** Alt text / description */
+  description?: string;
+  /** Image name/title */
+  name?: string;
+  /** Image title (wp:docPr title attribute for accessibility) */
+  title?: string;
+  /** Relationship ID (will be set by ImageManager) */
+  relationshipId?: string;
+  /** Effect extent (space for shadows/glows) */
+  effectExtent?: EffectExtent;
+  /** Text wrapping configuration */
+  wrap?: TextWrapSettings;
+  /** Position configuration (floating images) */
+  position?: ImagePosition;
+  /** Anchor configuration (floating images) */
+  anchor?: ImageAnchor;
+  /** Crop settings */
+  crop?: ImageCrop;
+  /** Visual effects */
+  effects?: ImageEffects;
+  /** Border settings */
+  border?: ImageBorder | { width: number };
+  /** Rotation angle in degrees (0-360) */
+  rotation?: number;
+  /** Horizontal flip (ECMA-376 §20.1.7.6) */
+  flipH?: boolean;
+  /** Vertical flip (ECMA-376 §20.1.7.6) */
+  flipV?: boolean;
+  /** Preset geometry shape (ECMA-376 §20.1.9.18) */
+  presetGeometry?: PresetGeometry;
+  /** Blip compression state (ECMA-376 §20.1.8.15) */
+  compressionState?: BlipCompressionState;
+  /** Black-and-white mode (ECMA-376 §20.1.2.2.35) */
+  bwMode?: string;
+  /** Inline distance from text - top (EMUs, ECMA-376 §20.4.2.8) */
+  inlineDistT?: number;
+  /** Inline distance from text - bottom (EMUs) */
+  inlineDistB?: number;
+  /** Inline distance from text - left (EMUs) */
+  inlineDistL?: number;
+  /** Inline distance from text - right (EMUs) */
+  inlineDistR?: number;
+  /** Whether aspect ratio lock is enabled (ECMA-376 §20.4.2.4) */
+  noChangeAspect?: boolean;
+  /** Hidden attribute on docPr (ECMA-376 §20.4.2.3) */
+  hidden?: boolean;
+  /** BlipFill DPI override (ECMA-376 §20.1.8.14) */
+  blipFillDpi?: number;
+  /** BlipFill rotate with shape flag (ECMA-376 §20.1.8.14) */
+  blipFillRotWithShape?: boolean;
+  /** Picture locks (ECMA-376 §20.1.2.2.31) */
+  picLocks?: Partial<Record<PicLockAttribute, boolean>>;
+  /** Non-visual picture properties (ECMA-376 §19.3.1.12) */
+  picNonVisualProps?: PicNonVisualProperties;
+  /** Whether image is linked (r:link) vs embedded (r:embed) */
+  isLinked?: boolean;
+  /** SVG relationship ID for Word 365 dual-relationship approach */
+  svgRelationshipId?: string;
+}
+
+/**
+ * Image validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+export class Image {
+  private source: string | Buffer;
+  private width: number;
+  private height: number;
+  private description: string;
+  private name: string;
+  private title?: string;
+  private relationshipId?: string;
+  private imageData?: Buffer;
+  private extension: string;
+  private docPrId = 1;
+  private dpi = 96; // Default DPI
+
+  // Advanced image properties
+  private effectExtent?: EffectExtent;
+  private wrap?: TextWrapSettings;
+  private position?: ImagePosition;
+  private anchor?: ImageAnchor;
+  private crop?: ImageCrop;
+  private effects?: ImageEffects;
+  private rotation = 0;
+  private flipH = false;
+  private flipV = false;
+  private border?: ImageBorder;
+
+  // Group A: Simple attribute preservation (ECMA-376 compliance)
+  private presetGeometry: PresetGeometry = 'rect';
+  private compressionState: BlipCompressionState = 'none';
+  private bwMode = 'auto';
+  private inlineDistT = 0;
+  private inlineDistB = 0;
+  private inlineDistL = 0;
+  private inlineDistR = 0;
+  private noChangeAspect = true;
+  private hidden = false;
+  private blipFillDpi?: number;
+  private blipFillRotWithShape?: boolean;
+  private picLocks: Partial<Record<PicLockAttribute, boolean>> = {
+    noChangeAspect: true,
+    noChangeArrowheads: true,
+  };
+  private picNonVisualProps: PicNonVisualProperties = { id: '0', name: '', descr: '' };
+  private isLinked = false;
+  private svgRelationshipId?: string;
+
+  // Group B: Raw XML passthrough for complex subtrees
+  private _rawPassthrough = new Map<string, string>();
+
+  /**
+   * Creates a new image from file path (async factory)
+   * @param path File path
+   * @param properties Additional properties
+   * @returns Promise<Image>
+   */
+  static async fromFile(path: string, properties: Partial<ImageProperties> = {}): Promise<Image> {
+    const image = new Image({ source: path, ...properties });
+    await image.loadImageDataForDimensions();
+    return image;
+  }
+
+  /**
+   * Creates a new image from buffer (async factory)
+   * Supports both modern and legacy API signatures
+   *
+   * @param buffer Image buffer
+   * @param mimeTypeOrProperties MIME type string ('png', 'jpeg', etc.) or properties object
+   * @param width Optional width in EMUs (legacy API)
+   * @param height Optional height in EMUs (legacy API)
+   * @returns Promise<Image>
+   *
+   * @example
+   * // Modern API (recommended)
+   * const img = await Image.fromBuffer(buffer, { mimeType: 'png', width: 914400, height: 914400 });
+   *
+   * // Legacy API (still supported)
+   * const img = await Image.fromBuffer(buffer, 'png', 914400, 914400);
+   */
+  static async fromBuffer(
+    buffer: Buffer,
+    mimeTypeOrProperties?: string | Partial<ImageProperties>,
+    width?: number,
+    height?: number
+  ): Promise<Image> {
+    let properties: Partial<ImageProperties>;
+
+    // Detect API signature
+    if (typeof mimeTypeOrProperties === 'string') {
+      // Legacy 4-parameter signature: fromBuffer(buffer, 'png', 914400, 914400)
+      // Note: mimeType is ignored - extension is auto-detected from buffer
+      properties = {
+        width: width,
+        height: height,
+      };
+    } else {
+      // Modern API: fromBuffer(buffer, { width: 914400, height: 914400 })
+      properties = mimeTypeOrProperties || {};
+    }
+
+    const image = new Image({ source: buffer, ...properties });
+    await image.loadImageDataForDimensions();
+    return image;
+  }
+
+  /**
+   * Unified create method for images (async factory)
+   * @param properties Image properties including source (path or buffer)
+   * @returns Promise<Image>
+   */
+  static async create(properties: ImageProperties): Promise<Image> {
+    if (Buffer.isBuffer(properties.source)) {
+      return Image.fromBuffer(properties.source, properties);
+    } else if (typeof properties.source === 'string') {
+      return Image.fromFile(properties.source, properties);
+    } else {
+      throw new Error('Invalid source: must be file path or Buffer');
+    }
+  }
+
+  /**
+   * Private constructor
+   * @param properties Image properties
+   */
+  private constructor(properties: ImageProperties) {
+    this.source = properties.source;
+    this.description = properties.description || 'Image';
+    this.name = properties.name || 'image';
+    this.title = properties.title;
+    this.relationshipId = properties.relationshipId;
+
+    // Detect image extension
+    this.extension = this.detectExtension();
+
+    // Set default dimensions (6 inches x 4 inches) if not provided
+    this.width = properties.width || inchesToEmus(6);
+    this.height = properties.height || inchesToEmus(4);
+
+    // Initialize advanced properties
+    this.effectExtent = properties.effectExtent;
+    this.wrap = properties.wrap;
+    this.position = properties.position;
+    this.anchor = properties.anchor;
+    this.crop = properties.crop;
+    this.effects = properties.effects;
+    // Border: accept both legacy { width } and full ImageBorder
+    if (properties.border) {
+      this.border = properties.border as ImageBorder;
+    }
+    // Apply rotation if provided (normalize to 0-360)
+    if (properties.rotation !== undefined && properties.rotation !== 0) {
+      this.rotation = ((properties.rotation % 360) + 360) % 360;
+    }
+    // Apply flip attributes (ECMA-376 §20.1.7.6)
+    this.flipH = properties.flipH || false;
+    this.flipV = properties.flipV || false;
+
+    // Group A: Simple attribute preservation
+    if (properties.presetGeometry !== undefined) this.presetGeometry = properties.presetGeometry;
+    if (properties.compressionState !== undefined)
+      this.compressionState = properties.compressionState;
+    if (properties.bwMode !== undefined) this.bwMode = properties.bwMode;
+    if (properties.inlineDistT !== undefined) this.inlineDistT = properties.inlineDistT;
+    if (properties.inlineDistB !== undefined) this.inlineDistB = properties.inlineDistB;
+    if (properties.inlineDistL !== undefined) this.inlineDistL = properties.inlineDistL;
+    if (properties.inlineDistR !== undefined) this.inlineDistR = properties.inlineDistR;
+    if (properties.noChangeAspect !== undefined) this.noChangeAspect = properties.noChangeAspect;
+    if (properties.hidden !== undefined) this.hidden = properties.hidden;
+    if (properties.blipFillDpi !== undefined) this.blipFillDpi = properties.blipFillDpi;
+    if (properties.blipFillRotWithShape !== undefined)
+      this.blipFillRotWithShape = properties.blipFillRotWithShape;
+    if (properties.picLocks !== undefined) this.picLocks = properties.picLocks;
+    if (properties.picNonVisualProps !== undefined)
+      this.picNonVisualProps = properties.picNonVisualProps;
+    if (properties.isLinked !== undefined) this.isLinked = properties.isLinked;
+    if (properties.svgRelationshipId !== undefined)
+      this.svgRelationshipId = properties.svgRelationshipId;
+
+    // Set default DPI
+    this.dpi = 96;
+  }
+
+  /**
+   * Loads image data temporarily for dimension detection only
+   * Data is released after detection to save memory
+   * @private
+   */
+  private async loadImageDataForDimensions(): Promise<void> {
+    let tempData: Buffer | undefined;
+
+    try {
+      if (Buffer.isBuffer(this.source)) {
+        tempData = this.source;
+      } else if (typeof this.source === 'string') {
+        await fs.access(this.source);
+        tempData = await fs.readFile(this.source);
+      }
+
+      if (tempData) {
+        this.imageData = tempData; // Temporarily store
+
+        // Only auto-detect dimensions if they weren't explicitly provided
+        // This preserves wp:extent values from parsed documents
+        const defaultWidth = inchesToEmus(6);
+        const defaultHeight = inchesToEmus(4);
+        const hasExplicitDimensions = this.width !== defaultWidth || this.height !== defaultHeight;
+
+        if (!hasExplicitDimensions) {
+          const dimensions = this.detectDimensions();
+          if (dimensions) {
+            this.dpi = this.detectDPI() || 96;
+            const emuPerInch = 914400;
+            const pixelsPerInch = this.dpi;
+            this.width = Math.round((dimensions.width / pixelsPerInch) * emuPerInch);
+            this.height = Math.round((dimensions.height / pixelsPerInch) * emuPerInch);
+          }
+        }
+
+        if (typeof this.source === 'string') {
+          this.imageData = undefined; // Release
+        }
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      defaultLogger.error(`Failed to load image for dimensions: ${message}`);
+      throw new Error(`Image loading failed: ${message}`);
+    }
+  }
+
+  /**
+   * Ensures image data is loaded (lazy loading)
+   */
+  async ensureDataLoaded(): Promise<void> {
+    if (this.imageData) return;
+
+    try {
+      if (Buffer.isBuffer(this.source)) {
+        this.imageData = this.source;
+      } else if (typeof this.source === 'string') {
+        await fs.access(this.source);
+        this.imageData = await fs.readFile(this.source);
+      } else {
+        throw new Error('Invalid image source');
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      defaultLogger.error(`Failed to load image data: ${message}`);
+      throw new Error(`Image data loading failed: ${message}`);
+    }
+  }
+
+  /**
+   * Releases image data from memory
+   */
+  releaseData(): void {
+    if (typeof this.source === 'string') {
+      this.imageData = undefined;
+    }
+  }
+
+  /**
+   * Validates the image data integrity
+   */
+  validateImageData(): ValidationResult {
+    // Skip validation for linked images (no data in package)
+    if (this.isLinked) {
+      return { valid: true };
+    }
+
+    if (!this.imageData || this.imageData.length === 0) {
+      return { valid: false, error: 'Empty image data' };
+    }
+
+    // Skip signature validation for text-based formats (SVG)
+    if (this.extension === 'svg') {
+      return { valid: true };
+    }
+
+    const signatures: Record<string, number[]> = {
+      png: [0x89, 0x50, 0x4e, 0x47],
+      jpg: [0xff, 0xd8],
+      jpeg: [0xff, 0xd8],
+      gif: [0x47, 0x49, 0x46],
+      bmp: [0x42, 0x4d],
+      tiff: [0x49, 0x49, 0x2a, 0x00],
+      tif: [0x49, 0x49, 0x2a, 0x00],
+    };
+
+    // EMF: check for ENHMETAHEADER signature at offset 40
+    if (this.extension === 'emf') {
+      if (
+        this.imageData.length >= 44 &&
+        this.imageData[40] === 0x20 &&
+        this.imageData[41] === 0x45 &&
+        this.imageData[42] === 0x4d &&
+        this.imageData[43] === 0x46
+      ) {
+        return { valid: true };
+      }
+      return { valid: false, error: 'Invalid EMF signature' };
+    }
+
+    // WMF: check for placeable or standard header
+    if (this.extension === 'wmf') {
+      if (this.imageData.length >= 4) {
+        // Placeable WMF
+        if (
+          this.imageData[0] === 0xd7 &&
+          this.imageData[1] === 0xcd &&
+          this.imageData[2] === 0xc6 &&
+          this.imageData[3] === 0x9a
+        ) {
+          return { valid: true };
+        }
+        // Standard WMF
+        if (
+          this.imageData[0] === 0x01 &&
+          this.imageData[1] === 0x00 &&
+          this.imageData[2] === 0x09 &&
+          this.imageData[3] === 0x00
+        ) {
+          return { valid: true };
+        }
+      }
+      return { valid: false, error: 'Invalid WMF signature' };
+    }
+
+    const sig = signatures[this.extension];
+    if (sig) {
+      for (let i = 0; i < sig.length; i++) {
+        if (this.imageData[i] !== sig[i]) {
+          return { valid: false, error: `Invalid ${this.extension.toUpperCase()} signature` };
+        }
+      }
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Detects image extension from source (path or buffer)
+   */
+  private detectExtension(): string {
+    // Try path-based detection first
+    if (typeof this.source === 'string') {
+      const match = /\.([a-z]+)$/i.exec(this.source);
+      if (match?.[1]) {
+        return match[1].toLowerCase();
+      }
+    }
+
+    // Buffer-based detection using magic bytes
+    if (Buffer.isBuffer(this.source) && this.source.length >= 4) {
+      const buf = this.source;
+      // PNG
+      if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'png';
+      // JPEG
+      if (buf[0] === 0xff && buf[1] === 0xd8) return 'jpeg';
+      // GIF
+      if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46) return 'gif';
+      // BMP
+      if (buf[0] === 0x42 && buf[1] === 0x4d) return 'bmp';
+      // TIFF LE
+      if (buf[0] === 0x49 && buf[1] === 0x49 && buf[2] === 0x2a && buf[3] === 0x00) return 'tiff';
+      // TIFF BE
+      if (buf[0] === 0x4d && buf[1] === 0x4d && buf[2] === 0x00 && buf[3] === 0x2a) return 'tiff';
+      // EMF: byte 0 = 0x01,0x00,0x00,0x00 AND ' EMF' at offset 40
+      if (
+        buf.length >= 44 &&
+        buf[0] === 0x01 &&
+        buf[1] === 0x00 &&
+        buf[2] === 0x00 &&
+        buf[3] === 0x00 &&
+        buf[40] === 0x20 &&
+        buf[41] === 0x45 &&
+        buf[42] === 0x4d &&
+        buf[43] === 0x46
+      )
+        return 'emf';
+      // WMF placeable
+      if (buf[0] === 0xd7 && buf[1] === 0xcd && buf[2] === 0xc6 && buf[3] === 0x9a) return 'wmf';
+      // WMF standard
+      if (buf[0] === 0x01 && buf[1] === 0x00 && buf[2] === 0x09 && buf[3] === 0x00) return 'wmf';
+      // SVG: starts with '<' or UTF-8 BOM + '<'
+      if (
+        buf[0] === 0x3c ||
+        (buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf && buf.length > 3 && buf[3] === 0x3c)
+      )
+        return 'svg';
+    }
+
+    return 'png';
+  }
+
+  /**
+   * Attempts to detect image dimensions from buffer
+   */
+  private detectDimensions(): { width: number; height: number } | null {
+    if (!this.imageData || this.imageData.length < 24) return null;
+
+    if (
+      this.imageData[0] === 0x89 &&
+      this.imageData[1] === 0x50 &&
+      this.imageData[2] === 0x4e &&
+      this.imageData[3] === 0x47
+    ) {
+      return this.detectPngDimensions();
+    }
+    if (this.imageData[0] === 0xff && this.imageData[1] === 0xd8) {
+      return this.detectJpegDimensions();
+    }
+    if (this.imageData[0] === 0x47 && this.imageData[1] === 0x49 && this.imageData[2] === 0x46) {
+      return this.detectGifDimensions();
+    }
+    if (this.imageData[0] === 0x42 && this.imageData[1] === 0x4d) {
+      return this.detectBmpDimensions();
+    }
+    if (
+      (this.imageData[0] === 0x49 && this.imageData[1] === 0x49 && this.imageData[2] === 0x2a) ||
+      (this.imageData[0] === 0x4d && this.imageData[1] === 0x4d && this.imageData[2] === 0x00)
+    ) {
+      return this.detectTiffDimensions();
+    }
+    // EMF: ENHMETAHEADER has ' EMF' at offset 40
+    if (
+      this.imageData.length >= 44 &&
+      this.imageData[40] === 0x20 &&
+      this.imageData[41] === 0x45 &&
+      this.imageData[42] === 0x4d &&
+      this.imageData[43] === 0x46
+    ) {
+      return this.detectEmfDimensions();
+    }
+    // WMF placeable
+    if (
+      this.imageData[0] === 0xd7 &&
+      this.imageData[1] === 0xcd &&
+      this.imageData[2] === 0xc6 &&
+      this.imageData[3] === 0x9a
+    ) {
+      return this.detectWmfDimensions();
+    }
+    // SVG (text-based)
+    if (
+      this.imageData[0] === 0x3c ||
+      (this.imageData[0] === 0xef && this.imageData[1] === 0xbb && this.imageData[2] === 0xbf)
+    ) {
+      return this.detectSvgDimensions();
+    }
+    return null;
+  }
+
+  // Dimension detection helpers (as before, keeping them the same)
+
+  private detectPngDimensions(): { width: number; height: number } | null {
+    if (!this.imageData || this.imageData.length < 24) return null;
+    const width = this.imageData.readUInt32BE(16);
+    const height = this.imageData.readUInt32BE(20);
+    return { width, height };
+  }
+
+  private detectGifDimensions(): { width: number; height: number } | null {
+    if (!this.imageData || this.imageData.length < 10) return null;
+    const width = this.imageData.readUInt16LE(6);
+    const height = this.imageData.readUInt16LE(8);
+    if (width > 0 && height > 0) return { width, height };
+    return null;
+  }
+
+  private detectBmpDimensions(): { width: number; height: number } | null {
+    if (!this.imageData || this.imageData.length < 26) return null;
+    const width = this.imageData.readInt32LE(18);
+    const height = Math.abs(this.imageData.readInt32LE(22));
+    if (width > 0 && height > 0) return { width, height };
+    return null;
+  }
+
+  private detectTiffDimensions(): { width: number; height: number } | null {
+    // Implementation as before
+    if (!this.imageData || this.imageData.length < 14) return null;
+    const isLittleEndian = this.imageData[0] === 0x49;
+    const ifdOffset = isLittleEndian
+      ? this.imageData.readUInt32LE(4)
+      : this.imageData.readUInt32BE(4);
+    if (ifdOffset + 14 > this.imageData.length) return null;
+    const numEntries = isLittleEndian
+      ? this.imageData.readUInt16LE(ifdOffset)
+      : this.imageData.readUInt16BE(ifdOffset);
+    let width = 0;
+    let height = 0;
+    for (let i = 0; i < numEntries; i++) {
+      const entryOffset = ifdOffset + 2 + i * 12;
+      if (entryOffset + 12 > this.imageData.length) break;
+      const tag = isLittleEndian
+        ? this.imageData.readUInt16LE(entryOffset)
+        : this.imageData.readUInt16BE(entryOffset);
+      const value = isLittleEndian
+        ? this.imageData.readUInt32LE(entryOffset + 8)
+        : this.imageData.readUInt32BE(entryOffset + 8);
+      if (tag === 256) width = value;
+      if (tag === 257) height = value;
+      if (width > 0 && height > 0) break;
+    }
+    if (width > 0 && height > 0) return { width, height };
+    return null;
+  }
+
+  private detectJpegDimensions(): { width: number; height: number } | null {
+    // Implementation as before
+    if (!this.imageData || this.imageData.length < 12) return null;
+    let offset = 2;
+    while (offset < this.imageData.length - 1) {
+      if (this.imageData[offset] !== 0xff) break;
+      const marker = this.imageData[offset + 1];
+      if (marker === undefined) break;
+      if (marker === 0x00 || marker === 0xff) {
+        offset++;
+        continue;
+      }
+      const isSOF =
+        marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+      if (isSOF) {
+        if (offset + 9 > this.imageData.length) break;
+        const height = this.imageData.readUInt16BE(offset + 5);
+        const width = this.imageData.readUInt16BE(offset + 7);
+        if (width > 0 && height > 0) return { width, height };
+      }
+      if (marker === 0xda || marker === 0xd9) break;
+      const segmentLength = this.imageData.readUInt16BE(offset + 2);
+      if (segmentLength < 2 || offset + 2 + segmentLength > this.imageData.length) break;
+      offset += 2 + segmentLength;
+    }
+    return null;
+  }
+
+  /**
+   * Detects SVG dimensions from width/height attributes or viewBox
+   */
+  private detectSvgDimensions(): { width: number; height: number } | null {
+    if (!this.imageData) return null;
+    try {
+      const svgText = this.imageData.toString('utf-8').substring(0, 2000);
+      // Try width/height attributes on <svg> element
+      const widthMatch = /<svg[^>]*\bwidth\s*=\s*["']?(\d+(?:\.\d+)?)/i.exec(svgText);
+      const heightMatch = /<svg[^>]*\bheight\s*=\s*["']?(\d+(?:\.\d+)?)/i.exec(svgText);
+      if (widthMatch?.[1] && heightMatch?.[1]) {
+        return {
+          width: Math.round(parseFloat(widthMatch[1])),
+          height: Math.round(parseFloat(heightMatch[1])),
+        };
+      }
+      // Try viewBox attribute
+      const viewBoxMatch =
+        /<svg[^>]*\bviewBox\s*=\s*["']?\s*[\d.]+\s+[\d.]+\s+([\d.]+)\s+([\d.]+)/i.exec(svgText);
+      if (viewBoxMatch?.[1] && viewBoxMatch?.[2]) {
+        return {
+          width: Math.round(parseFloat(viewBoxMatch[1])),
+          height: Math.round(parseFloat(viewBoxMatch[2])),
+        };
+      }
+    } catch {
+      // SVG parsing failed
+    }
+    return null;
+  }
+
+  /**
+   * Detects EMF dimensions from ENHMETAHEADER rclFrame (offsets 24-36, 0.01mm units)
+   */
+  private detectEmfDimensions(): { width: number; height: number } | null {
+    if (!this.imageData || this.imageData.length < 40) return null;
+    try {
+      // rclFrame: left(24), top(28), right(32), bottom(36) in 0.01mm units
+      const left = this.imageData.readInt32LE(24);
+      const top = this.imageData.readInt32LE(28);
+      const right = this.imageData.readInt32LE(32);
+      const bottom = this.imageData.readInt32LE(36);
+      const widthMm = (right - left) / 100;
+      const heightMm = (bottom - top) / 100;
+      // Convert mm to pixels at 96 DPI (1 inch = 25.4mm)
+      const width = Math.round((widthMm / 25.4) * 96);
+      const height = Math.round((heightMm / 25.4) * 96);
+      if (width > 0 && height > 0) return { width, height };
+    } catch {
+      // EMF header parsing failed
+    }
+    return null;
+  }
+
+  /**
+   * Detects WMF dimensions from placeable WMF header bounding box (offsets 6-14)
+   */
+  private detectWmfDimensions(): { width: number; height: number } | null {
+    if (!this.imageData || this.imageData.length < 22) return null;
+    try {
+      // Placeable WMF header: left(6), top(8), right(10), bottom(12), inch(14)
+      const left = this.imageData.readInt16LE(6);
+      const top = this.imageData.readInt16LE(8);
+      const right = this.imageData.readInt16LE(10);
+      const bottom = this.imageData.readInt16LE(12);
+      const unitsPerInch = this.imageData.readUInt16LE(14);
+      if (unitsPerInch > 0) {
+        const width = Math.round(((right - left) / unitsPerInch) * 96);
+        const height = Math.round(((bottom - top) / unitsPerInch) * 96);
+        if (width > 0 && height > 0) return { width, height };
+      }
+    } catch {
+      // WMF header parsing failed
+    }
+    return null;
+  }
+
+  /**
+   * Gets the image data buffer asynchronously
+   */
+  async getImageDataAsync(): Promise<Buffer> {
+    await this.ensureDataLoaded();
+    if (!this.imageData) throw new Error('Failed to load image data');
+    return this.imageData;
+  }
+
+  /**
+   * Gets the image data buffer synchronously
+   */
+  getImageData(): Buffer {
+    if (!this.imageData) throw new Error('Image data not loaded. Call ensureDataLoaded first.');
+    return this.imageData;
+  }
+
+  getExtension(): string {
+    return this.extension;
+  }
+
+  getDPI(): number {
+    return this.dpi;
+  }
+
+  getWidth(): number {
+    return this.width;
+  }
+
+  getHeight(): number {
+    return this.height;
+  }
+
+  getImageDataSafe(): Buffer | null {
+    return this.imageData ?? null;
+  }
+
+  setWidth(width: number, maintainAspectRatio = true): this {
+    if (maintainAspectRatio && this.height > 0) {
+      const ratio = this.height / this.width;
+      this.height = Math.round(width * ratio);
+    }
+    this.width = width;
+    return this;
+  }
+
+  setHeight(height: number, maintainAspectRatio = true): this {
+    if (maintainAspectRatio && this.width > 0) {
+      const ratio = this.width / this.height;
+      this.width = Math.round(height * ratio);
+    }
+    this.height = height;
+    return this;
+  }
+
+  setSize(width: number, height: number): this {
+    this.width = width;
+    this.height = height;
+    return this;
+  }
+
+  async updateImageData(newSource: string | Buffer): Promise<void> {
+    this.source = newSource;
+    this.imageData = undefined;
+    await this.loadImageDataForDimensions();
+    this.extension = this.detectExtension();
+    this.dpi = this.detectDPI() || 96;
+  }
+
+  setRelationshipId(relationshipId: string): this {
+    this.relationshipId = relationshipId;
+    return this;
+  }
+
+  getRelationshipId(): string | undefined {
+    return this.relationshipId;
+  }
+
+  setDocPrId(id: number): this {
+    this.docPrId = id;
+    return this;
+  }
+
+  setAltText(altText: string): this {
+    this.description = altText;
+    return this;
+  }
+
+  getAltText(): string {
+    return this.description;
+  }
+
+  setTitle(title: string): this {
+    this.title = title;
+    return this;
+  }
+
+  getTitle(): string | undefined {
+    return this.title;
+  }
+
+  rotate(degrees: number): this {
+    this.rotation = ((degrees % 360) + 360) % 360;
+    if (this.rotation === 90 || this.rotation === 270) {
+      [this.width, this.height] = [this.height, this.width];
+    }
+    return this;
+  }
+
+  getRotation(): number {
+    return this.rotation;
+  }
+
+  setFlipH(flip: boolean): this {
+    this.flipH = flip;
+    return this;
+  }
+
+  getFlipH(): boolean {
+    return this.flipH;
+  }
+
+  setFlipV(flip: boolean): this {
+    this.flipV = flip;
+    return this;
+  }
+
+  getFlipV(): boolean {
+    return this.flipV;
+  }
+
+  // --- Group A: Simple attribute getters/setters ---
+
+  getPresetGeometry(): PresetGeometry {
+    return this.presetGeometry;
+  }
+  setPresetGeometry(geom: PresetGeometry): this {
+    this.presetGeometry = geom;
+    return this;
+  }
+
+  getCompressionState(): BlipCompressionState {
+    return this.compressionState;
+  }
+  setCompressionState(state: BlipCompressionState): this {
+    this.compressionState = state;
+    return this;
+  }
+
+  getBwMode(): string {
+    return this.bwMode;
+  }
+  setBwMode(mode: string): this {
+    this.bwMode = mode;
+    return this;
+  }
+
+  getInlineDistT(): number {
+    return this.inlineDistT;
+  }
+  getInlineDistB(): number {
+    return this.inlineDistB;
+  }
+  getInlineDistL(): number {
+    return this.inlineDistL;
+  }
+  getInlineDistR(): number {
+    return this.inlineDistR;
+  }
+  setInlineDist(distT: number, distB: number, distL: number, distR: number): this {
+    this.inlineDistT = distT;
+    this.inlineDistB = distB;
+    this.inlineDistL = distL;
+    this.inlineDistR = distR;
+    return this;
+  }
+
+  getNoChangeAspect(): boolean {
+    return this.noChangeAspect;
+  }
+  setNoChangeAspect(val: boolean): this {
+    this.noChangeAspect = val;
+    return this;
+  }
+
+  getHidden(): boolean {
+    return this.hidden;
+  }
+  setHidden(val: boolean): this {
+    this.hidden = val;
+    return this;
+  }
+
+  getBlipFillDpi(): number | undefined {
+    return this.blipFillDpi;
+  }
+  setBlipFillDpi(dpi: number | undefined): this {
+    this.blipFillDpi = dpi;
+    return this;
+  }
+
+  getBlipFillRotWithShape(): boolean | undefined {
+    return this.blipFillRotWithShape;
+  }
+  setBlipFillRotWithShape(val: boolean | undefined): this {
+    this.blipFillRotWithShape = val;
+    return this;
+  }
+
+  getPicLocks(): Partial<Record<PicLockAttribute, boolean>> {
+    return { ...this.picLocks };
+  }
+  setPicLocks(locks: Partial<Record<PicLockAttribute, boolean>>): this {
+    this.picLocks = locks;
+    return this;
+  }
+
+  getPicNonVisualProps(): PicNonVisualProperties {
+    return { ...this.picNonVisualProps };
+  }
+  setPicNonVisualProps(props: PicNonVisualProperties): this {
+    this.picNonVisualProps = props;
+    return this;
+  }
+
+  getIsLinked(): boolean {
+    return this.isLinked;
+  }
+  setIsLinked(val: boolean): this {
+    this.isLinked = val;
+    return this;
+  }
+
+  getSvgRelationshipId(): string | undefined {
+    return this.svgRelationshipId;
+  }
+  setSvgRelationshipId(id: string | undefined): this {
+    this.svgRelationshipId = id;
+    return this;
+  }
+
+  // --- Group B: Raw passthrough storage ---
+
+  /** @internal */
+  _setRawPassthrough(slot: string, xml: string): void {
+    this._rawPassthrough.set(slot, xml);
+  }
+
+  /** @internal */
+  _getRawPassthrough(slot: string): string | undefined {
+    return this._rawPassthrough.get(slot);
+  }
+
+  /** @internal */
+  _hasRawPassthrough(slot: string): boolean {
+    return this._rawPassthrough.has(slot);
+  }
+
+  // --- Group C: Enhanced border ---
+
+  getBorder(): ImageBorder | undefined {
+    return this.border;
+  }
+
+  setEffectExtent(left: number, top: number, right: number, bottom: number): this {
+    this.effectExtent = { left, top, right, bottom };
+    return this;
+  }
+
+  getEffectExtent(): EffectExtent | undefined {
+    return this.effectExtent;
+  }
+
+  setWrap(
+    type: WrapType,
+    side?: WrapSide,
+    distances?: { top?: number; bottom?: number; left?: number; right?: number }
+  ): this {
+    this.wrap = {
+      type,
+      side,
+      distanceTop: distances?.top,
+      distanceBottom: distances?.bottom,
+      distanceLeft: distances?.left,
+      distanceRight: distances?.right,
+    };
+    return this;
+  }
+
+  getWrap(): TextWrapSettings | undefined {
+    return this.wrap;
+  }
+
+  /**
+   * Validates a position offset value
+   * @param offset - Offset value in EMUs
+   * @param axis - 'horizontal' or 'vertical' for error messages
+   * @throws {Error} If offset exceeds maximum reasonable value
+   * @private
+   */
+  private validatePositionOffset(offset: number | undefined, axis: string): void {
+    if (offset === undefined) return;
+
+    // Maximum reasonable offset: 50 inches = 45,720,000 EMUs
+    const MAX_OFFSET_EMUS = 45720000;
+    if (Math.abs(offset) > MAX_OFFSET_EMUS) {
+      throw new Error(
+        `Invalid ${axis} position offset: ${offset} EMUs exceeds maximum of ${MAX_OFFSET_EMUS} EMUs (50 inches).`
+      );
+    }
+  }
+
+  /**
+   * Sets the position for a floating image
+   *
+   * Position can be specified using either:
+   * - Absolute offset (in EMUs from the anchor point)
+   * - Relative alignment (left, center, right / top, center, bottom)
+   *
+   * @param horizontal - Horizontal positioning configuration
+   * @param vertical - Vertical positioning configuration
+   * @returns This image for chaining
+   * @throws {Error} If offset values exceed maximum
+   *
+   * @example
+   * ```typescript
+   * // Absolute positioning (100,000 EMUs from page edges)
+   * image.setPosition(
+   *   { anchor: 'page', offset: 100000 },
+   *   { anchor: 'page', offset: 100000 }
+   * );
+   *
+   * // Relative alignment (centered on page)
+   * image.setPosition(
+   *   { anchor: 'page', alignment: 'center' },
+   *   { anchor: 'page', alignment: 'center' }
+   * );
+   * ```
+   */
+  setPosition(horizontal: ImagePosition['horizontal'], vertical: ImagePosition['vertical']): this {
+    // Validate offset values
+    this.validatePositionOffset(horizontal.offset, 'horizontal');
+    this.validatePositionOffset(vertical.offset, 'vertical');
+
+    this.position = { horizontal, vertical };
+    return this;
+  }
+
+  getPosition(): ImagePosition | undefined {
+    return this.position;
+  }
+
+  /**
+   * Validates the current image position configuration
+   *
+   * Checks for common configuration issues:
+   * - Missing anchor when offset is used
+   * - Conflicting offset and alignment values
+   * - Invalid combinations
+   *
+   * @returns Validation result with details
+   *
+   * @example
+   * ```typescript
+   * const result = image.validatePosition();
+   * if (!result.isValid) {
+   *   console.log(result.warnings); // Array of warning messages
+   * }
+   * ```
+   */
+  validatePosition(): {
+    isValid: boolean;
+    warnings: string[];
+  } {
+    const warnings: string[] = [];
+
+    if (!this.position) {
+      return { isValid: true, warnings };
+    }
+
+    // Check if both offset and alignment are specified (unusual but not invalid)
+    if (this.position.horizontal.offset !== undefined && this.position.horizontal.alignment) {
+      warnings.push(
+        'Horizontal position has both offset and alignment. Word will use alignment and ignore offset.'
+      );
+    }
+
+    if (this.position.vertical.offset !== undefined && this.position.vertical.alignment) {
+      warnings.push(
+        'Vertical position has both offset and alignment. Word will use alignment and ignore offset.'
+      );
+    }
+
+    // Check for floating image without anchor settings
+    if (this.position && !this.anchor) {
+      warnings.push(
+        'Position is set but anchor is not. Consider setting anchor properties for proper floating behavior.'
+      );
+    }
+
+    return {
+      isValid: warnings.length === 0,
+      warnings,
+    };
+  }
+
+  setAnchor(options: ImageAnchor): this {
+    this.anchor = options;
+    return this;
+  }
+
+  getAnchor(): ImageAnchor | undefined {
+    return this.anchor;
+  }
+
+  setCrop(left: number, top: number, right: number, bottom: number): this {
+    const clamp = (val: number) => Math.max(0, Math.min(100, val));
+    this.crop = { left: clamp(left), top: clamp(top), right: clamp(right), bottom: clamp(bottom) };
+    return this;
+  }
+
+  getCrop(): ImageCrop | undefined {
+    return this.crop;
+  }
+
+  setEffects(options: ImageEffects): this {
+    const clamp = (val?: number) =>
+      val !== undefined ? Math.max(-100, Math.min(100, val)) : undefined;
+    this.effects = {
+      brightness: clamp(options.brightness),
+      contrast: clamp(options.contrast),
+      grayscale: options.grayscale,
+      transparency:
+        options.transparency !== undefined
+          ? Math.max(0, Math.min(100, options.transparency))
+          : undefined,
+    };
+    return this;
+  }
+
+  getEffects(): ImageEffects | undefined {
+    return this.effects;
+  }
+
+  private detectDPI(): number | undefined {
+    if (!this.imageData) return undefined;
+
+    try {
+      if (this.extension === 'png') {
+        const physIndex = this.imageData.indexOf(Buffer.from([0x70, 0x48, 0x59, 0x73]));
+        if (physIndex !== -1 && physIndex + 12 < this.imageData.length) {
+          const xPixelsPerMeter = this.imageData.readUInt32BE(physIndex + 4);
+          const yPixelsPerMeter = this.imageData.readUInt32BE(physIndex + 8);
+          const unit = this.imageData[physIndex + 12];
+          if (unit === 1) {
+            const dpiX = Math.round(xPixelsPerMeter * 0.0254);
+            const dpiY = Math.round(yPixelsPerMeter * 0.0254);
+            return Math.min(dpiX, dpiY);
+          }
+        }
+      } else if (this.extension === 'jpg' || this.extension === 'jpeg') {
+        let offset = 2;
+        while (offset < this.imageData.length) {
+          if (this.imageData[offset] !== 0xff) break;
+          const marker = this.imageData[offset + 1];
+          if (marker === 0xe0) {
+            const length = this.imageData.readUInt16BE(offset + 2);
+            if (
+              length >= 16 &&
+              this.imageData.slice(offset + 4, offset + 9).toString('ascii') === 'JFIF\0'
+            ) {
+              const units = this.imageData[offset + 11];
+              const xDensity = this.imageData.readUInt16BE(offset + 12);
+              const yDensity = this.imageData.readUInt16BE(offset + 14);
+              if (units === 1) return Math.min(xDensity, yDensity);
+              if (units === 2)
+                return Math.min(Math.round(xDensity * 2.54), Math.round(yDensity * 2.54));
+            }
+            offset += 2 + length;
+            continue;
+          }
+          offset += 2 + this.imageData.readUInt16BE(offset + 2);
+        }
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error);
+      defaultLogger.warn(`DPI detection failed: ${message}`);
+    }
+    return undefined;
+  }
+
+  isFloating(): boolean {
+    return !!this.anchor || !!this.position;
+  }
+
+  floatTopLeft(marginTop = 0, marginLeft = 0): this {
+    this.setPosition({ anchor: 'page', offset: marginLeft }, { anchor: 'page', offset: marginTop });
+    this.setAnchor({
+      behindDoc: false,
+      locked: false,
+      layoutInCell: true,
+      allowOverlap: true,
+      relativeHeight: 251658240,
+    });
+    this.setWrap('square', 'bothSides');
+    return this;
+  }
+
+  floatTopRight(marginTop = 0, marginRight = 0): this {
+    this.setPosition(
+      { anchor: 'page', alignment: 'right', offset: -marginRight },
+      { anchor: 'page', offset: marginTop }
+    );
+    this.setAnchor({
+      behindDoc: false,
+      locked: false,
+      layoutInCell: true,
+      allowOverlap: true,
+      relativeHeight: 251658240,
+    });
+    this.setWrap('square', 'bothSides');
+    return this;
+  }
+
+  floatCenter(): this {
+    this.setPosition(
+      { anchor: 'page', alignment: 'center' },
+      { anchor: 'page', alignment: 'center' }
+    );
+    this.setAnchor({
+      behindDoc: false,
+      locked: false,
+      layoutInCell: true,
+      allowOverlap: true,
+      relativeHeight: 251658240,
+    });
+    this.setWrap('square', 'bothSides');
+    return this;
+  }
+
+  setBehindText(behind = true): this {
+    if (this.anchor) {
+      this.anchor.behindDoc = behind;
+    } else {
+      this.setAnchor({
+        behindDoc: behind,
+        locked: false,
+        layoutInCell: true,
+        allowOverlap: true,
+        relativeHeight: 251658240,
+      });
+    }
+    return this;
+  }
+
+  /**
+   * Applies a border around the image
+   * @param thicknessOrOptions Border thickness in points (number) or full ImageBorder options
+   * @returns This image for chaining
+   *
+   * Note: effectExtent is set to accommodate the border width so it renders
+   * properly without being clipped. The border is drawn centered on the image
+   * edge, so half the border width extends outside the image bounds.
+   */
+  setBorder(thicknessOrOptions: number | ImageBorder = 2): this {
+    if (typeof thicknessOrOptions === 'number') {
+      this.border = { width: thicknessOrOptions };
+    } else {
+      this.border = thicknessOrOptions;
+    }
+
+    // Calculate space needed for border (half-width on each side)
+    // Border is drawn centered on the edge
+    const borderEmu = this.border.width * UNITS.EMUS_PER_POINT;
+    const halfBorderEmu = Math.ceil(borderEmu / 2);
+
+    // Ensure effectExtent has at least enough space for the border
+    if (!this.effectExtent) {
+      this.effectExtent = { left: 0, top: 0, right: 0, bottom: 0 };
+    }
+    this.effectExtent.left = Math.max(this.effectExtent.left, halfBorderEmu);
+    this.effectExtent.top = Math.max(this.effectExtent.top, halfBorderEmu);
+    this.effectExtent.right = Math.max(this.effectExtent.right, halfBorderEmu);
+    this.effectExtent.bottom = Math.max(this.effectExtent.bottom, halfBorderEmu);
+
+    return this;
+  }
+
+  /**
+   * Removes the border from the image
+   * @returns This image for chaining
+   */
+  removeBorder(): this {
+    this.border = undefined;
+    return this;
+  }
+
+  /**
+   * @deprecated Use setBorder() instead. This method will be removed in a future version.
+   * Applies a 2-point black border around the image.
+   * @returns This image for chaining
+   */
+  applyTwoPixelBlackBorder(): this {
+    return this.setBorder(2);
+  }
+
+  toXML(): XMLElement {
+    const isFloating = this.isFloating();
+
+    // Common elements - must include wp: namespace prefix
+    const extent = XMLBuilder.wp('extent', {
+      cx: this.width.toString(),
+      cy: this.height.toString(),
+    });
+
+    // --- Build blip element with effects ---
+    const blipChildren: XMLElement[] = [];
+
+    // Add luminance effect for brightness/contrast (per ECMA-376 §20.1.8.43)
+    if (this.effects?.brightness !== undefined || this.effects?.contrast !== undefined) {
+      const lumAttrs: Record<string, string> = {};
+      if (this.effects.brightness !== undefined) {
+        lumAttrs.bright = Math.round(this.effects.brightness * 1000).toString();
+      }
+      if (this.effects.contrast !== undefined) {
+        lumAttrs.contrast = Math.round(this.effects.contrast * 1000).toString();
+      }
+      blipChildren.push(XMLBuilder.aSelf('lum', lumAttrs));
+    }
+
+    // Add grayscale effect (per ECMA-376 §20.1.8.37)
+    if (this.effects?.grayscale) {
+      blipChildren.push(XMLBuilder.aSelf('grayscl'));
+    }
+
+    // Add transparency effect via a:alphaModFix (ECMA-376 §20.1.8.4)
+    if (this.effects?.transparency !== undefined && this.effects.transparency > 0) {
+      // transparency is 0-100%, alphaModFix amt is in 1/1000ths of percent
+      // e.g., 50% transparency = 50000 amt (= 50% opacity)
+      const amt = Math.round((100 - this.effects.transparency) * 1000);
+      blipChildren.push(XMLBuilder.aSelf('alphaModFix', { amt: amt.toString() }));
+    }
+
+    // Group B: Inject raw blip effects passthrough (a:clrChange, a:duotone, etc.)
+    if (this._rawPassthrough.has('blip-effects')) {
+      blipChildren.push({
+        name: '__rawXml',
+        rawXml: this._rawPassthrough.get('blip-effects')!,
+      } as XMLElement);
+    }
+
+    // Group B: Inject raw blip extLst passthrough (must come last per schema)
+    if (this._rawPassthrough.has('blip-extLst')) {
+      blipChildren.push({
+        name: '__rawXml',
+        rawXml: this._rawPassthrough.get('blip-extLst')!,
+      } as XMLElement);
+    } else if (this.svgRelationshipId) {
+      // SVG dual-relationship: add asvg:svgBlip reference in extLst
+      blipChildren.push({
+        name: '__rawXml',
+        rawXml: `<a:extLst><a:ext uri="{96DAC541-7B7A-43D3-8B79-37D633B846F1}"><asvg:svgBlip xmlns:asvg="http://schemas.microsoft.com/office/drawing/2016/SVG/main" r:embed="${this.svgRelationshipId}"/></a:ext></a:extLst>`,
+      } as XMLElement);
+    }
+
+    // Build blip attributes: r:embed or r:link, cstate
+    const blipAttrs: Record<string, string | undefined> = {
+      cstate: this.compressionState,
+    };
+    if (this.isLinked) {
+      blipAttrs['r:link'] = this.relationshipId;
+    } else {
+      blipAttrs['r:embed'] = this.relationshipId;
+    }
+
+    const blip =
+      blipChildren.length > 0
+        ? XMLBuilder.a('blip', blipAttrs, blipChildren)
+        : XMLBuilder.a('blip', blipAttrs);
+
+    // --- Build transform (a:xfrm) ---
+    const xfrmAttrs: Record<string, string> | undefined = (() => {
+      const attrs: Record<string, string> = {};
+      if (this.rotation > 0) attrs.rot = Math.round(this.rotation * 60000).toString();
+      if (this.flipH) attrs.flipH = '1';
+      if (this.flipV) attrs.flipV = '1';
+      return Object.keys(attrs).length > 0 ? attrs : undefined;
+    })();
+    const xfrm = XMLBuilder.a('xfrm', xfrmAttrs, [
+      XMLBuilder.a('off', { x: '0', y: '0' }),
+      XMLBuilder.a('ext', { cx: this.width.toString(), cy: this.height.toString() }),
+    ]);
+
+    // --- Build shape properties (pic:spPr) ---
+    const spPrChildren: XMLElement[] = [xfrm];
+
+    // Geometry: use passthrough for custGeom or prstGeom with avLst, otherwise default
+    if (this._rawPassthrough.has('geometry')) {
+      spPrChildren.push({
+        name: '__rawXml',
+        rawXml: this._rawPassthrough.get('geometry')!,
+      } as XMLElement);
+    } else {
+      spPrChildren.push(
+        XMLBuilder.a('prstGeom', { prst: this.presetGeometry }, [XMLBuilder.a('avLst')])
+      );
+    }
+
+    // Border (a:ln) - full model (Group C)
+    if (this.border) {
+      // Add noFill element before the border line (required by Word)
+      spPrChildren.push(XMLBuilder.a('noFill'));
+
+      const ptToEmu = 12700;
+      const widthEmu = this.border.width * ptToEmu;
+      const lnAttrs: Record<string, string> = { w: widthEmu.toString() };
+      if (this.border.cap) lnAttrs.cap = this.border.cap;
+      if (this.border.compound) lnAttrs.cmpd = this.border.compound;
+      if (this.border.alignment) lnAttrs.algn = this.border.alignment;
+
+      const lnChildren: XMLElement[] = [];
+
+      // Fill
+      if (this.border.rawFillXml) {
+        lnChildren.push({ name: '__rawXml', rawXml: this.border.rawFillXml } as XMLElement);
+      } else if (this.border.fill) {
+        const colorChildren: XMLElement[] = [];
+        if (this.border.fill.modifiers) {
+          for (const mod of this.border.fill.modifiers) {
+            colorChildren.push(XMLBuilder.aSelf(mod.name, { val: mod.val }));
+          }
+        }
+        const colorEl =
+          colorChildren.length > 0
+            ? XMLBuilder.a(this.border.fill.type, { val: this.border.fill.value }, colorChildren)
+            : XMLBuilder.a(this.border.fill.type, { val: this.border.fill.value });
+        lnChildren.push(XMLBuilder.a('solidFill', undefined, [colorEl]));
+      } else {
+        // Default: scheme color tx1 (backward compat)
+        lnChildren.push(
+          XMLBuilder.a('solidFill', undefined, [XMLBuilder.a('schemeClr', { val: 'tx1' })])
+        );
+      }
+
+      // Dash pattern
+      if (this.border.dashPattern) {
+        lnChildren.push(XMLBuilder.aSelf('prstDash', { val: this.border.dashPattern }));
+      }
+
+      // Join
+      if (this.border.join === 'round') {
+        lnChildren.push(XMLBuilder.aSelf('round'));
+      } else if (this.border.join === 'bevel') {
+        lnChildren.push(XMLBuilder.aSelf('bevel'));
+      } else if (this.border.join === 'miter') {
+        const miterAttrs: Record<string, string> = {};
+        if (this.border.miterLimit) miterAttrs.lim = this.border.miterLimit.toString();
+        lnChildren.push(XMLBuilder.aSelf('miter', miterAttrs));
+      }
+
+      // Head/tail end
+      if (this.border.headEnd) {
+        lnChildren.push(XMLBuilder.aSelf('headEnd', this.border.headEnd as Record<string, string>));
+      }
+      if (this.border.tailEnd) {
+        lnChildren.push(XMLBuilder.aSelf('tailEnd', this.border.tailEnd as Record<string, string>));
+      }
+
+      spPrChildren.push(XMLBuilder.a('ln', lnAttrs, lnChildren));
+    }
+
+    // Group B: Inject raw spPr effects passthrough (effectLst, scene3d, sp3d, etc.)
+    if (this._rawPassthrough.has('spPr-effects')) {
+      spPrChildren.push({
+        name: '__rawXml',
+        rawXml: this._rawPassthrough.get('spPr-effects')!,
+      } as XMLElement);
+    }
+
+    // --- Build pic:cNvPr with passthrough ---
+    const cNvPrChildren: XMLElement[] = [];
+    if (this._rawPassthrough.has('cNvPr-extra')) {
+      cNvPrChildren.push({
+        name: '__rawXml',
+        rawXml: this._rawPassthrough.get('cNvPr-extra')!,
+      } as XMLElement);
+    }
+    const cNvPr =
+      cNvPrChildren.length > 0
+        ? XMLBuilder.pic(
+            'cNvPr',
+            {
+              id: this.picNonVisualProps.id,
+              name: this.picNonVisualProps.name,
+              descr: this.picNonVisualProps.descr,
+            },
+            cNvPrChildren
+          )
+        : XMLBuilder.pic('cNvPr', {
+            id: this.picNonVisualProps.id,
+            name: this.picNonVisualProps.name,
+            descr: this.picNonVisualProps.descr,
+          });
+
+    // --- Build picLocks from map ---
+    const picLocksAttrs: Record<string, string> = {};
+    for (const [key, val] of Object.entries(this.picLocks)) {
+      if (val) picLocksAttrs[key] = '1';
+    }
+
+    // --- Build blipFill ---
+    const blipFillAttrs: Record<string, string> = {};
+    if (this.blipFillDpi !== undefined) blipFillAttrs.dpi = this.blipFillDpi.toString();
+    if (this.blipFillRotWithShape !== undefined)
+      blipFillAttrs.rotWithShape = this.blipFillRotWithShape ? '1' : '0';
+
+    const blipFillChildren: XMLElement[] = [blip];
+    // Crop values are stored as percentages (0-100), serialized as per-mille (0-100000)
+    if (this.crop) {
+      blipFillChildren.push(
+        XMLBuilder.a('srcRect', {
+          l: Math.round(this.crop.left * 1000).toString(),
+          t: Math.round(this.crop.top * 1000).toString(),
+          r: Math.round(this.crop.right * 1000).toString(),
+          b: Math.round(this.crop.bottom * 1000).toString(),
+        })
+      );
+    }
+    // Group B: Use tile passthrough instead of stretch when present
+    if (this._rawPassthrough.has('blipFill-extra')) {
+      blipFillChildren.push({
+        name: '__rawXml',
+        rawXml: this._rawPassthrough.get('blipFill-extra')!,
+      } as XMLElement);
+    } else {
+      blipFillChildren.push(XMLBuilder.a('stretch', undefined, [XMLBuilder.a('fillRect')]));
+    }
+
+    const blipFillAttrsObj = Object.keys(blipFillAttrs).length > 0 ? blipFillAttrs : undefined;
+
+    const graphicData = XMLBuilder.a(
+      'graphicData',
+      { uri: 'http://schemas.openxmlformats.org/drawingml/2006/picture' },
+      [
+        XMLBuilder.pic('pic', undefined, [
+          XMLBuilder.pic('nvPicPr', undefined, [
+            cNvPr,
+            XMLBuilder.pic('cNvPicPr', undefined, [
+              XMLBuilder.a(
+                'picLocks',
+                Object.keys(picLocksAttrs).length > 0 ? picLocksAttrs : undefined
+              ),
+            ]),
+          ]),
+          XMLBuilder.pic('blipFill', blipFillAttrsObj, blipFillChildren),
+          XMLBuilder.pic('spPr', { bwMode: this.bwMode }, spPrChildren),
+        ]),
+      ]
+    );
+
+    const graphic = XMLBuilder.a('graphic', undefined, [graphicData]);
+
+    // --- Build docPr element (shared between inline and floating) ---
+    const buildDocPr = (idVal: string | number): XMLElement => {
+      const attrs: Record<string, any> = { id: idVal, name: this.name, descr: this.description };
+      if (this.title) attrs.title = this.title;
+      if (this.hidden) attrs.hidden = '1';
+      const children: XMLElement[] = [];
+      if (this._rawPassthrough.has('docPr-extra')) {
+        children.push({
+          name: '__rawXml',
+          rawXml: this._rawPassthrough.get('docPr-extra')!,
+        } as XMLElement);
+      }
+      return children.length > 0
+        ? XMLBuilder.wp('docPr', attrs, children)
+        : XMLBuilder.wp('docPr', attrs);
+    };
+
+    // --- Build cNvGraphicFramePr element (shared between inline and floating) ---
+    const buildCNvGraphicFramePr = (): XMLElement => {
+      return XMLBuilder.wp('cNvGraphicFramePr', undefined, [
+        XMLBuilder.a('graphicFrameLocks', {
+          'xmlns:a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
+          noChangeAspect: this.noChangeAspect ? '1' : '0',
+        }),
+      ]);
+    };
+
+    if (isFloating) {
+      // Floating image (anchor)
+      const positionHChildren: XMLElement[] = [];
+      if (this.position?.horizontal.alignment) {
+        positionHChildren.push(
+          XMLBuilder.wp('align', undefined, [this.position.horizontal.alignment])
+        );
+      } else {
+        positionHChildren.push(
+          XMLBuilder.wp('posOffset', undefined, [
+            (this.position?.horizontal.offset || 0).toString(),
+          ])
+        );
+      }
+      const positionH = XMLBuilder.wp(
+        'positionH',
+        { relativeFrom: this.position?.horizontal.anchor || 'page' },
+        positionHChildren
+      );
+
+      const positionVChildren: XMLElement[] = [];
+      if (this.position?.vertical.alignment) {
+        positionVChildren.push(
+          XMLBuilder.wp('align', undefined, [this.position.vertical.alignment])
+        );
+      } else {
+        positionVChildren.push(
+          XMLBuilder.wp('posOffset', undefined, [(this.position?.vertical.offset || 0).toString()])
+        );
+      }
+      const positionV = XMLBuilder.wp(
+        'positionV',
+        { relativeFrom: this.position?.vertical.anchor || 'page' },
+        positionVChildren
+      );
+
+      // Effect extent for floating images (required by Word)
+      const floatEffectExt = this.effectExtent || { left: 0, top: 0, right: 0, bottom: 0 };
+      const effectExtentElement = XMLBuilder.wp('effectExtent', {
+        t: floatEffectExt.top.toString(),
+        r: floatEffectExt.right.toString(),
+        b: floatEffectExt.bottom.toString(),
+        l: floatEffectExt.left.toString(),
+      });
+
+      const anchorChildren: XMLElement[] = [positionH, positionV, extent, effectExtentElement];
+
+      // Wrap element (required by CT_Anchor per ECMA-376 — defaults to wrapNone)
+      if (this.wrap) {
+        const wrapAttrs: Record<string, any> = {};
+        if (this.wrap.distanceTop !== undefined) wrapAttrs.distT = this.wrap.distanceTop;
+        if (this.wrap.distanceBottom !== undefined) wrapAttrs.distB = this.wrap.distanceBottom;
+        if (this.wrap.distanceLeft !== undefined) wrapAttrs.distL = this.wrap.distanceLeft;
+        if (this.wrap.distanceRight !== undefined) wrapAttrs.distR = this.wrap.distanceRight;
+        if (this.wrap.side) wrapAttrs.wrapText = this.wrap.side;
+
+        let wrapElementName: string;
+        switch (this.wrap.type) {
+          case 'square':
+            wrapElementName = 'wrapSquare';
+            break;
+          case 'tight':
+            wrapElementName = 'wrapTight';
+            break;
+          case 'through':
+            wrapElementName = 'wrapThrough';
+            break;
+          case 'topAndBottom':
+            wrapElementName = 'wrapTopAndBottom';
+            break;
+          case 'none':
+            wrapElementName = 'wrapNone';
+            break;
+          default:
+            wrapElementName = 'wrapSquare';
+        }
+
+        // Group B: Include wrap polygon passthrough as children
+        const wrapChildren: XMLElement[] = [];
+        if (this._rawPassthrough.has('wrap-polygon')) {
+          wrapChildren.push({
+            name: '__rawXml',
+            rawXml: this._rawPassthrough.get('wrap-polygon')!,
+          } as XMLElement);
+        } else if (wrapElementName === 'wrapTight' || wrapElementName === 'wrapThrough') {
+          // CT_WrapTight/CT_WrapThrough require a wp:wrapPolygon child.
+          // Generate a default rectangular polygon covering the full image extents.
+          wrapChildren.push({
+            name: 'wp:wrapPolygon',
+            attributes: { edited: '0' },
+            children: [
+              { name: 'wp:start', attributes: { x: '0', y: '0' }, selfClosing: true },
+              { name: 'wp:lineTo', attributes: { x: '21600', y: '0' }, selfClosing: true },
+              { name: 'wp:lineTo', attributes: { x: '21600', y: '21600' }, selfClosing: true },
+              { name: 'wp:lineTo', attributes: { x: '0', y: '21600' }, selfClosing: true },
+              { name: 'wp:lineTo', attributes: { x: '0', y: '0' }, selfClosing: true },
+            ],
+          });
+        }
+
+        anchorChildren.push(
+          wrapChildren.length > 0
+            ? XMLBuilder.wp(wrapElementName, wrapAttrs, wrapChildren)
+            : XMLBuilder.wp(wrapElementName, wrapAttrs)
+        );
+      } else {
+        // Default: wrapNone (required choice element per CT_Anchor)
+        anchorChildren.push(XMLBuilder.wp('wrapNone', {}));
+      }
+
+      anchorChildren.push(buildDocPr(this.docPrId));
+      anchorChildren.push(buildCNvGraphicFramePr());
+      anchorChildren.push(graphic);
+
+      // Group B: Inject anchor extras (wp14:sizeRelH, wp14:sizeRelV)
+      if (this._rawPassthrough.has('anchor-extra')) {
+        anchorChildren.push({
+          name: '__rawXml',
+          rawXml: this._rawPassthrough.get('anchor-extra')!,
+        } as XMLElement);
+      }
+
+      // Build anchor attributes including simplePos and distance from text
+      const anchorAttrs: Record<string, any> = {
+        behindDoc: this.anchor?.behindDoc ? 1 : 0,
+        locked: this.anchor?.locked ? 1 : 0,
+        layoutInCell: this.anchor?.layoutInCell ? 1 : 0,
+        allowOverlap: this.anchor?.allowOverlap ? 1 : 0,
+        relativeHeight: this.anchor?.relativeHeight,
+        simplePos: this.anchor?.simplePos ? '1' : '0',
+        distT: (this.anchor?.distT ?? 0).toString(),
+        distB: (this.anchor?.distB ?? 0).toString(),
+        distL: (this.anchor?.distL ?? 0).toString(),
+        distR: (this.anchor?.distR ?? 0).toString(),
+      };
+      if (this.hidden) anchorAttrs.hidden = '1';
+
+      // Add wp:simplePos child element (required by ECMA-376 even when simplePos="0")
+      anchorChildren.unshift(XMLBuilder.wp('simplePos', { x: '0', y: '0' }));
+
+      return XMLBuilder.w('drawing', undefined, [
+        XMLBuilder.wp('anchor', anchorAttrs, anchorChildren),
+      ]);
+    } else {
+      // Inline image
+      const effectExt = this.effectExtent || { left: 0, top: 0, right: 0, bottom: 0 };
+
+      return XMLBuilder.w('drawing', undefined, [
+        XMLBuilder.wp(
+          'inline',
+          {
+            distT: this.inlineDistT.toString(),
+            distB: this.inlineDistB.toString(),
+            distL: this.inlineDistL.toString(),
+            distR: this.inlineDistR.toString(),
+          },
+          [
+            extent,
+            XMLBuilder.wp('effectExtent', {
+              t: effectExt.top.toString(),
+              r: effectExt.right.toString(),
+              b: effectExt.bottom.toString(),
+              l: effectExt.left.toString(),
+            }),
+            buildDocPr(this.docPrId.toString()),
+            buildCNvGraphicFramePr(),
+            graphic,
+          ]
+        ),
+      ]);
+    }
+  }
+}