@willwade/aac-processors 0.2.10 → 0.2.12

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,46 @@ class GridsetProcessor extends BaseProcessor {
                     originalGrid.Grid.WordList.Items.WordListItem = allItems;
                 }
             }
-            // Build the updated grid XML and convert to Windows line endings
+            // Process WordList items attached to the page (from personalisation)
+            // These are tracked separately and shouldn't create new cells
+            // Use a known symbol key to check for WordList items
+            const WORDLIST_ITEMS_KEY = 'wordListItems';
+            const wordListItems = page[WORDLIST_ITEMS_KEY];
+            if (wordListItems && wordListItems.length > 0) {
+                // Ensure WordList structure exists
+                if (!originalGrid.Grid) {
+                    originalGrid.Grid = {};
+                }
+                if (!originalGrid.Grid.WordList) {
+                    originalGrid.Grid.WordList = {};
+                }
+                if (!originalGrid.Grid.WordList.Items) {
+                    originalGrid.Grid.WordList.Items = {};
+                }
+                const existingItems = originalGrid.Grid.WordList.Items.WordListItem ||
+                    originalGrid.Grid.WordList.Items.wordlistitem ||
+                    [];
+                const itemsArray = Array.isArray(existingItems) ? existingItems : [existingItems];
+                // Add new WordList items with proper Grid 3 format
+                for (const item of wordListItems) {
+                    itemsArray.push({
+                        Text: {
+                            p: {
+                                s: {
+                                    r: item.label,
+                                },
+                            },
+                        },
+                        Image: '',
+                        PartOfSpeech: 'Unknown',
+                    });
+                }
+                // Update the WordList
+                originalGrid.Grid.WordList.Items.WordListItem = itemsArray;
+            }
+            // 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 +2525,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

package/dist/browser/utils/sqlite.js

@@ -80,7 +80,9 @@ export async function openSqliteDatabase(input, options = {}) {
             throw new Error('SQLite file paths are not supported in browser environments.');
         }
         const Database = getBetterSqlite3();
-        const db = new Database(input, { readonly: options.readonly ?? true });
+        const db = new Database(input, {
+            readonly: options.readonly ?? true,
+        });
         return { db };
     }
     const data = await readBinaryFromInput(input);
@@ -93,7 +95,9 @@ export async function openSqliteDatabase(input, options = {}) {
     const dbPath = join(tempDir, 'input.sqlite');
     await writeBinaryToPath(dbPath, data);
     const Database = getBetterSqlite3();
-    const db = new Database(dbPath, { readonly: options.readonly ?? true });
+    const db = new Database(dbPath, {
+        readonly: options.readonly ?? true,
+    });
     const cleanup = async () => {
         try {
             db.close();

package/dist/processors/gridset/cellHelpers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Grid3 Cell Helpers
+ *
+ * Utilities for working with Grid 3 cells, including finding button positions
+ * and calculating cell spans in grid layouts.
+ */
+import type { AACPage, AACButton } from '../../core/treeStructure';
+/**
+ * Cell position with span information
+ */
+export interface CellPosition {
+    /** X coordinate (column) */
+    x: number;
+    /** Y coordinate (row) */
+    y: number;
+    /** Number of columns the cell spans */
+    columnSpan: number;
+    /** Number of rows the cell spans */
+    rowSpan: number;
+}
+/**
+ * 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 declare function findButtonPosition(page: AACPage, button: AACButton, fallbackIndex: number): CellPosition;
+/**
+ * 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 declare function cellPositionKey(x: number, y: number): string;
+/**
+ * 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 declare function parseCellPositionKey(key: string): {
+    x: number;
+    y: number;
+};

package/dist/processors/gridset/cellHelpers.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Grid3 Cell Helpers
+ *
+ * Utilities for working with Grid 3 cells, including finding button positions
+ * and calculating cell spans in grid layouts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findButtonPosition = findButtonPosition;
+exports.cellPositionKey = cellPositionKey;
+exports.parseCellPositionKey = parseCellPositionKey;
+/**
+ * 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}`);
+ */
+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"
+ */
+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 }
+ */
+function parseCellPositionKey(key) {
+    const [x, y] = key.split(',').map(Number);
+    return { x, y };
+}

package/dist/processors/gridset/gridCalculations.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Grid3 Grid Calculations
+ *
+ * Utilities for calculating grid dimensions and definitions
+ * based on page layout and button count.
+ */
+import type { AACPage } from '../../core/treeStructure';
+/**
+ * Grid definition structure for Grid 3 XML
+ */
+export interface GridDefinitions {
+    ColumnDefinition: any[];
+}
+export interface RowDefinitions {
+    RowDefinition: any[];
+}
+/**
+ * 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 declare function calculateColumnDefinitions(page: AACPage): GridDefinitions;
+/**
+ * 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 declare function calculateRowDefinitions(page: AACPage, addWorkspaceOffset?: boolean): RowDefinitions;

package/dist/processors/gridset/gridCalculations.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Grid3 Grid Calculations
+ *
+ * Utilities for calculating grid dimensions and definitions
+ * based on page layout and button count.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateColumnDefinitions = calculateColumnDefinitions;
+exports.calculateRowDefinitions = calculateRowDefinitions;
+/**
+ * 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
+ */
+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
+ */
+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/processors/gridset/helpers.js

@@ -167,7 +167,10 @@ function getCommonDocumentsPath() {
         // Query registry for Common Documents path
         const child_process = (0, io_1.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/processors/gridset/wordlistHelpers.js

@@ -69,9 +69,10 @@ function wordlistToXml(wordlist) {
     const items = wordlist.items.map((item) => ({
         WordListItem: {
             Text: {
-                s: {
-                    '@_Image': item.image || '',
-                    r: item.text,
+                p: {
+                    s: {
+                        r: item.text,
+                    },
                 },
             },
             Image: item.image || '',
@@ -137,7 +138,7 @@ async function extractWordlists(gridsetBuffer, password = (0, password_1.resolve
                             ? [itemsContainer.WordListItem]
                             : [];
                     const items = itemArray.map((item) => ({
-                        text: item.Text?.s?.r || item.text?.s?.r || '',
+                        text: item.Text?.p?.s?.r || item.Text?.s?.r || item.text?.p?.s?.r || item.text?.s?.r || '',
                         image: item.Image || item.image || undefined,
                         partOfSpeech: item.PartOfSpeech || item.partOfSpeech || 'Unknown',
                     }));
@@ -202,9 +203,10 @@ async function updateWordlist(gridsetBuffer, gridName, wordlist, password = (0,
                     const items = wordlist.items.map((item) => ({
                         WordListItem: {
                             Text: {
-                                s: {
-                                    '@_Image': item.image || '',
-                                    r: item.text,
+                                p: {
+                                    s: {
+                                        r: item.text,
+                                    },
                                 },
                             },
                             Image: item.image || '',

package/dist/processors/gridset/xmlFormatter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function formatGrid3Xml(xml: string): string;
+/**
+ * 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 declare function formatEmptyCaptionsWithCdata(xml: string): string;
+/**
+ * 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 declare function formatGrid3XmlComplete(xml: string): string;

package/dist/processors/gridset/xmlFormatter.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatGrid3Xml = formatGrid3Xml;
+exports.formatEmptyCaptionsWithCdata = formatEmptyCaptionsWithCdata;
+exports.formatGrid3XmlComplete = formatGrid3XmlComplete;
+/**
+ * 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>'
+ */
+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
+ */
+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
+ */
+function formatGrid3XmlComplete(xml) {
+    let formatted = formatGrid3Xml(xml);
+    formatted = formatEmptyCaptionsWithCdata(formatted);
+    return formatted;
+}

package/dist/processors/gridsetProcessor.js

@@ -31,6 +31,9 @@ const resolver_1 = require("./gridset/resolver");
 const translationProcessor_1 = require("../utilities/translation/translationProcessor");
 const password_1 = require("./gridset/password");
 const crypto_1 = require("./gridset/crypto");
+const xmlFormatter_1 = require("./gridset/xmlFormatter");
+const gridCalculations_1 = require("./gridset/gridCalculations");
+const cellHelpers_1 = require("./gridset/cellHelpers");
 const gridsetValidator_1 = require("../validation/gridsetValidator");
 // New imports for enhanced Grid 3 support
 const pluginTypes_1 = require("./gridset/pluginTypes");
@@ -2221,33 +2224,11 @@ class GridsetProcessor extends baseProcessor_1.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 (0, gridCalculations_1.calculateColumnDefinitions)(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 (0, gridCalculations_1.calculateRowDefinitions)(page, addWorkspaceOffset);
     }
     /**
      * Save a modified tree while preserving all original files (settings, images, assets)
@@ -2393,6 +2374,9 @@ class GridsetProcessor extends baseProcessor_1.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 = [];
@@ -2405,9 +2389,18 @@ class GridsetProcessor extends baseProcessor_1.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;
@@ -2416,11 +2409,14 @@ class GridsetProcessor extends baseProcessor_1.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
@@ -2447,23 +2443,46 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                     originalGrid.Grid.WordList.Items.WordListItem = allItems;
                 }
             }
-            // Build the updated grid XML and convert to Windows line endings
+            // Process WordList items attached to the page (from personalisation)
+            // These are tracked separately and shouldn't create new cells
+            // Use a known symbol key to check for WordList items
+            const WORDLIST_ITEMS_KEY = 'wordListItems';
+            const wordListItems = page[WORDLIST_ITEMS_KEY];
+            if (wordListItems && wordListItems.length > 0) {
+                // Ensure WordList structure exists
+                if (!originalGrid.Grid) {
+                    originalGrid.Grid = {};
+                }
+                if (!originalGrid.Grid.WordList) {
+                    originalGrid.Grid.WordList = {};
+                }
+                if (!originalGrid.Grid.WordList.Items) {
+                    originalGrid.Grid.WordList.Items = {};
+                }
+                const existingItems = originalGrid.Grid.WordList.Items.WordListItem ||
+                    originalGrid.Grid.WordList.Items.wordlistitem ||
+                    [];
+                const itemsArray = Array.isArray(existingItems) ? existingItems : [existingItems];
+                // Add new WordList items with proper Grid 3 format
+                for (const item of wordListItems) {
+                    itemsArray.push({
+                        Text: {
+                            p: {
+                                s: {
+                                    r: item.label,
+                                },
+                            },
+                        },
+                        Image: '',
+                        PartOfSpeech: 'Unknown',
+                    });
+                }
+                // Update the WordList
+                originalGrid.Grid.WordList.Items.WordListItem = itemsArray;
+            }
+            // 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 = (0, xmlFormatter_1.formatGrid3XmlComplete)(builtXml);
             newGridFiles.set(gridPath, builtXml);
         }
         // Copy all files from original zip, replacing modified grid files
@@ -2532,57 +2551,14 @@ class GridsetProcessor extends baseProcessor_1.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 = (0, xmlFormatter_1.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 (0, cellHelpers_1.findButtonPosition)(page, button, fallbackIndex);
     }
     /**
      * Extract strings with metadata for aac-tools-platform compatibility

package/dist/utils/sqlite.js

@@ -85,7 +85,9 @@ async function openSqliteDatabase(input, options = {}) {
             throw new Error('SQLite file paths are not supported in browser environments.');
         }
         const Database = getBetterSqlite3();
-        const db = new Database(input, { readonly: options.readonly ?? true });
+        const db = new Database(input, {
+            readonly: options.readonly ?? true,
+        });
         return { db };
     }
     const data = await readBinaryFromInput(input);
@@ -98,7 +100,9 @@ async function openSqliteDatabase(input, options = {}) {
     const dbPath = join(tempDir, 'input.sqlite');
     await writeBinaryToPath(dbPath, data);
     const Database = getBetterSqlite3();
-    const db = new Database(dbPath, { readonly: options.readonly ?? true });
+    const db = new Database(dbPath, {
+        readonly: options.readonly ?? true,
+    });
     const cleanup = async () => {
         try {
             db.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "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",