@willwade/aac-processors 0.0.27 → 0.0.29

package/dist/processors/gridsetProcessor.d.ts

@@ -12,6 +12,11 @@ declare class GridsetProcessor extends BaseProcessor {
     private decryptGridsetEntry;
     private getGridsetPassword;
     private ensureAlphaChannel;
+    /**
+     * Calculate appropriate font color (black or white) based on background brightness
+     * Uses WCAG relative luminance formula to determine contrast
+     */
+    private getContrastFontColor;
     /**
      * Extract words from Grid3 WordList structure
      */

package/dist/processors/gridsetProcessor.js

@@ -58,6 +58,19 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
     ensureAlphaChannel(color) {
         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;
@@ -74,6 +87,37 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         // Invalid or unknown format, return white
         return '#FFFFFFFF';
     }
+    /**
+     * Calculate appropriate font color (black or white) based on background brightness
+     * Uses WCAG relative luminance formula to determine contrast
+     */
+    getContrastFontColor(backgroundColor) {
+        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
      */
@@ -1628,7 +1672,8 @@ class GridsetProcessor extends baseProcessor_1.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',
                 };
@@ -1687,26 +1732,50 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                         if (imageMatch) {
                                             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;
+                                            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);
+                                            }
+                                        }
+                                        // 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,
+                                            });
                                         }
-                                        // 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 = {
                                         '@_X': position.x, // Grid3 uses 0-based X coordinates (defaults to 0 when omitted)
@@ -1736,9 +1805,10 @@ class GridsetProcessor extends baseProcessor_1.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;
                                         }

package/dist/processors/obfProcessor.d.ts

@@ -3,7 +3,18 @@ import { AACTree } from '../core/treeStructure';
 import { ValidationResult } from '../validation/validationTypes';
 import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 declare class ObfProcessor extends BaseProcessor {
+    private zipFile?;
+    private imageCache;
     constructor(options?: ProcessorOptions);
+    /**
+     * Extract an image from the ZIP file as a Buffer
+     */
+    private extractImageAsBuffer;
+    /**
+     * Extract an image from the ZIP file and convert to data URL
+     */
+    private extractImageAsDataUrl;
+    private getMimeTypeFromFilename;
     private processBoard;
     extractTexts(filePathOrBuffer: string | Buffer): string[];
     loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;

package/dist/processors/obfProcessor.js

@@ -26,6 +26,104 @@ function mapObfVisibility(hidden) {
 class ObfProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
+        this.imageCache = new Map(); // Cache for data URLs
+    }
+    /**
+     * Extract an image from the ZIP file as a Buffer
+     */
+    extractImageAsBuffer(imageId, images) {
+        if (!this.zipFile || !images) {
+            return null;
+        }
+        // Find the image metadata
+        const imageData = images.find((img) => 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
+     */
+    extractImageAsDataUrl(imageId, images) {
+        // Check cache first
+        if (this.imageCache.has(imageId)) {
+            return this.imageCache.get(imageId) ?? null;
+        }
+        if (!this.zipFile || !images) {
+            return null;
+        }
+        // Find the image metadata
+        const imageData = images.find((img) => img.id === imageId);
+        if (!imageData) {
+            return null;
+        }
+        // Try to get the image file from the ZIP
+        // Images are typically stored in an 'images' folder or root
+        const possiblePaths = [
+            imageData.path, // Explicit path if provided
+            `images/${imageData.filename || imageId}`, // Standard images folder
+            imageData.id, // Just the ID
+        ].filter(Boolean);
+        for (const imagePath of possiblePaths) {
+            try {
+                const entry = this.zipFile.getEntry(imagePath);
+                if (entry) {
+                    const buffer = entry.getData();
+                    const contentType = imageData.content_type ||
+                        this.getMimeTypeFromFilename(imagePath);
+                    const dataUrl = `data:${contentType};base64,${buffer.toString('base64')}`;
+                    this.imageCache.set(imageId, dataUrl);
+                    return dataUrl;
+                }
+            }
+            catch (err) {
+                // Continue to next path
+                continue;
+            }
+        }
+        // If image has a URL, use that as fallback
+        if (imageData.url) {
+            const url = imageData.url;
+            this.imageCache.set(imageId, url);
+            return url;
+        }
+        return null;
+    }
+    getMimeTypeFromFilename(filename) {
+        const ext = filename.toLowerCase().split('.').pop();
+        switch (ext) {
+            case 'png':
+                return 'image/png';
+            case 'jpg':
+            case 'jpeg':
+                return 'image/jpeg';
+            case 'gif':
+                return 'image/gif';
+            case 'svg':
+                return 'image/svg+xml';
+            case 'webp':
+                return 'image/webp';
+            default:
+                return 'image/png';
+        }
     }
     processBoard(boardData, _boardPath) {
         const sourceButtons = boardData.buttons || [];
@@ -55,6 +153,22 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                         message: String(btn?.vocalization || btn?.label || ''),
                     },
                 };
+            // Resolve image if image_id is present
+            let resolvedImage;
+            let imageBuffer;
+            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 = {};
+            if (imageBuffer) {
+                buttonParameters.imageData = imageBuffer;
+            }
+            // Store image_id for web viewers to fetch images via API
+            if (btn.image_id) {
+                buttonParameters.image_id = btn.image_id;
+            }
             return new treeStructure_1.AACButton({
                 // Make button ID unique by combining page ID and button ID
                 id: `${pageId}::${btn?.id || ''}`,
@@ -65,6 +179,9 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                     backgroundColor: btn.background_color,
                     borderColor: btn.border_color,
                 },
+                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
@@ -271,6 +388,9 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
             console.error('[OBF] Error instantiating AdmZip with input:', err);
             throw err;
         }
+        // Store the ZIP file reference for image extraction
+        this.zipFile = zip;
+        this.imageCache.clear(); // Clear cache for new file
         console.log('[OBF] Detected zip archive, extracting .obf files');
         zip.getEntries().forEach((entry) => {
             if (entry.entryName.endsWith('.obf')) {

package/dist/utilities/analytics/metrics/core.d.ts

@@ -47,10 +47,13 @@ export declare class MetricsCalculator {
      * - Parent button's cumulative effort (to reach the button)
      * - + Effort to select the word form from its position in predictions grid
      *
+     * If a word exists as both a regular button and a word form, the version
+     * with lower effort is kept.
+     *
      * @param tree - The AAC tree
      * @param buttons - Already calculated button metrics
      * @param options - Metrics options
-     * @returns Array of word form button metrics
+     * @returns Object containing word form metrics and labels that were replaced
      */
     private calculateWordFormMetrics;
     /**

package/dist/utilities/analytics/metrics/core.js

@@ -83,11 +83,20 @@ class MetricsCalculator {
         });
         // Update buttons using dynamic spelling effort if applicable
         const buttons = Array.from(knownButtons.values()).sort((a, b) => a.effort - b.effort);
-        // Calculate metrics for word forms (smart grammar predictions)
-        const wordFormMetrics = this.calculateWordFormMetrics(tree, buttons, options);
-        buttons.push(...wordFormMetrics);
-        // Re-sort after adding word forms
-        buttons.sort((a, b) => a.effort - b.effort);
+        // Calculate metrics for word forms (smart grammar predictions) if enabled
+        // Default to true if not specified
+        const useSmartGrammar = options.useSmartGrammar !== false;
+        if (useSmartGrammar) {
+            const { wordFormMetrics, replacedLabels } = this.calculateWordFormMetrics(tree, buttons, options);
+            // Remove buttons that were replaced by lower-effort word forms
+            const filteredButtons = buttons.filter((btn) => !replacedLabels.has(btn.label.toLowerCase()));
+            // Add word forms and re-sort
+            filteredButtons.push(...wordFormMetrics);
+            filteredButtons.sort((a, b) => a.effort - b.effort);
+            // Replace the original buttons array
+            buttons.length = 0;
+            buttons.push(...filteredButtons);
+        }
         // Calculate grid dimensions
         const grid = this.calculateGridDimensions(tree);
         // Identify prediction metrics
@@ -573,14 +582,18 @@ class MetricsCalculator {
      * - Parent button's cumulative effort (to reach the button)
      * - + Effort to select the word form from its position in predictions grid
      *
+     * If a word exists as both a regular button and a word form, the version
+     * with lower effort is kept.
+     *
      * @param tree - The AAC tree
      * @param buttons - Already calculated button metrics
      * @param options - Metrics options
-     * @returns Array of word form button metrics
+     * @returns Object containing word form metrics and labels that were replaced
      */
     calculateWordFormMetrics(tree, buttons, _options = {}) {
         const wordFormMetrics = [];
-        // Track which buttons already exist to avoid duplicates
+        const replacedLabels = new Set();
+        // Track buttons by label to compare efforts
         const existingLabels = new Map();
         buttons.forEach((btn) => existingLabels.set(btn.label.toLowerCase(), btn));
         // Iterate through all pages to find buttons with predictions
@@ -596,10 +609,6 @@ class MetricsCalculator {
                     // Calculate effort for each word form
                     btn.predictions.forEach((wordForm, index) => {
                         const wordFormLower = wordForm.toLowerCase();
-                        // Skip if this word form already exists as a regular button
-                        if (existingLabels.has(wordFormLower)) {
-                            return;
-                        }
                         // Calculate effort based on position in predictions array
                         // Assume predictions are displayed in a grid layout (e.g., 2 columns)
                         const predictionsGridCols = 2; // Typical predictions layout
@@ -611,7 +620,17 @@ class MetricsCalculator {
                         const predictionSelectionEffort = (0, effort_1.visualScanEffort)(predictionPriorItems);
                         // Word form effort = parent button's cumulative effort + selection effort
                         const wordFormEffort = parentMetrics.effort + predictionSelectionEffort;
-                        // Mark as word form with a special ID pattern
+                        // Check if this word already exists as a regular button
+                        const existingBtn = existingLabels.get(wordFormLower);
+                        // If word exists and has lower or equal effort, skip the word form
+                        if (existingBtn && existingBtn.effort <= wordFormEffort) {
+                            return;
+                        }
+                        // If word exists but word form has lower effort, mark for replacement
+                        if (existingBtn && existingBtn.effort > wordFormEffort) {
+                            replacedLabels.add(wordFormLower);
+                        }
+                        // Create word form metric
                         const wordFormBtn = {
                             id: `${btn.id}_wordform_${index}`,
                             label: wordForm,
@@ -631,8 +650,11 @@ class MetricsCalculator {
                 });
             });
         });
-        console.log(`📝 Calculated ${wordFormMetrics.length} word form metrics from predictions`);
-        return wordFormMetrics;
+        console.log(`📝 Calculated ${wordFormMetrics.length} word form metrics` +
+            (replacedLabels.size > 0
+                ? ` (${replacedLabels.size} replaced higher-effort buttons: ${Array.from(replacedLabels).join(', ')})`
+                : ''));
+        return { wordFormMetrics, replacedLabels };
     }
     /**
      * Calculate grid dimensions from the tree

package/dist/utilities/analytics/metrics/types.d.ts

@@ -117,6 +117,20 @@ export interface MetricsOptions {
      * Default is 1.5 (checking 1-2 predictions on average).
      */
     predictionSelections?: number;
+    /**
+     * Whether to include smart grammar word forms in metrics
+     *
+     * When true (default): Word forms from smart grammar predictions are included
+     * in the metrics. If a word exists as both a regular button and a word form,
+     * the version with lower effort is used.
+     *
+     * When false: Smart grammar word forms are excluded from metrics. Only actual
+     * buttons in the tree are analyzed.
+     *
+     * Only applicable to systems that support smart grammar (e.g., Grid 3).
+     * Default is true.
+     */
+    useSmartGrammar?: boolean;
 }
 /**
  * Comparison result between two board sets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",