@willwade/aac-processors 0.2.9 → 0.2.11

package/README.md

@@ -13,6 +13,7 @@ npm install @willwade/aac-processors
 ## Dual Build Targets
 
 ### Node.js (default)
+
 Full feature set, including filesystem access, SQLite-backed formats, and
 ZIP/encrypted formats.
 
@@ -27,6 +28,7 @@ const texts = await snap.extractTexts('board.sps');
 ```
 
 ### Browser
+
 Browser-safe entry that avoids Node-only dependencies. It expects `Buffer`,
 `Uint8Array`, or `ArrayBuffer` inputs rather than file paths.
 
@@ -82,7 +84,8 @@ const translations = new Map([
 
 await processor.processTexts('board.dot', translations, 'board-es.dot');
 ```
-NB: Please use [https://aactools.co.uk](https://aactools.co.uk) for a far more comphrensive translation logic - where we do far far more than this...  
+
+NB: Please use [https://aactools.co.uk](https://aactools.co.uk) for a far more comphrensive translation logic - where we do far far more than this...
 
 ## Documentation
 

package/dist/browser/processors/gridset/cellHelpers.js

@@ -0,0 +1,97 @@
+/**
+ * Grid3 Cell Helpers
+ *
+ * Utilities for working with Grid 3 cells, including finding button positions
+ * and calculating cell spans in grid layouts.
+ */
+/**
+ * Find button position with span information
+ *
+ * Searches the page's grid layout for a button and calculates its position
+ * and span (how many columns/rows it occupies).
+ *
+ * @param page - The AAC page containing the button
+ * @param button - The button to locate
+ * @param fallbackIndex - Index to use if button not found in grid
+ * @returns Position and span information for the button
+ *
+ * @example
+ * const position = findButtonPosition(page, button, 0);
+ * console.log(`Button at ${position.x},${position.y} spans ${position.columnSpan}x${position.rowSpan}`);
+ */
+export function findButtonPosition(page, button, fallbackIndex) {
+    if (page.grid && page.grid.length > 0) {
+        // Search for button in grid layout and calculate span
+        for (let y = 0; y < page.grid.length; y++) {
+            for (let x = 0; x < page.grid[y].length; x++) {
+                const current = page.grid[y][x];
+                if (current && current.id === button.id) {
+                    // Calculate span by checking how far the same button extends
+                    let columnSpan = 1;
+                    let rowSpan = 1;
+                    // Check column span (rightward)
+                    while (x + columnSpan < page.grid[y].length) {
+                        const right = page.grid[y][x + columnSpan];
+                        if (right && right.id === button.id) {
+                            columnSpan++;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    // Check row span (downward)
+                    while (y + rowSpan < page.grid.length) {
+                        const below = page.grid[y + rowSpan][x];
+                        if (below && below.id === button.id) {
+                            rowSpan++;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    return { x, y, columnSpan, rowSpan };
+                }
+            }
+        }
+    }
+    // Fallback positioning
+    const gridCols = page.grid?.[0]?.length || Math.ceil(Math.sqrt(page.buttons.length));
+    return {
+        x: fallbackIndex % gridCols,
+        y: Math.floor(fallbackIndex / gridCols),
+        columnSpan: 1,
+        rowSpan: 1,
+    };
+}
+/**
+ * Calculate cell position key for Maps and Sets
+ *
+ * Creates a string key from X and Y coordinates for use as a Map key or Set entry.
+ *
+ * @param x - X coordinate
+ * @param y - Y coordinate
+ * @returns String key in format "x,y"
+ *
+ * @example
+ * const key = cellPositionKey(5, 3);
+ * console.log(key); // "5,3"
+ */
+export function cellPositionKey(x, y) {
+    return `${x},${y}`;
+}
+/**
+ * Parse cell position key
+ *
+ * Extracts X and Y coordinates from a position key string.
+ *
+ * @param key - Position key in format "x,y"
+ * @returns Object with x and y properties
+ *
+ * @example
+ * const pos = parseCellPositionKey("5,3");
+ * console.log(pos); // { x: 5, y: 3 }
+ */
+export function parseCellPositionKey(key) {
+    const [x, y] = key.split(',').map(Number);
+    return { x, y };
+}

package/dist/browser/processors/gridset/gridCalculations.js

@@ -0,0 +1,61 @@
+/**
+ * Grid3 Grid Calculations
+ *
+ * Utilities for calculating grid dimensions and definitions
+ * based on page layout and button count.
+ */
+/**
+ * Calculate column definitions based on page layout
+ *
+ * Analyzes the page's grid structure to determine the number of columns.
+ * If no grid exists, estimates from button count.
+ *
+ * @param page - The AAC page to analyze
+ * @returns Column definitions object for Grid 3 XML
+ *
+ * @example
+ * const columns = calculateColumnDefinitions(page);
+ * // Returns: { ColumnDefinition: [{}, {}, {}, {}] } for 4 columns
+ */
+export function calculateColumnDefinitions(page) {
+    let maxCols = 4; // Default minimum
+    if (page.grid && page.grid.length > 0) {
+        maxCols = Math.max(maxCols, page.grid[0]?.length || 0);
+    }
+    else {
+        // Fallback: estimate from button count
+        maxCols = Math.max(4, Math.ceil(Math.sqrt(page.buttons.length)));
+    }
+    return {
+        ColumnDefinition: Array(maxCols).fill({}),
+    };
+}
+/**
+ * Calculate row definitions based on page layout
+ *
+ * Analyzes the page's grid structure to determine the number of rows.
+ * If no grid exists, estimates from button count.
+ *
+ * @param page - The AAC page to analyze
+ * @param addWorkspaceOffset - Whether to add 1 row for workspace (default: false)
+ * @returns Row definitions object for Grid 3 XML
+ *
+ * @example
+ * const rows = calculateRowDefinitions(page, false);
+ * // Returns: { RowDefinition: [{}, {}, {}, {}] } for 4 rows
+ */
+export function calculateRowDefinitions(page, addWorkspaceOffset = false) {
+    let maxRows = 4; // Default minimum
+    const offset = addWorkspaceOffset ? 1 : 0;
+    if (page.grid && page.grid.length > 0) {
+        maxRows = Math.max(maxRows, page.grid.length + offset);
+    }
+    else {
+        // Fallback: estimate from button count
+        const estimatedCols = Math.ceil(Math.sqrt(page.buttons.length));
+        maxRows = Math.max(4, Math.ceil(page.buttons.length / estimatedCols)) + offset;
+    }
+    return {
+        RowDefinition: Array(maxRows).fill({}),
+    };
+}

package/dist/browser/processors/gridset/helpers.js

@@ -149,7 +149,10 @@ export function getCommonDocumentsPath() {
         // Query registry for Common Documents path
         const child_process = getNodeRequire()('child_process');
         const command = 'REG.EXE QUERY "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Shell Folders" /V "Common Documents"';
-        const output = child_process.execSync(command, { encoding: 'utf-8', windowsHide: true });
+        const output = child_process.execSync(command, {
+            encoding: 'utf-8',
+            windowsHide: true,
+        });
         // Parse the output to extract the path
         const match = output.match(/Common Documents\s+REG_SZ\s+(.+)/);
         if (match && match[1]) {

package/dist/browser/processors/gridset/xmlFormatter.js

@@ -0,0 +1,84 @@
+/**
+ * Grid3 XML Formatter
+ *
+ * Utilities for formatting XML to match Grid 3's specific requirements.
+ * Grid 3 has strict formatting requirements including line endings, self-closing
+ * tag spacing, and specific tag expansion rules.
+ */
+/**
+ * Tags that Grid 3 requires in full opening/closing format instead of self-closing
+ * Grid 3 cannot parse <AudioDescription /> - it requires <AudioDescription></AudioDescription>
+ */
+const TAGS_NEEDING_EXPANSION = ['AudioDescription', 'VideoDescription'];
+/**
+ * Format XML string to match Grid 3's requirements
+ *
+ * Grid 3 requires specific formatting:
+ * - Windows line endings (\r\n)
+ * - Space before /> in self-closing tags: <Element /> not <Element/>
+ * - Plain apostrophes instead of &apos;
+ * - Specific tags expanded to full opening/closing format
+ * - CDATA for empty/whitespace captions and <r> tags
+ *
+ * @param xml - The XML string to format
+ * @returns Formatted XML string compatible with Grid 3
+ *
+ * @example
+ * const formatted = formatGrid3Xml('<Grid><Cell X="0"/></Grid>');
+ * // Returns: '<Grid>\r\n<Cell X="0" />\r\n</Grid>'
+ */
+export function formatGrid3Xml(xml) {
+    let formatted = xml;
+    // Convert Unix line endings to Windows (\r\n) for Grid 3 compatibility
+    formatted = formatted.replace(/\n/g, '\r\n');
+    // Add space before /> in self-closing tags to match Grid 3's expected format
+    // Grid 3 original files use <Element /> not <Element/>
+    formatted = formatted.replace(/<(\w+)([^>]*)\/>/g, '<$1$2 />');
+    // Decode XML entities back to plain text to match Grid 3's expected format
+    // Grid 3 expects plain apostrophes, not &apos;
+    formatted = formatted.replace(/&apos;/g, "'");
+    formatted = formatted.replace(/&quot;/g, '"');
+    formatted = formatted.replace(/&lt;/g, '<');
+    formatted = formatted.replace(/&gt;/g, '>');
+    // Expand only specific self-closing tags that Grid 3 requires in full opening/closing format
+    // This must be done AFTER adding spaces, so we need to match the format with spaces
+    for (const tag of TAGS_NEEDING_EXPANSION) {
+        formatted = formatted.replace(new RegExp(`<${tag}(\\s+[^>]*)? />`, 'g'), `<${tag}$1></${tag}>`);
+    }
+    return formatted;
+}
+/**
+ * Format empty/whitespace captions with CDATA for Grid 3 compatibility
+ *
+ * Grid 3 requires <![CDATA[ ]]> for empty captions, not plain text.
+ * Also handles <r> tags which need CDATA for spaces to prevent stripping.
+ *
+ * @param xml - The XML string to format
+ * @returns XML string with CDATA-wrapped empty content
+ */
+export function formatEmptyCaptionsWithCdata(xml) {
+    let formatted = xml;
+    // Convert empty/whitespace captions to CDATA format for Grid 3 compatibility
+    // Grid 3 requires <![CDATA[ ]]> for empty captions, not plain text
+    formatted = formatted.replace(/<Caption><\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+    formatted = formatted.replace(/<Caption> <\/Caption>/g, '<Caption><![CDATA[ ]]></Caption>');
+    formatted = formatted.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>
+    formatted = formatted.replace(/<r> <\/r>/g, '<r><![CDATA[ ]]></r>');
+    formatted = formatted.replace(/<r> {2}<\/r>/g, '<r><![CDATA[  ]]></r>');
+    return formatted;
+}
+/**
+ * Complete XML formatting for Grid 3 compatibility
+ * Combines all Grid 3 XML formatting requirements
+ *
+ * @param xml - The XML string to format
+ * @returns Fully formatted XML string compatible with Grid 3
+ */
+export function formatGrid3XmlComplete(xml) {
+    let formatted = formatGrid3Xml(xml);
+    formatted = formatEmptyCaptionsWithCdata(formatted);
+    return formatted;
+}

package/dist/browser/processors/gridsetProcessor.js

@@ -5,6 +5,9 @@ import { resolveGrid3CellImage } from './gridset/resolver';
 import { extractAllButtonsForTranslation, validateTranslationResults, } from '../utilities/translation/translationProcessor';
 import { getZipEntriesFromAdapter, resolveGridsetPassword, } from './gridset/password';
 import { decryptGridsetEntry } from './gridset/crypto';
+import { formatGrid3XmlComplete } from './gridset/xmlFormatter';
+import { calculateColumnDefinitions as calcColumnDefs, calculateRowDefinitions as calcRowDefs, } from './gridset/gridCalculations';
+import { findButtonPosition as findButtonPos } from './gridset/cellHelpers';
 import { GridsetValidator } from '../validation/gridsetValidator';
 // New imports for enhanced Grid 3 support
 import { detectPluginCellType, Grid3CellType } from './gridset/pluginTypes';
@@ -2195,33 +2198,11 @@ class GridsetProcessor extends BaseProcessor {
     }
     // Helper method to calculate column definitions based on page layout
     calculateColumnDefinitions(page) {
-        let maxCols = 4; // Default minimum
-        if (page.grid && page.grid.length > 0) {
-            maxCols = Math.max(maxCols, page.grid[0]?.length || 0);
-        }
-        else {
-            // Fallback: estimate from button count
-            maxCols = Math.max(4, Math.ceil(Math.sqrt(page.buttons.length)));
-        }
-        return {
-            ColumnDefinition: Array(maxCols).fill({}),
-        };
+        return calcColumnDefs(page);
     }
     // Helper method to calculate row definitions based on page layout
     calculateRowDefinitions(page, addWorkspaceOffset = false) {
-        let maxRows = 4; // Default minimum
-        const offset = addWorkspaceOffset ? 1 : 0;
-        if (page.grid && page.grid.length > 0) {
-            maxRows = Math.max(maxRows, page.grid.length + offset);
-        }
-        else {
-            // Fallback: estimate from button count
-            const estimatedCols = Math.ceil(Math.sqrt(page.buttons.length));
-            maxRows = Math.max(4, Math.ceil(page.buttons.length / estimatedCols)) + offset;
-        }
-        return {
-            RowDefinition: Array(maxRows).fill({}),
-        };
+        return calcRowDefs(page, addWorkspaceOffset);
     }
     /**
      * Save a modified tree while preserving all original files (settings, images, assets)
@@ -2367,6 +2348,9 @@ class GridsetProcessor extends BaseProcessor {
                     }
                 }
             }
+            // DO NOT create new cells - the system should only modify existing content
+            // Personalized vocabulary is added to WordList cells via the WordList.Items array
+            // Creating new cells would corrupt the grid structure
             // Update the page's WordList with new words from modified buttons
             // Collect all modified buttons that should be added to the WordList
             const newWordListItems = [];
@@ -2379,9 +2363,18 @@ class GridsetProcessor extends BaseProcessor {
                         ? [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;
+                    const cellY = parseInt(String(c['@_Y'] || c['@_Row'] || '0'), 10);
+                    // Check Y position first
+                    if (cellY !== pos.y) {
+                        return false;
+                    }
+                    const cellX = c['@_X'] !== undefined ? parseInt(String(c['@_X']), 10) : undefined;
+                    // If cell has no X attribute (full-width cell), it matches any button at this Y
+                    if (cellX === undefined) {
+                        return true;
+                    }
+                    // Otherwise, check exact X match
+                    return cellX === pos.x;
                 });
                 if (cell) {
                     const contentType = cell.Content?.ContentType || cell.Content?.contentType;
@@ -2390,11 +2383,14 @@ class GridsetProcessor extends BaseProcessor {
                     // 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>
+                        // Format: <Text><p><s><r>label</r></s></p></Text>
+                        // Note: <p> wrapper is required by Grid 3's WordList format
                         newWordListItems.push({
                             Text: {
-                                s: {
-                                    r: button.label,
+                                p: {
+                                    s: {
+                                        r: button.label,
+                                    },
                                 },
                             },
                             Image: '', // No image for user-added words
@@ -2421,23 +2417,9 @@ class GridsetProcessor extends BaseProcessor {
                     originalGrid.Grid.WordList.Items.WordListItem = allItems;
                 }
             }
-            // Build the updated grid XML and convert to Windows line endings
+            // Build the updated grid XML and format for Grid 3 compatibility
             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>');
+            builtXml = formatGrid3XmlComplete(builtXml);
             newGridFiles.set(gridPath, builtXml);
         }
         // Copy all files from original zip, replacing modified grid files
@@ -2506,57 +2488,14 @@ class GridsetProcessor extends BaseProcessor {
             // Preserve Grid 3 XML formatting requirements
             suppressBooleanAttributes: false,
         });
-        // Build the grid XML and convert to Windows line endings for Grid 3 compatibility
+        // Build the grid XML and format 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>');
+        builtXml = formatGrid3XmlComplete(builtXml);
         return builtXml;
     }
     // Helper method to find button position with span information
     findButtonPosition(page, button, fallbackIndex) {
-        if (page.grid && page.grid.length > 0) {
-            // Search for button in grid layout and calculate span
-            for (let y = 0; y < page.grid.length; y++) {
-                for (let x = 0; x < page.grid[y].length; x++) {
-                    const current = page.grid[y][x];
-                    if (current && current.id === button.id) {
-                        // Calculate span by checking how far the same button extends
-                        let columnSpan = 1;
-                        let rowSpan = 1;
-                        // Check column span (rightward)
-                        while (x + columnSpan < page.grid[y].length) {
-                            const right = page.grid[y][x + columnSpan];
-                            if (right && right.id === button.id) {
-                                columnSpan++;
-                            }
-                            else {
-                                break;
-                            }
-                        }
-                        // Check row span (downward)
-                        while (y + rowSpan < page.grid.length) {
-                            const below = page.grid[y + rowSpan][x];
-                            if (below && below.id === button.id) {
-                                rowSpan++;
-                            }
-                            else {
-                                break;
-                            }
-                        }
-                        return { x, y, columnSpan, rowSpan };
-                    }
-                }
-            }
-        }
-        // Fallback positioning
-        const gridCols = page.grid?.[0]?.length || Math.ceil(Math.sqrt(page.buttons.length));
-        return {
-            x: fallbackIndex % gridCols,
-            y: Math.floor(fallbackIndex / gridCols),
-            columnSpan: 1,
-            rowSpan: 1,
-        };
+        return findButtonPos(page, button, fallbackIndex);
     }
     /**
      * Extract strings with metadata for aac-tools-platform compatibility