docxmlater 10.0.2 → 10.0.3

package/src/elements/ImageManager.ts

@@ -0,0 +1,432 @@
+/**
+ * ImageManager - Manages images in a document
+ *
+ * Handles image tracking, unique filename generation, and coordination
+ * with the RelationshipManager for image relationships.
+ */
+
+import { Image } from './Image';
+import { defaultLogger } from '../utils/logger';
+
+/**
+ * Image file entry
+ */
+interface ImageEntry {
+  /** The Image object */
+  image: Image;
+  /** Filename in media folder (e.g., 'image1.png') */
+  filename: string;
+  /** Relationship ID */
+  relationshipId: string;
+  /** Document property ID (for DrawingML) */
+  docPrId: number;
+}
+
+/**
+ * Image manager options
+ */
+export interface ImageManagerOptions {
+  /** Maximum number of images allowed. Default: 1000 */
+  maxImageCount?: number;
+  /** Maximum total size of all images in MB. Default: 100 */
+  maxTotalImageSizeMB?: number;
+  /** Maximum size of a single image in MB. Default: 20 */
+  maxSingleImageSizeMB?: number;
+}
+
+/**
+ * Manages all images in a document
+ */
+export class ImageManager {
+  private images: Map<Image, ImageEntry>;
+  private imagesByRelId: Map<string, ImageEntry>; // Track by relationship ID (Issue #12 fix)
+  private nextImageNumber: number;
+  private nextDocPrId: number;
+  private maxImageCount: number;
+  private maxTotalImageSizeBytes: number;
+  private maxSingleImageSizeBytes: number;
+
+  /**
+   * Creates a new image manager
+   * @param options Image manager options
+   */
+  constructor(options: ImageManagerOptions = {}) {
+    this.images = new Map();
+    this.imagesByRelId = new Map(); // Issue #12 fix
+    this.nextImageNumber = 1;
+    this.nextDocPrId = 1;
+    // Increased from 20 to 1000 to support production documents with many images
+    this.maxImageCount = options.maxImageCount ?? 1000;
+    this.maxTotalImageSizeBytes = (options.maxTotalImageSizeMB ?? 100) * 1024 * 1024;
+    this.maxSingleImageSizeBytes = (options.maxSingleImageSizeMB ?? 20) * 1024 * 1024;
+  }
+
+  /**
+   * Registers an image with the manager
+   * @param image The image to register
+   * @param relationshipId The relationship ID for this image
+   * @param originalFilename Optional original filename from the source document.
+   *   When provided (during parsing), preserves the original filename to maintain
+   *   consistency with relationship targets. When not provided (adding new images),
+   *   generates a new sequential filename.
+   * @param partName Optional part name (e.g., 'header1.xml', 'footer1.xml') for
+   *   distinguishing relationship IDs from different document parts. Headers and footers
+   *   have their own .rels files, so rId1 in header1.xml is different from rId1 in document.xml.
+   * @returns The filename assigned to this image
+   * @throws {Error} If image limits are exceeded
+   *
+   * **Issue #12 Fix:** Reuses filename for images with same relationship ID
+   * to prevent duplicating files in media folder during save.
+   * However, each image occurrence gets its own entry to preserve dimensions
+   * (Word allows same image file displayed at different sizes via wp:extent).
+   */
+  registerImage(image: Image, relationshipId: string, originalFilename?: string, partName?: string): string {
+    // Check if already registered by object reference (exact same object)
+    const existing = this.images.get(image);
+    if (existing) {
+      return existing.filename;
+    }
+
+    // Issue #12 fix: Reuse FILENAME for same rId, but create separate entry
+    // This prevents duplicate files in media folder while preserving dimensions
+    // Use composite key with partName to distinguish headers/footers from document body
+    const relIdKey = partName ? `${partName}:${relationshipId}` : relationshipId;
+    const existingByRelId = this.imagesByRelId.get(relIdKey);
+
+    // Filename priority:
+    // 1. Existing filename for same rId (prevents duplicates)
+    // 2. Original filename from source document (preserves round-trip integrity)
+    // 3. Generate new sequential filename (for newly added images)
+    const filename = existingByRelId
+      ? existingByRelId.filename
+      : (originalFilename || `image${this.nextImageNumber++}.${image.getExtension()}`);
+
+    // Validate image count limit
+    if (this.images.size >= this.maxImageCount) {
+      throw new Error(
+        `Cannot add image: Maximum image count (${this.maxImageCount}) exceeded. ` +
+        `Consider:\n` +
+        `  - Reducing the number of images\n` +
+        `  - Increasing maxImageCount in DocumentOptions\n` +
+        `  - Splitting into multiple documents`
+      );
+    }
+
+    // Validate single image size (if data is loaded)
+    try {
+      const imageData = image.getImageData();
+      const imageSizeMB = imageData.length / (1024 * 1024);
+
+      if (imageData.length > this.maxSingleImageSizeBytes) {
+        throw new Error(
+          `Image size (${imageSizeMB.toFixed(1)}MB) exceeds maximum single image size ` +
+          `(${(this.maxSingleImageSizeBytes / (1024 * 1024)).toFixed(0)}MB). ` +
+          `Consider:\n` +
+          `  - Compressing the image\n` +
+          `  - Resizing to lower resolution\n` +
+          `  - Converting to a more efficient format (e.g., JPEG)\n` +
+          `  - Increasing maxSingleImageSizeMB in DocumentOptions`
+        );
+      }
+
+      // Validate total size after adding this image
+      const currentTotalSize = this.getTotalSize();
+      const newTotalSize = currentTotalSize + imageData.length;
+      const newTotalSizeMB = newTotalSize / (1024 * 1024);
+
+      if (newTotalSize > this.maxTotalImageSizeBytes) {
+        throw new Error(
+          `Total image size (${newTotalSizeMB.toFixed(1)}MB) would exceed maximum ` +
+          `(${(this.maxTotalImageSizeBytes / (1024 * 1024)).toFixed(0)}MB) after adding this image. ` +
+          `Consider:\n` +
+          `  - Compressing existing images\n` +
+          `  - Removing unnecessary images\n` +
+          `  - Increasing maxTotalImageSizeMB in DocumentOptions\n` +
+          `  - Splitting into multiple documents`
+        );
+      }
+    } catch (error: unknown) {
+      // Image data not loaded yet - validation will happen during save
+      // This is acceptable for lazy-loaded images
+      if (error instanceof Error && !error.message.includes('not loaded')) {
+        throw error; // Re-throw size limit errors
+      }
+    }
+
+    // Assign docPr ID
+    const docPrId = this.nextDocPrId++;
+    image.setDocPrId(docPrId);
+
+    // Set relationship ID
+    image.setRelationshipId(relationshipId);
+
+    // Store entry (each image occurrence gets its own entry)
+    const entry: ImageEntry = {
+      image,
+      filename,
+      relationshipId,
+      docPrId,
+    };
+
+    this.images.set(image, entry);
+
+    // Only store first image for each rId (used for filename reuse)
+    // Use composite key to distinguish headers/footers from document body
+    if (!existingByRelId) {
+      this.imagesByRelId.set(relIdKey, entry);
+    }
+
+    return filename;
+  }
+
+  /**
+   * Gets the filename for an image
+   * @param image The image
+   * @returns The filename, or undefined if not registered
+   */
+  getFilename(image: Image): string | undefined {
+    return this.images.get(image)?.filename;
+  }
+
+  /**
+   * Gets the relationship ID for an image
+   * @param image The image
+   * @returns The relationship ID, or undefined if not registered
+   */
+  getRelationshipId(image: Image): string | undefined {
+    return this.images.get(image)?.relationshipId;
+  }
+
+  /**
+   * Updates the filename for an image and all other entries sharing the same old filename.
+   * Used when image format changes (e.g., BMP → PNG) require a new filename.
+   * @param image The image whose filename to update
+   * @param newFilename The new filename
+   * @returns The old filename, or undefined if image not registered
+   */
+  updateEntryFilename(image: Image, newFilename: string): string | undefined {
+    const entry = this.images.get(image);
+    if (!entry) return undefined;
+    const oldFilename = entry.filename;
+    if (oldFilename === newFilename) return oldFilename;
+
+    // Update all entries sharing the old filename
+    for (const e of this.images.values()) {
+      if (e.filename === oldFilename) e.filename = newFilename;
+    }
+    for (const e of this.imagesByRelId.values()) {
+      if (e.filename === oldFilename) e.filename = newFilename;
+    }
+    return oldFilename;
+  }
+
+  /**
+   * Gets all registered images
+   * @returns Array of image entries
+   */
+  getAllImages(): ImageEntry[] {
+    return Array.from(this.images.values());
+  }
+
+  /**
+   * Gets the number of images
+   * @returns Number of registered images
+   */
+  getImageCount(): number {
+    return this.images.size;
+  }
+
+  /**
+   * Checks if an image is registered
+   * @param image The image
+   * @returns True if registered
+   */
+  hasImage(image: Image): boolean {
+    return this.images.has(image);
+  }
+
+  /**
+   * Gets the MIME type for an image extension
+   * @param extension File extension (without dot)
+   * @returns MIME type
+   */
+  static getMimeType(extension: string): string {
+    const mimeTypes: Record<string, string> = {
+      png: 'image/png',
+      jpg: 'image/jpeg',
+      jpeg: 'image/jpeg',
+      gif: 'image/gif',
+      bmp: 'image/bmp',
+      tiff: 'image/tiff',
+      tif: 'image/tiff',
+      svg: 'image/svg+xml',
+      emf: 'image/x-emf',
+      wmf: 'image/x-wmf',
+    };
+
+    return mimeTypes[extension.toLowerCase()] || 'image/png';
+  }
+
+  /**
+   * Loads data for all images with controlled concurrency
+   * Call this before saving to ensure all image data is available
+   * @param concurrency Maximum number of images to load simultaneously (default: 5)
+   * @param onProgress Optional callback for progress tracking (loaded, total)
+   */
+  async loadAllImageData(
+    concurrency = 5,
+    onProgress?: (loaded: number, total: number) => void
+  ): Promise<void> {
+    const images = Array.from(this.images.values());
+    const total = images.length;
+
+    if (total === 0) {
+      return;
+    }
+
+    // Validate concurrency
+    if (concurrency < 1 || concurrency > 50 || !Number.isInteger(concurrency)) {
+      throw new Error('Concurrency must be an integer between 1 and 50');
+    }
+
+    let loaded = 0;
+
+    // Load images in batches to control concurrency
+    for (let i = 0; i < total; i += concurrency) {
+      const batch = images.slice(i, Math.min(i + concurrency, total));
+
+      // Load batch in parallel
+      await Promise.all(
+        batch.map(async (entry) => {
+          try {
+            await entry.image.ensureDataLoaded();
+            loaded++;
+
+            // Report progress
+            if (onProgress) {
+              onProgress(loaded, total);
+            }
+          } catch (error: unknown) {
+            // Log error but continue loading other images
+            const message = error instanceof Error ? error.message : String(error);
+            defaultLogger.warn(
+              `Failed to load image data: ${message}`
+            );
+            loaded++; // Still count as processed
+
+            if (onProgress) {
+              onProgress(loaded, total);
+            }
+          }
+        })
+      );
+    }
+  }
+
+  /**
+   * Releases data for all images
+   * Call this after saving to free memory
+   */
+  releaseAllImageData(): void {
+    for (const entry of this.images.values()) {
+      entry.image.releaseData();
+    }
+  }
+
+  /**
+   * Gets the total size of all loaded image data
+   * Only counts images that are currently loaded in memory
+   * @returns Total size in bytes
+   */
+  getTotalSize(): number {
+    let totalSize = 0;
+    for (const entry of this.images.values()) {
+      try {
+        const data = entry.image.getImageData();
+        totalSize += data.length;
+      } catch (e) {
+        defaultLogger.debug(`[ImageManager] Image not loaded, skipping size count: ${entry.filename}`);
+      }
+    }
+    return totalSize;
+  }
+
+  /**
+   * Gets the total size of all images (loads them if needed)
+   * Use this for accurate size estimation before saving
+   * @returns Total size in bytes
+   */
+  async getTotalSizeAsync(): Promise<number> {
+    let totalSize = 0;
+    for (const entry of this.images.values()) {
+      try {
+        const data = await entry.image.getImageDataAsync();
+        totalSize += data.length;
+      } catch (e) {
+        defaultLogger.debug(`[ImageManager] Image loading failed, skipping: ${entry.filename}`);
+      }
+    }
+    return totalSize;
+  }
+
+  /**
+   * Gets statistics about images
+   * @returns Object with image statistics
+   */
+  getStats(): {
+    count: number;
+    totalSize: number;
+    averageSize: number;
+  } {
+    const count = this.getImageCount();
+    const totalSize = this.getTotalSize();
+    return {
+      count,
+      totalSize,
+      averageSize: count > 0 ? Math.round(totalSize / count) : 0,
+    };
+  }
+
+  /**
+   * Initializes nextImageNumber from already-loaded images
+   * Call after parsing to prevent filename collisions
+   * 
+   * **Issue #12 Fix:** Prevents collisions when adding new images after load
+   */
+  initializeFromLoadedImages(): void {
+    let maxNumber = 0;
+
+    for (const entry of this.images.values()) {
+      // Extract number from filename (e.g., "image5.png" → 5)
+      const match = /image(\d+)\./.exec(entry.filename); 
+      if (match?.[1]) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNumber) {
+          maxNumber = num;
+        }
+      }
+    }
+
+    // Start numbering after highest existing number
+    this.nextImageNumber = maxNumber + 1;
+  }
+
+  /**
+   * Clears all images
+   */
+  clear(): this {
+    this.images.clear();
+    this.imagesByRelId.clear(); // Issue #12 fix
+    this.nextImageNumber = 1;
+    this.nextDocPrId = 1;
+    return this;
+  }
+
+  /**
+   * Creates a new image manager
+   * @param options Image manager options
+   */
+  static create(options?: ImageManagerOptions): ImageManager {
+    return new ImageManager(options);
+  }
+}

package/src/elements/ImageRun.ts

@@ -0,0 +1,59 @@
+/**
+ * ImageRun - A run that contains an image (drawing)
+ * Extends Run class for type-safe paragraph content
+ *
+ * This is a specialized Run that contains a drawing instead of text.
+ * It generates proper w:r (run) XML with w:drawing child element.
+ */
+
+import { Run } from './Run';
+import { Image } from './Image';
+import { XMLElement } from '../xml/XMLBuilder';
+
+/**
+ * ImageRun - A run containing an embedded image
+ *
+ * In WordprocessingML, images are embedded in runs as drawing elements:
+ * <w:r>
+ *   <w:drawing>
+ *     <wp:inline>
+ *       ... image data ...
+ *     </wp:inline>
+ *   </w:drawing>
+ * </w:r>
+ */
+export class ImageRun extends Run {
+  private imageElement: Image;
+
+  /**
+   * Creates a new image run
+   * @param image The image to embed in this run
+   */
+  constructor(image: Image) {
+    // Call parent constructor with empty text
+    // The text is irrelevant for image runs
+    super('');
+    this.imageElement = image;
+  }
+
+  /**
+   * Gets the image element
+   * @returns Image instance
+   */
+  getImageElement(): Image {
+    return this.imageElement;
+  }
+
+  /**
+   * Override toXML to generate image-specific XML
+   * Generates a w:r element containing w:drawing instead of w:t
+   * @returns XMLElement with w:r containing w:drawing
+   */
+  toXML(): XMLElement {
+    const drawing = this.imageElement.toXML();
+    return {
+      name: 'w:r',
+      children: [drawing]
+    };
+  }
+}

package/src/elements/MathElement.ts

@@ -0,0 +1,65 @@
+/**
+ * MathElement - Represents math elements (m:oMathPara and m:oMath)
+ *
+ * Per ECMA-376 Part 1 §22.1, math paragraphs (m:oMathPara) are block-level
+ * and inline math expressions (m:oMath) can appear within paragraphs.
+ *
+ * Stored as raw XML for round-trip fidelity since math content has complex
+ * internal structure (fractions, radicals, matrices, etc.).
+ */
+
+import { XMLElement } from '../xml/XMLBuilder';
+
+/**
+ * Block-level math paragraph (m:oMathPara)
+ * Can appear directly in the document body alongside paragraphs and tables.
+ */
+export class MathParagraph {
+  private rawXml: string;
+
+  constructor(rawXml: string) {
+    this.rawXml = rawXml;
+  }
+
+  toXML(): XMLElement {
+    return {
+      name: '__rawXml',
+      rawXml: this.rawXml,
+    } as XMLElement;
+  }
+
+  getRawXml(): string {
+    return this.rawXml;
+  }
+
+  getType(): string {
+    return 'mathParagraph';
+  }
+}
+
+/**
+ * Inline math expression (m:oMath)
+ * Can appear within paragraphs alongside runs.
+ */
+export class MathExpression {
+  private rawXml: string;
+
+  constructor(rawXml: string) {
+    this.rawXml = rawXml;
+  }
+
+  toXML(): XMLElement {
+    return {
+      name: '__rawXml',
+      rawXml: this.rawXml,
+    } as XMLElement;
+  }
+
+  getRawXml(): string {
+    return this.rawXml;
+  }
+
+  getType(): string {
+    return 'mathExpression';
+  }
+}