feat: Add OBZ to Grid3 conversion with embedded images

- Add extractImageAsBuffer() method to OBZ processor
- Store raw image Buffers in button.parameters.imageData
- Keep data URLs in button.image for board viewer display
- Add data URL → Buffer conversion in Grid3 saveFromTree()
- Handle both Buffer and data URL formats when saving Grid3 files
- Extract MIME type from data URL for proper file extension

This enables full round-trip conversion:
OBZ → AACTree → Grid3 (with embedded images preserved)

Images are now stored in dual format:
- button.image: data URL (for display)
- button.parameters.imageData: Buffer (for Grid3 export)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: willwade

src/processors/gridsetProcessor.ts

@@ -75,6 +75,21 @@ class GridsetProcessor extends BaseProcessor {
   // Helper function to ensure color has alpha channel (Grid3 format)
   private ensureAlphaChannel(color: string | undefined): string {
     if (!color) return '#FFFFFFFF';
+
+    // Handle rgb() and rgba() formats
+    const rgbMatch = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/);
+    if (rgbMatch) {
+      const r = parseInt(rgbMatch[1]);
+      const g = parseInt(rgbMatch[2]);
+      const b = parseInt(rgbMatch[3]);
+      const a = rgbMatch[4] !== undefined ? parseFloat(rgbMatch[4]) : 1.0;
+      const alphaHex = Math.round(a * 255)
+        .toString(16)
+        .toUpperCase()
+        .padStart(2, '0');
+      return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}${alphaHex}`;
+    }
+
     // If already 8 digits (with alpha), return as is
     if (color.match(/^#[0-9A-Fa-f]{8}$/)) return color;
     // If 6 digits (no alpha), add FF for fully opaque
@@ -90,6 +105,42 @@ class GridsetProcessor extends BaseProcessor {
     return '#FFFFFFFF';
   }
 
+  /**
+   * Calculate appropriate font color (black or white) based on background brightness
+   * Uses WCAG relative luminance formula to determine contrast
+   */
+  private getContrastFontColor(backgroundColor: string | undefined): string {
+    if (!backgroundColor) return '#FF000000FF'; // Default to black
+
+    // Parse color from various formats
+    let r = 255,
+      g = 255,
+      b = 255;
+
+    // Handle hex colors
+    const hexMatch = backgroundColor.match(/#?([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})/);
+    if (hexMatch) {
+      r = parseInt(hexMatch[1], 16);
+      g = parseInt(hexMatch[2], 16);
+      b = parseInt(hexMatch[3], 16);
+    } else {
+      // Handle rgb() format
+      const rgbMatch = backgroundColor.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+      if (rgbMatch) {
+        r = parseInt(rgbMatch[1]);
+        g = parseInt(rgbMatch[2]);
+        b = parseInt(rgbMatch[3]);
+      }
+    }
+
+    // Calculate relative luminance using WCAG formula
+    const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+
+    // Use white text for dark backgrounds (luminance < 0.5), black for light backgrounds
+    // Return 6-digit hex (ensureAlphaChannel will add FF for alpha)
+    return luminance < 0.5 ? '#FFFFFF' : '#000000';
+  }
+
   /**
    * Extract words from Grid3 WordList structure
    */
@@ -1798,7 +1849,10 @@ class GridsetProcessor extends BaseProcessor {
           // For "None" surround, just use BackColour for the fill (no TileColour)
           BackColour: this.ensureAlphaChannel(style.backgroundColor),
           BorderColour: this.ensureAlphaChannel(style.borderColor),
-          FontColour: this.ensureAlphaChannel(style.fontColor),
+          // Calculate font color based on background if not explicitly set
+          FontColour: this.ensureAlphaChannel(
+            style.fontColor || this.getContrastFontColor(style.backgroundColor)
+          ),
           FontName: style.fontFamily || 'Arial',
           FontSize: style.fontSize?.toString() || '16',
         };
@@ -1867,30 +1921,58 @@ class GridsetProcessor extends BaseProcessor {
                           imageExt = imageMatch[1].toLowerCase();
                         }
 
-                        // Grid3 dynamically constructs image filenames by prepending cell coordinates
-                        // The XML should only contain the suffix: -0-text-0.{ext}
-                        // Grid3 automatically adds the X-Y prefix based on the Cell's position
-                        captionAndImage.Image = `-0-text-0.${imageExt}`;
-
                         // Extract image data from button parameters if available
                         // (AstericsGridProcessor stores it there during loadIntoTree)
+                        // Also handle data URLs from OBZ conversion
                         let imageData = Buffer.alloc(0);
+                        let hasImageData = false;
+
                         if (
                           button.parameters &&
                           button.parameters.imageData &&
                           Buffer.isBuffer(button.parameters.imageData)
                         ) {
                           imageData = button.parameters.imageData as any;
+                          hasImageData = imageData.length > 0;
+                        } else if (
+                          button.image &&
+                          typeof button.image === 'string' &&
+                          button.image.startsWith('data:image')
+                        ) {
+                          // Convert data URL to Buffer (for OBZ → Grid3 conversion)
+                          try {
+                            const matches = button.image.match(/^data:image\/(\w+);base64,(.+)$/);
+                            if (matches) {
+                              const extension = matches[1]; // e.g., 'png', 'jpeg', 'gif'
+                              const base64Data = matches[2];
+                              imageData = Buffer.from(base64Data, 'base64');
+                              imageExt = extension; // Override the detected extension
+                              hasImageData = imageData.length > 0;
+                            }
+                          } catch (err) {
+                            console.warn(
+                              `[Grid3] Failed to convert data URL to Buffer for button ${button.id}:`,
+                              err
+                            );
+                          }
                         }
 
-                        // Store image data for later writing to ZIP
-                        buttonImages.set(button.id, {
-                          imageData: imageData,
-                          ext: imageExt,
-                          pageName: page.name || page.id,
-                          x: position.x,
-                          y: position.y + yOffset,
-                        });
+                        // Only add image reference if we have actual image data
+                        if (hasImageData) {
+                          // Grid3 dynamically constructs image filenames by prepending cell coordinates
+                          // The XML should only contain the suffix: -0-text-0.{ext}
+                          // Grid3 automatically adds the X-Y prefix based on the Cell's position
+                          captionAndImage.Image = `-0-text-0.${imageExt}`;
+
+                          // Store image data for later writing to ZIP
+                          buttonImages.set(button.id, {
+                            imageData: imageData,
+                            ext: imageExt,
+                            pageName: page.name || page.id,
+                            x: position.x,
+                            y: position.y + yOffset,
+                          });
+                        }
                       }
 
                       const cellData: Record<string, unknown> = {
@@ -1927,9 +2009,11 @@ class GridsetProcessor extends BaseProcessor {
                         if (button.style?.borderColor) {
                           styleObj.BorderColour = this.ensureAlphaChannel(button.style.borderColor);
                         }
-                        if (button.style?.fontColor) {
-                          styleObj.FontColour = this.ensureAlphaChannel(button.style.fontColor);
-                        }
+                        // Always add font color inline - either from button style or calculated from background
+                        const fontColor =
+                          button.style?.fontColor ||
+                          this.getContrastFontColor(button.style?.backgroundColor);
+                        styleObj.FontColour = this.ensureAlphaChannel(fontColor);
                         if (button.style?.fontFamily) {
                           styleObj.FontName = button.style.fontFamily;
                         }

src/processors/obfProcessor.ts

@@ -82,6 +82,41 @@ class ObfProcessor extends BaseProcessor {
     super(options);
   }
 
+  /**
+   * Extract an image from the ZIP file as a Buffer
+   */
+  private extractImageAsBuffer(imageId: string, images: any[]): Buffer | null {
+    if (!this.zipFile || !images) {
+      return null;
+    }
+
+    // Find the image metadata
+    const imageData = images.find((img: any) => img.id === imageId);
+    if (!imageData) {
+      return null;
+    }
+
+    // Try to get the image file from the ZIP
+    const possiblePaths = [
+      imageData.path,
+      `images/${imageData.filename || imageId}`,
+      imageData.id,
+    ].filter(Boolean);
+
+    for (const imagePath of possiblePaths) {
+      try {
+        const entry = this.zipFile.getEntry(imagePath);
+        if (entry) {
+          return entry.getData(); // Return raw Buffer
+        }
+      } catch (err) {
+        continue;
+      }
+    }
+
+    return null;
+  }
+
   /**
    * Extract an image from the ZIP file and convert to data URL
    */
@@ -187,8 +222,16 @@ class ObfProcessor extends BaseProcessor {
 
       // Resolve image if image_id is present
       let resolvedImage: string | undefined;
+      let imageBuffer: Buffer | undefined;
       if (btn.image_id && boardData.images) {
         resolvedImage = this.extractImageAsDataUrl(btn.image_id, boardData.images) || undefined;
+        imageBuffer = this.extractImageAsBuffer(btn.image_id, boardData.images) || undefined;
+      }
+
+      // Build parameters object for Grid3 export compatibility
+      const buttonParameters: { imageData?: Buffer; [key: string]: any } = {};
+      if (imageBuffer) {
+        buttonParameters.imageData = imageBuffer;
       }
 
       return new AACButton({
@@ -203,6 +246,7 @@ class ObfProcessor extends BaseProcessor {
         },
         image: resolvedImage, // Set the resolved image data URL
         resolvedImageEntry: resolvedImage,
+        parameters: Object.keys(buttonParameters).length > 0 ? buttonParameters : undefined,
         semanticAction,
         targetPageId: btn.load_board?.path,
         semantic_id: btn.semantic_id, // Extract semantic_id if present