@willwade/aac-processors 0.2.7 → 0.2.9

package/dist/browser/processors/gridsetProcessor.js

@@ -1137,9 +1137,11 @@ class GridsetProcessor extends BaseProcessor {
                                         }
                                         break;
                                     case 'Jump.ToKeyboard': {
-                                        // Navigate to the set keyboard if we found one in settings
+                                        // Prefer explicit keyboard page metadata when available.
+                                        // Some Gridsets resolve the keyboard page in metadata
+                                        // without preserving tree.keyboardGridName during parse.
                                         const keyboardGridName = tree.keyboardGridName;
-                                        const keyboardPageId = gridNameToIdMap.get(keyboardGridName);
+                                        const keyboardPageId = tree.metadata?.defaultKeyboardPageId || gridNameToIdMap.get(keyboardGridName);
                                         if (keyboardPageId && !navigationTarget) {
                                             navigationTarget = keyboardPageId;
                                         }
@@ -1699,6 +1701,7 @@ class GridsetProcessor extends BaseProcessor {
                     settingsData?.gridSetSettings?.keyboardGrid ||
                     settingsData?.GridsetSettings?.KeyboardGrid;
                 if (keyboardGridName && typeof keyboardGridName === 'string') {
+                    tree.keyboardGridName = keyboardGridName;
                     metadata.defaultKeyboardPageId = gridNameToIdMap.get(keyboardGridName);
                 }
             }
@@ -1708,6 +1711,22 @@ class GridsetProcessor extends BaseProcessor {
         }
         // Set metadata on tree
         tree.metadata = metadata;
+        if (metadata.defaultKeyboardPageId) {
+            Object.values(tree.pages).forEach((page) => {
+                page.buttons.forEach((button) => {
+                    if (button?.semanticAction?.platformData?.grid3?.commandId === 'Jump.ToKeyboard' &&
+                        !button.targetPageId) {
+                        button.targetPageId = metadata.defaultKeyboardPageId;
+                        if (button.semanticAction) {
+                            button.semanticAction.targetId = metadata.defaultKeyboardPageId;
+                            if (button.semanticAction.fallback?.type === 'NAVIGATE') {
+                                button.semanticAction.fallback.targetPageId = metadata.defaultKeyboardPageId;
+                            }
+                        }
+                    }
+                });
+            });
+        }
         return tree;
     }
     async processTexts(filePathOrBuffer, translations, outputPath) {
@@ -2207,6 +2226,7 @@ class GridsetProcessor extends BaseProcessor {
     /**
      * Save a modified tree while preserving all original files (settings, images, assets)
      * This method only updates the grid.xml files for pages in the tree, keeping everything else intact.
+     * It preserves the original grid structure and only updates button labels and messages.
      *
      * @param originalPath - Path to the original gridset file
      * @param tree - Modified AACTree with pages to save
@@ -2223,91 +2243,202 @@ class GridsetProcessor extends BaseProcessor {
         const AdmZip = (await import('adm-zip')).default;
         const originalZip = new AdmZip(originalPath);
         const outputZip = new AdmZip();
-        // Collect styles from the tree for grid.xml files
-        const uniqueStyles = new Map();
-        let styleIdCounter = 1;
-        const addStyle = (style) => {
-            if (!style)
-                return '';
-            const normalizedStyle = { ...style };
-            const styleKey = JSON.stringify(normalizedStyle);
-            const existing = uniqueStyles.get(styleKey);
-            if (existing)
-                return existing.id;
-            const styleId = `Style${styleIdCounter++}`;
-            uniqueStyles.set(styleKey, { id: styleId, style: normalizedStyle });
-            return styleId;
-        };
-        // Collect all styles from pages and buttons
-        Object.values(tree.pages).forEach((page) => {
-            addStyle(page.style);
-            page.buttons.forEach((button) => {
-                addStyle(button.style);
-            });
-        });
+        // Create a map of pages by name for easy lookup
+        const pagesByName = new Map();
+        for (const page of Object.values(tree.pages)) {
+            pagesByName.set(page.name, page);
+        }
         // Track which grid files we're modifying
         const modifiedGridFiles = new Set();
-        // Generate grid.xml files for pages in the tree
+        // Generate updated grid.xml files for pages in the tree
         const newGridFiles = new Map();
+        // Create XML parser and builder
+        const parser = new XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '@_',
+        });
+        const gridBuilder = new XMLBuilder({
+            ignoreAttributes: false,
+            format: true,
+            indentBy: '  ',
+            suppressEmptyNode: true,
+            // Preserve Grid 3 XML formatting requirements
+            suppressBooleanAttributes: false,
+        });
         for (const page of Object.values(tree.pages)) {
             const gridPath = `Grids/${page.name}/grid.xml`;
             modifiedGridFiles.add(gridPath);
-            // Build the grid XML content
-            const gridData = {
-                Grid: {
-                    '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
-                    GridGuid: page.id,
-                    ColumnDefinitions: this.calculateColumnDefinitions(page),
-                    RowDefinitions: this.calculateRowDefinitions(page, false),
-                    AutoContentCommands: '',
-                    Cells: page.buttons.length > 0
-                        ? {
-                            Cell: this.filterPageButtons(page.buttons).map((button, btnIndex) => {
-                                const buttonStyleId = button.style ? addStyle(button.style) : '';
-                                const position = this.findButtonPosition(page, button, btnIndex);
-                                const captionAndImage = {
-                                    Caption: button.label || '',
-                                };
-                                // Handle image references
-                                if (button.image) {
-                                    captionAndImage.Image = `${button.image}`;
-                                }
-                                const cell = {
-                                    '@_Column': position.x,
-                                    '@_Row': position.y,
-                                    captionAndImage,
-                                };
-                                if (position.columnSpan > 1) {
-                                    cell['@_ColumnSpan'] = position.columnSpan;
-                                }
-                                if (position.rowSpan > 1) {
-                                    cell['@_RowSpan'] = position.rowSpan;
-                                }
-                                if (buttonStyleId) {
-                                    cell.CellStyle = buttonStyleId;
-                                }
-                                if (button.message && button.message !== button.label) {
-                                    // Use spoken message if different from label
-                                    const spoken = button.message;
-                                    const cellContent = {
-                                        spoken,
-                                        type: 'text',
-                                    };
-                                    cell['ContentCell'] = cellContent;
+            // Try to get the original grid.xml file
+            const originalEntry = originalZip.getEntry(gridPath);
+            if (!originalEntry) {
+                // If original doesn't exist, create a new basic grid
+                const basicGrid = this.createBasicGridXml(page);
+                newGridFiles.set(gridPath, basicGrid);
+                continue;
+            }
+            // Parse the original grid XML
+            const originalContent = originalEntry.getData().toString('utf-8');
+            const originalGrid = parser.parse(originalContent);
+            if (!originalGrid.Grid) {
+                // Invalid grid structure, create a basic one
+                const basicGrid = this.createBasicGridXml(page);
+                newGridFiles.set(gridPath, basicGrid);
+                continue;
+            }
+            // Create a map of buttons by their position for easy lookup
+            const buttonsByPosition = new Map();
+            for (const button of page.buttons) {
+                const pos = this.findButtonPosition(page, button, 0);
+                const key = `${pos.x},${pos.y}`;
+                buttonsByPosition.set(key, button);
+            }
+            // Update cells in the original grid
+            const originalCells = originalGrid.Grid.Cells?.Cell;
+            if (originalCells) {
+                const cellArray = Array.isArray(originalCells) ? originalCells : [originalCells];
+                for (const cell of cellArray) {
+                    if (!cell.Content)
+                        continue;
+                    // Get cell position
+                    const x = parseInt(String(cell['@_X'] || cell['@_Column'] || '0'), 10);
+                    const y = parseInt(String(cell['@_Y'] || cell['@_Row'] || '0'), 10);
+                    const key = `${x},${y}`;
+                    // Check if there's a modified button for this position
+                    const modifiedButton = buttonsByPosition.get(key);
+                    if (modifiedButton) {
+                        // Check if this is an AutoContent/WordList cell
+                        const contentType = cell.Content.ContentType || cell.Content.contentType;
+                        const contentSubType = cell.Content.ContentSubType || cell.Content.contentsubtype;
+                        const isWordListCell = contentType === 'AutoContent' && contentSubType === 'WordList';
+                        const isPredictionCell = contentType === 'AutoContent' && contentSubType === 'Prediction';
+                        if (isWordListCell) {
+                            // For WordList cells, we need to add the word to the page's WordList
+                            // instead of modifying the cell directly. The cell will automatically
+                            // populate from the WordList.
+                            // Note: WordList updates are handled by collecting all new words
+                            // and adding them to the WordList.Items array later.
+                            continue; // Skip cell modification for WordList cells
+                        }
+                        if (isPredictionCell) {
+                            // Prediction cells are populated dynamically by Grid 3's prediction system.
+                            // They should remain as <CaptionAndImage xsi:nil="true" /> and not be modified.
+                            continue; // Skip cell modification for Prediction cells
+                        }
+                        // For regular cells, update the caption directly
+                        // CDATA wrapping for empty captions will be done in post-processing
+                        if (cell.Content.CaptionAndImage || cell.Content.captionAndImage) {
+                            const captionAndImage = cell.Content.CaptionAndImage || cell.Content.captionAndImage;
+                            // Check if the label is a placeholder (generated during extraction)
+                            const isPlaceholderLabel = !modifiedButton.label ||
+                                modifiedButton.label.startsWith('Cell_') ||
+                                modifiedButton.label.startsWith('AutoContent_') ||
+                                modifiedButton.label.startsWith('Prediction ');
+                            if (!isPlaceholderLabel) {
+                                // Only update caption with real content, not placeholders
+                                captionAndImage.Caption = modifiedButton.label;
+                                // Remove xsi:nil attribute when adding content
+                                if (captionAndImage['@_xsi:nil'] || captionAndImage['xsi:nil']) {
+                                    delete captionAndImage['@_xsi:nil'];
+                                    delete captionAndImage['xsi:nil'];
                                 }
-                                return cell;
-                            }),
+                            }
                         }
-                        : undefined,
-                },
-            };
-            const gridBuilder = new XMLBuilder({
-                ignoreAttributes: false,
-                format: true,
-                indentBy: '  ',
-                suppressEmptyNode: true,
-            });
-            newGridFiles.set(gridPath, gridBuilder.build(gridData));
+                        // Update the message if different from label
+                        // But skip placeholder labels
+                        const isPlaceholderMessage = !modifiedButton.message ||
+                            modifiedButton.message.startsWith('Cell_') ||
+                            modifiedButton.message.startsWith('AutoContent_') ||
+                            modifiedButton.message.startsWith('Prediction ');
+                        if (!isPlaceholderMessage &&
+                            modifiedButton.message &&
+                            modifiedButton.message !== modifiedButton.label) {
+                            // For simple text content
+                            if (!cell.Content.Commands) {
+                                cell.Content['#text'] = modifiedButton.message;
+                            }
+                        }
+                        // Update image if present
+                        if (modifiedButton.image) {
+                            if (cell.Content.CaptionAndImage || cell.Content.captionAndImage) {
+                                const captionAndImage = cell.Content.CaptionAndImage || cell.Content.captionAndImage;
+                                captionAndImage.Image = modifiedButton.image;
+                            }
+                        }
+                    }
+                }
+            }
+            // Update the page's WordList with new words from modified buttons
+            // Collect all modified buttons that should be added to the WordList
+            const newWordListItems = [];
+            for (const button of page.buttons) {
+                const pos = this.findButtonPosition(page, button, 0);
+                // Check if this button corresponds to a WordList cell
+                const cellArray = Array.isArray(originalGrid.Grid.Cells?.Cell)
+                    ? originalGrid.Grid.Cells.Cell
+                    : originalGrid.Grid.Cells?.Cell
+                        ? [originalGrid.Grid.Cells.Cell]
+                        : [];
+                const cell = cellArray.find((c) => {
+                    const cellX = parseInt(String(c['@_X'] || '0'), 10);
+                    const cellY = parseInt(String(c['@_Y'] || '0'), 10);
+                    return cellX === pos.x && cellY === pos.y;
+                });
+                if (cell) {
+                    const contentType = cell.Content?.ContentType || cell.Content?.contentType;
+                    const contentSubType = cell.Content?.ContentSubType || cell.Content?.contentsubtype;
+                    const isWordListCell = contentType === 'AutoContent' && contentSubType === 'WordList';
+                    // Note: Prediction cells are already skipped earlier, so they won't reach here
+                    if (isWordListCell) {
+                        // Add this button to the WordList with proper Grid 3 format
+                        // Format: <Text><s><r>label</r></s></Text>
+                        newWordListItems.push({
+                            Text: {
+                                s: {
+                                    r: button.label,
+                                },
+                            },
+                            Image: '', // No image for user-added words
+                            PartOfSpeech: 'Unknown',
+                        });
+                    }
+                }
+            }
+            // Add new items to the existing WordList
+            if (newWordListItems.length > 0) {
+                const existingWordList = originalGrid.Grid.WordList;
+                if (existingWordList && existingWordList.Items) {
+                    const existingItems = existingWordList.Items.WordListItem || existingWordList.Items.wordlistitem || [];
+                    const itemsArray = Array.isArray(existingItems) ? existingItems : [existingItems];
+                    // Merge existing and new items
+                    const allItems = [...itemsArray, ...newWordListItems];
+                    // Update the WordList
+                    if (!originalGrid.Grid.WordList) {
+                        originalGrid.Grid.WordList = {};
+                    }
+                    if (!originalGrid.Grid.WordList.Items) {
+                        originalGrid.Grid.WordList.Items = {};
+                    }
+                    originalGrid.Grid.WordList.Items.WordListItem = allItems;
+                }
+            }
+            // Build the updated grid XML and convert to Windows line endings
+            let builtXml = gridBuilder.build(originalGrid);
+            // Convert Unix line endings to Windows (\r\n) for Grid 3 compatibility
+            builtXml = builtXml.replace(/\n/g, '\r\n');
+            // Expand self-closing tags to full opening/closing tags for Grid 3 compatibility
+            // Grid 3 cannot parse <AudioDescription /> - it requires <AudioDescription></AudioDescription>
+            builtXml = builtXml.replace(/<(\w+)(\s+[^>]*)?\s*\/>/g, '<$1$2></$1>');
+            // Convert empty/whitespace captions to CDATA format for Grid 3 compatibility
+            // Grid 3 requires <![CDATA[ ]]> for empty captions, not plain text
+            builtXml = builtXml.replace(/<Caption><\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+            builtXml = builtXml.replace(/<Caption> <\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+            builtXml = builtXml.replace(/<Caption> {2}<\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+            // Preserve CDATA in <r> tags for text parameters
+            // Spaces in <r> tags must use CDATA or they get stripped during rendering
+            // e.g., <r> </r> becomes <r><![CDATA[ ]]></r>
+            builtXml = builtXml.replace(/<r> <\/r>/g, '<r><![CDATA[ ]]></r>');
+            builtXml = builtXml.replace(/<r> {2}<\/r>/g, '<r><![CDATA[  ]]></r>');
+            newGridFiles.set(gridPath, builtXml);
         }
         // Copy all files from original zip, replacing modified grid files
         for (const entry of originalZip.getEntries()) {
@@ -2328,6 +2459,60 @@ class GridsetProcessor extends BaseProcessor {
         const outputBuffer = outputZip.toBuffer();
         await writeBinaryToPath(outputPath, outputBuffer);
     }
+    /**
+     * Create a basic grid XML for a page when original doesn't exist
+     */
+    createBasicGridXml(page) {
+        const gridData = {
+            Grid: {
+                '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+                GridGuid: page.id,
+                ColumnDefinitions: this.calculateColumnDefinitions(page),
+                RowDefinitions: this.calculateRowDefinitions(page, false),
+                AutoContentCommands: '',
+                Cells: page.buttons.length > 0
+                    ? {
+                        Cell: this.filterPageButtons(page.buttons).map((button, btnIndex) => {
+                            const position = this.findButtonPosition(page, button, btnIndex);
+                            const cell = {
+                                '@_X': position.x,
+                                '@_Y': position.y,
+                                Content: {
+                                    CaptionAndImage: {
+                                        Caption: button.label || '',
+                                    },
+                                },
+                            };
+                            if (button.image) {
+                                cell.Content.CaptionAndImage.Image = button.image;
+                            }
+                            if (position.columnSpan > 1) {
+                                cell['@_ColumnSpan'] = position.columnSpan;
+                            }
+                            if (position.rowSpan > 1) {
+                                cell['@_RowSpan'] = position.rowSpan;
+                            }
+                            return cell;
+                        }),
+                    }
+                    : undefined,
+            },
+        };
+        const gridBuilder = new XMLBuilder({
+            ignoreAttributes: false,
+            format: true,
+            indentBy: '  ',
+            suppressEmptyNode: true,
+            // Preserve Grid 3 XML formatting requirements
+            suppressBooleanAttributes: false,
+        });
+        // Build the grid XML and convert to Windows line endings for Grid 3 compatibility
+        let builtXml = gridBuilder.build(gridData);
+        builtXml = builtXml.replace(/\n/g, '\r\n');
+        // Expand self-closing tags to full opening/closing tags for Grid 3 compatibility
+        builtXml = builtXml.replace(/<(\w+)(\s+[^>]*)?\s*\/>/g, '<$1$2></$1>');
+        return builtXml;
+    }
     // Helper method to find button position with span information
     findButtonPosition(page, button, fallbackIndex) {
         if (page.grid && page.grid.length > 0) {

package/dist/processors/gridsetProcessor.d.ts

@@ -54,12 +54,17 @@ declare class GridsetProcessor extends BaseProcessor {
     /**
      * Save a modified tree while preserving all original files (settings, images, assets)
      * This method only updates the grid.xml files for pages in the tree, keeping everything else intact.
+     * It preserves the original grid structure and only updates button labels and messages.
      *
      * @param originalPath - Path to the original gridset file
      * @param tree - Modified AACTree with pages to save
      * @param outputPath - Path where the modified gridset should be saved
      */
     saveModifiedTree(originalPath: string, tree: AACTree, outputPath: string): Promise<void>;
+    /**
+     * Create a basic grid XML for a page when original doesn't exist
+     */
+    private createBasicGridXml;
     private findButtonPosition;
     /**
      * Extract strings with metadata for aac-tools-platform compatibility

package/dist/processors/gridsetProcessor.js

@@ -1163,9 +1163,11 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                         }
                                         break;
                                     case 'Jump.ToKeyboard': {
-                                        // Navigate to the set keyboard if we found one in settings
+                                        // Prefer explicit keyboard page metadata when available.
+                                        // Some Gridsets resolve the keyboard page in metadata
+                                        // without preserving tree.keyboardGridName during parse.
                                         const keyboardGridName = tree.keyboardGridName;
-                                        const keyboardPageId = gridNameToIdMap.get(keyboardGridName);
+                                        const keyboardPageId = tree.metadata?.defaultKeyboardPageId || gridNameToIdMap.get(keyboardGridName);
                                         if (keyboardPageId && !navigationTarget) {
                                             navigationTarget = keyboardPageId;
                                         }
@@ -1725,6 +1727,7 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                     settingsData?.gridSetSettings?.keyboardGrid ||
                     settingsData?.GridsetSettings?.KeyboardGrid;
                 if (keyboardGridName && typeof keyboardGridName === 'string') {
+                    tree.keyboardGridName = keyboardGridName;
                     metadata.defaultKeyboardPageId = gridNameToIdMap.get(keyboardGridName);
                 }
             }
@@ -1734,6 +1737,22 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         }
         // Set metadata on tree
         tree.metadata = metadata;
+        if (metadata.defaultKeyboardPageId) {
+            Object.values(tree.pages).forEach((page) => {
+                page.buttons.forEach((button) => {
+                    if (button?.semanticAction?.platformData?.grid3?.commandId === 'Jump.ToKeyboard' &&
+                        !button.targetPageId) {
+                        button.targetPageId = metadata.defaultKeyboardPageId;
+                        if (button.semanticAction) {
+                            button.semanticAction.targetId = metadata.defaultKeyboardPageId;
+                            if (button.semanticAction.fallback?.type === 'NAVIGATE') {
+                                button.semanticAction.fallback.targetPageId = metadata.defaultKeyboardPageId;
+                            }
+                        }
+                    }
+                });
+            });
+        }
         return tree;
     }
     async processTexts(filePathOrBuffer, translations, outputPath) {
@@ -2233,6 +2252,7 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
     /**
      * Save a modified tree while preserving all original files (settings, images, assets)
      * This method only updates the grid.xml files for pages in the tree, keeping everything else intact.
+     * It preserves the original grid structure and only updates button labels and messages.
      *
      * @param originalPath - Path to the original gridset file
      * @param tree - Modified AACTree with pages to save
@@ -2249,91 +2269,202 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         const AdmZip = (await Promise.resolve().then(() => __importStar(require('adm-zip')))).default;
         const originalZip = new AdmZip(originalPath);
         const outputZip = new AdmZip();
-        // Collect styles from the tree for grid.xml files
-        const uniqueStyles = new Map();
-        let styleIdCounter = 1;
-        const addStyle = (style) => {
-            if (!style)
-                return '';
-            const normalizedStyle = { ...style };
-            const styleKey = JSON.stringify(normalizedStyle);
-            const existing = uniqueStyles.get(styleKey);
-            if (existing)
-                return existing.id;
-            const styleId = `Style${styleIdCounter++}`;
-            uniqueStyles.set(styleKey, { id: styleId, style: normalizedStyle });
-            return styleId;
-        };
-        // Collect all styles from pages and buttons
-        Object.values(tree.pages).forEach((page) => {
-            addStyle(page.style);
-            page.buttons.forEach((button) => {
-                addStyle(button.style);
-            });
-        });
+        // Create a map of pages by name for easy lookup
+        const pagesByName = new Map();
+        for (const page of Object.values(tree.pages)) {
+            pagesByName.set(page.name, page);
+        }
         // Track which grid files we're modifying
         const modifiedGridFiles = new Set();
-        // Generate grid.xml files for pages in the tree
+        // Generate updated grid.xml files for pages in the tree
         const newGridFiles = new Map();
+        // Create XML parser and builder
+        const parser = new fast_xml_parser_1.XMLParser({
+            ignoreAttributes: false,
+            attributeNamePrefix: '@_',
+        });
+        const gridBuilder = new fast_xml_parser_1.XMLBuilder({
+            ignoreAttributes: false,
+            format: true,
+            indentBy: '  ',
+            suppressEmptyNode: true,
+            // Preserve Grid 3 XML formatting requirements
+            suppressBooleanAttributes: false,
+        });
         for (const page of Object.values(tree.pages)) {
             const gridPath = `Grids/${page.name}/grid.xml`;
             modifiedGridFiles.add(gridPath);
-            // Build the grid XML content
-            const gridData = {
-                Grid: {
-                    '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
-                    GridGuid: page.id,
-                    ColumnDefinitions: this.calculateColumnDefinitions(page),
-                    RowDefinitions: this.calculateRowDefinitions(page, false),
-                    AutoContentCommands: '',
-                    Cells: page.buttons.length > 0
-                        ? {
-                            Cell: this.filterPageButtons(page.buttons).map((button, btnIndex) => {
-                                const buttonStyleId = button.style ? addStyle(button.style) : '';
-                                const position = this.findButtonPosition(page, button, btnIndex);
-                                const captionAndImage = {
-                                    Caption: button.label || '',
-                                };
-                                // Handle image references
-                                if (button.image) {
-                                    captionAndImage.Image = `${button.image}`;
-                                }
-                                const cell = {
-                                    '@_Column': position.x,
-                                    '@_Row': position.y,
-                                    captionAndImage,
-                                };
-                                if (position.columnSpan > 1) {
-                                    cell['@_ColumnSpan'] = position.columnSpan;
-                                }
-                                if (position.rowSpan > 1) {
-                                    cell['@_RowSpan'] = position.rowSpan;
-                                }
-                                if (buttonStyleId) {
-                                    cell.CellStyle = buttonStyleId;
-                                }
-                                if (button.message && button.message !== button.label) {
-                                    // Use spoken message if different from label
-                                    const spoken = button.message;
-                                    const cellContent = {
-                                        spoken,
-                                        type: 'text',
-                                    };
-                                    cell['ContentCell'] = cellContent;
+            // Try to get the original grid.xml file
+            const originalEntry = originalZip.getEntry(gridPath);
+            if (!originalEntry) {
+                // If original doesn't exist, create a new basic grid
+                const basicGrid = this.createBasicGridXml(page);
+                newGridFiles.set(gridPath, basicGrid);
+                continue;
+            }
+            // Parse the original grid XML
+            const originalContent = originalEntry.getData().toString('utf-8');
+            const originalGrid = parser.parse(originalContent);
+            if (!originalGrid.Grid) {
+                // Invalid grid structure, create a basic one
+                const basicGrid = this.createBasicGridXml(page);
+                newGridFiles.set(gridPath, basicGrid);
+                continue;
+            }
+            // Create a map of buttons by their position for easy lookup
+            const buttonsByPosition = new Map();
+            for (const button of page.buttons) {
+                const pos = this.findButtonPosition(page, button, 0);
+                const key = `${pos.x},${pos.y}`;
+                buttonsByPosition.set(key, button);
+            }
+            // Update cells in the original grid
+            const originalCells = originalGrid.Grid.Cells?.Cell;
+            if (originalCells) {
+                const cellArray = Array.isArray(originalCells) ? originalCells : [originalCells];
+                for (const cell of cellArray) {
+                    if (!cell.Content)
+                        continue;
+                    // Get cell position
+                    const x = parseInt(String(cell['@_X'] || cell['@_Column'] || '0'), 10);
+                    const y = parseInt(String(cell['@_Y'] || cell['@_Row'] || '0'), 10);
+                    const key = `${x},${y}`;
+                    // Check if there's a modified button for this position
+                    const modifiedButton = buttonsByPosition.get(key);
+                    if (modifiedButton) {
+                        // Check if this is an AutoContent/WordList cell
+                        const contentType = cell.Content.ContentType || cell.Content.contentType;
+                        const contentSubType = cell.Content.ContentSubType || cell.Content.contentsubtype;
+                        const isWordListCell = contentType === 'AutoContent' && contentSubType === 'WordList';
+                        const isPredictionCell = contentType === 'AutoContent' && contentSubType === 'Prediction';
+                        if (isWordListCell) {
+                            // For WordList cells, we need to add the word to the page's WordList
+                            // instead of modifying the cell directly. The cell will automatically
+                            // populate from the WordList.
+                            // Note: WordList updates are handled by collecting all new words
+                            // and adding them to the WordList.Items array later.
+                            continue; // Skip cell modification for WordList cells
+                        }
+                        if (isPredictionCell) {
+                            // Prediction cells are populated dynamically by Grid 3's prediction system.
+                            // They should remain as <CaptionAndImage xsi:nil="true" /> and not be modified.
+                            continue; // Skip cell modification for Prediction cells
+                        }
+                        // For regular cells, update the caption directly
+                        // CDATA wrapping for empty captions will be done in post-processing
+                        if (cell.Content.CaptionAndImage || cell.Content.captionAndImage) {
+                            const captionAndImage = cell.Content.CaptionAndImage || cell.Content.captionAndImage;
+                            // Check if the label is a placeholder (generated during extraction)
+                            const isPlaceholderLabel = !modifiedButton.label ||
+                                modifiedButton.label.startsWith('Cell_') ||
+                                modifiedButton.label.startsWith('AutoContent_') ||
+                                modifiedButton.label.startsWith('Prediction ');
+                            if (!isPlaceholderLabel) {
+                                // Only update caption with real content, not placeholders
+                                captionAndImage.Caption = modifiedButton.label;
+                                // Remove xsi:nil attribute when adding content
+                                if (captionAndImage['@_xsi:nil'] || captionAndImage['xsi:nil']) {
+                                    delete captionAndImage['@_xsi:nil'];
+                                    delete captionAndImage['xsi:nil'];
                                 }
-                                return cell;
-                            }),
+                            }
                         }
-                        : undefined,
-                },
-            };
-            const gridBuilder = new fast_xml_parser_1.XMLBuilder({
-                ignoreAttributes: false,
-                format: true,
-                indentBy: '  ',
-                suppressEmptyNode: true,
-            });
-            newGridFiles.set(gridPath, gridBuilder.build(gridData));
+                        // Update the message if different from label
+                        // But skip placeholder labels
+                        const isPlaceholderMessage = !modifiedButton.message ||
+                            modifiedButton.message.startsWith('Cell_') ||
+                            modifiedButton.message.startsWith('AutoContent_') ||
+                            modifiedButton.message.startsWith('Prediction ');
+                        if (!isPlaceholderMessage &&
+                            modifiedButton.message &&
+                            modifiedButton.message !== modifiedButton.label) {
+                            // For simple text content
+                            if (!cell.Content.Commands) {
+                                cell.Content['#text'] = modifiedButton.message;
+                            }
+                        }
+                        // Update image if present
+                        if (modifiedButton.image) {
+                            if (cell.Content.CaptionAndImage || cell.Content.captionAndImage) {
+                                const captionAndImage = cell.Content.CaptionAndImage || cell.Content.captionAndImage;
+                                captionAndImage.Image = modifiedButton.image;
+                            }
+                        }
+                    }
+                }
+            }
+            // Update the page's WordList with new words from modified buttons
+            // Collect all modified buttons that should be added to the WordList
+            const newWordListItems = [];
+            for (const button of page.buttons) {
+                const pos = this.findButtonPosition(page, button, 0);
+                // Check if this button corresponds to a WordList cell
+                const cellArray = Array.isArray(originalGrid.Grid.Cells?.Cell)
+                    ? originalGrid.Grid.Cells.Cell
+                    : originalGrid.Grid.Cells?.Cell
+                        ? [originalGrid.Grid.Cells.Cell]
+                        : [];
+                const cell = cellArray.find((c) => {
+                    const cellX = parseInt(String(c['@_X'] || '0'), 10);
+                    const cellY = parseInt(String(c['@_Y'] || '0'), 10);
+                    return cellX === pos.x && cellY === pos.y;
+                });
+                if (cell) {
+                    const contentType = cell.Content?.ContentType || cell.Content?.contentType;
+                    const contentSubType = cell.Content?.ContentSubType || cell.Content?.contentsubtype;
+                    const isWordListCell = contentType === 'AutoContent' && contentSubType === 'WordList';
+                    // Note: Prediction cells are already skipped earlier, so they won't reach here
+                    if (isWordListCell) {
+                        // Add this button to the WordList with proper Grid 3 format
+                        // Format: <Text><s><r>label</r></s></Text>
+                        newWordListItems.push({
+                            Text: {
+                                s: {
+                                    r: button.label,
+                                },
+                            },
+                            Image: '', // No image for user-added words
+                            PartOfSpeech: 'Unknown',
+                        });
+                    }
+                }
+            }
+            // Add new items to the existing WordList
+            if (newWordListItems.length > 0) {
+                const existingWordList = originalGrid.Grid.WordList;
+                if (existingWordList && existingWordList.Items) {
+                    const existingItems = existingWordList.Items.WordListItem || existingWordList.Items.wordlistitem || [];
+                    const itemsArray = Array.isArray(existingItems) ? existingItems : [existingItems];
+                    // Merge existing and new items
+                    const allItems = [...itemsArray, ...newWordListItems];
+                    // Update the WordList
+                    if (!originalGrid.Grid.WordList) {
+                        originalGrid.Grid.WordList = {};
+                    }
+                    if (!originalGrid.Grid.WordList.Items) {
+                        originalGrid.Grid.WordList.Items = {};
+                    }
+                    originalGrid.Grid.WordList.Items.WordListItem = allItems;
+                }
+            }
+            // Build the updated grid XML and convert to Windows line endings
+            let builtXml = gridBuilder.build(originalGrid);
+            // Convert Unix line endings to Windows (\r\n) for Grid 3 compatibility
+            builtXml = builtXml.replace(/\n/g, '\r\n');
+            // Expand self-closing tags to full opening/closing tags for Grid 3 compatibility
+            // Grid 3 cannot parse <AudioDescription /> - it requires <AudioDescription></AudioDescription>
+            builtXml = builtXml.replace(/<(\w+)(\s+[^>]*)?\s*\/>/g, '<$1$2></$1>');
+            // Convert empty/whitespace captions to CDATA format for Grid 3 compatibility
+            // Grid 3 requires <![CDATA[ ]]> for empty captions, not plain text
+            builtXml = builtXml.replace(/<Caption><\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+            builtXml = builtXml.replace(/<Caption> <\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+            builtXml = builtXml.replace(/<Caption> {2}<\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+            // Preserve CDATA in <r> tags for text parameters
+            // Spaces in <r> tags must use CDATA or they get stripped during rendering
+            // e.g., <r> </r> becomes <r><![CDATA[ ]]></r>
+            builtXml = builtXml.replace(/<r> <\/r>/g, '<r><![CDATA[ ]]></r>');
+            builtXml = builtXml.replace(/<r> {2}<\/r>/g, '<r><![CDATA[  ]]></r>');
+            newGridFiles.set(gridPath, builtXml);
         }
         // Copy all files from original zip, replacing modified grid files
         for (const entry of originalZip.getEntries()) {
@@ -2354,6 +2485,60 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         const outputBuffer = outputZip.toBuffer();
         await writeBinaryToPath(outputPath, outputBuffer);
     }
+    /**
+     * Create a basic grid XML for a page when original doesn't exist
+     */
+    createBasicGridXml(page) {
+        const gridData = {
+            Grid: {
+                '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+                GridGuid: page.id,
+                ColumnDefinitions: this.calculateColumnDefinitions(page),
+                RowDefinitions: this.calculateRowDefinitions(page, false),
+                AutoContentCommands: '',
+                Cells: page.buttons.length > 0
+                    ? {
+                        Cell: this.filterPageButtons(page.buttons).map((button, btnIndex) => {
+                            const position = this.findButtonPosition(page, button, btnIndex);
+                            const cell = {
+                                '@_X': position.x,
+                                '@_Y': position.y,
+                                Content: {
+                                    CaptionAndImage: {
+                                        Caption: button.label || '',
+                                    },
+                                },
+                            };
+                            if (button.image) {
+                                cell.Content.CaptionAndImage.Image = button.image;
+                            }
+                            if (position.columnSpan > 1) {
+                                cell['@_ColumnSpan'] = position.columnSpan;
+                            }
+                            if (position.rowSpan > 1) {
+                                cell['@_RowSpan'] = position.rowSpan;
+                            }
+                            return cell;
+                        }),
+                    }
+                    : undefined,
+            },
+        };
+        const gridBuilder = new fast_xml_parser_1.XMLBuilder({
+            ignoreAttributes: false,
+            format: true,
+            indentBy: '  ',
+            suppressEmptyNode: true,
+            // Preserve Grid 3 XML formatting requirements
+            suppressBooleanAttributes: false,
+        });
+        // Build the grid XML and convert to Windows line endings for Grid 3 compatibility
+        let builtXml = gridBuilder.build(gridData);
+        builtXml = builtXml.replace(/\n/g, '\r\n');
+        // Expand self-closing tags to full opening/closing tags for Grid 3 compatibility
+        builtXml = builtXml.replace(/<(\w+)(\s+[^>]*)?\s*\/>/g, '<$1$2></$1>');
+        return builtXml;
+    }
     // Helper method to find button position with span information
     findButtonPosition(page, button, fallbackIndex) {
         if (page.grid && page.grid.length > 0) {

package/package.json

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