@willwade/aac-processors 0.0.15 → 0.0.17

package/README.md

@@ -94,7 +94,7 @@ This step is only required for Electron apps; regular Node.js consumers do not n
 
 ## 🔧 Quick Start
 
-### Basic Usage (TypeScript/ES6)
+### Basic Usage (TypeScript)
 
 ```typescript
 import {
@@ -118,15 +118,20 @@ const aacTree = dotProcessor.loadIntoTree("examples/example.dot");
 console.log("Pages:", Object.keys(aacTree.pages).length);
 ```
 
-### Basic Usage (CommonJS)
+### Platform Support
 
-```javascript
-const { getProcessor, DotProcessor } = require("aac-processors");
+**AACProcessors is designed for Node.js environments only.** It requires Node.js v20+ and cannot run in browsers due to:
 
-const processor = getProcessor("board.dot");
-const tree = processor.loadIntoTree("board.dot");
-console.log(tree);
-```
+- **File system access** - Required for reading/writing AAC files
+- **Native SQLite** - Used by Snap, TouchChat, and Analytics features
+- **Binary format processing** - ZIP, encrypted formats, etc.
+
+**For browser-based AAC display**, consider these alternatives:
+- **obf-renderer** - Display OBF/OBZ files in web apps
+- **Arc Core** - Browser-based AAC communication
+- **Cboard** - Web-based AAC display system
+
+This library focuses on **server-side file processing**, not client-side rendering.
 
 ### Button Filtering System
 
@@ -893,3 +898,7 @@ Inspired by the Python AACProcessors project
 ### Contributing
 
 Want to help with any of these items? See our [Contributing Guidelines](#-contributing) and pick an issue that interests you!
+
+### Credits
+
+Some of the OBF work is directly from https://github.com/open-aac/obf and https://github.com/open-aac/aac-metrics - OBLA too https://www.openboardformat.org/logs 

package/dist/core/treeStructure.d.ts

@@ -86,6 +86,7 @@ export interface AACSemanticAction {
         touchChat?: {
             actionCode: number;
             actionData: string;
+            resourceId?: number;
         };
         snap?: {
             navigatePageId?: number;

package/dist/processors/gridset/commands.js

@@ -699,6 +699,21 @@ exports.GRID3_COMMANDS = {
         description: 'Clear word prediction buffer',
         platforms: ['desktop', 'ios', 'medicare', 'medicareBionics'],
     },
+    'Prediction.PredictThis': {
+        id: 'Prediction.PredictThis',
+        category: Grid3CommandCategory.AUTO_CONTENT,
+        pluginId: 'prediction',
+        displayName: 'Predict This',
+        description: 'Provide suggestions based on word list',
+        parameters: [
+            {
+                key: 'wordlist',
+                type: 'string', // Actually highly structured, but string type is a placeholder
+                required: true,
+                description: 'Word list for prediction',
+            },
+        ],
+    },
     'Grammar.Change': {
         id: 'Grammar.Change',
         category: Grid3CommandCategory.AUTO_CONTENT,

package/dist/processors/gridset/pluginTypes.js

@@ -128,12 +128,12 @@ function detectPluginCellType(content) {
     }
     // AutoContent detection - dynamic word/content suggestions
     if (contentType === 'AutoContent' || content.Style?.BasedOnStyle === 'AutoContent') {
-        const autoContentType = extractAutoContentType(content);
+        const autoContentType = extractAutoContentType(content) || contentSubType;
         return {
             cellType: Grid3CellType.AutoContent,
-            autoContentType: autoContentType || undefined,
-            pluginId: inferAutoContentPlugin(autoContentType),
-            displayName: autoContentType || 'Auto Content',
+            autoContentType: autoContentType ? String(autoContentType) : undefined,
+            pluginId: inferAutoContentPlugin(autoContentType ? String(autoContentType) : undefined),
+            displayName: autoContentType ? String(autoContentType) : 'Auto Content',
         };
     }
     // Regular cell

package/dist/processors/gridsetProcessor.d.ts

@@ -12,6 +12,10 @@ declare class GridsetProcessor extends BaseProcessor {
     private decryptGridsetEntry;
     private getGridsetPassword;
     private ensureAlphaChannel;
+    /**
+     * Extract words from Grid3 WordList structure
+     */
+    private _extractWordsFromWordList;
     private generateCommandsFromSemanticAction;
     private convertGrid3StyleToAACStyle;
     private getStyleById;

package/dist/processors/gridsetProcessor.js

@@ -74,6 +74,35 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         // Invalid or unknown format, return white
         return '#FFFFFFFF';
     }
+    /**
+     * Extract words from Grid3 WordList structure
+     */
+    _extractWordsFromWordList(param) {
+        if (!param)
+            return [];
+        // Sometimes the param itself is the WordList, sometimes it has a WordList property
+        const wordList = param.WordList || param.wordlist || (param.Items || param.items ? param : undefined);
+        if (!wordList || !(wordList.Items || wordList.items))
+            return [];
+        const items = wordList.Items?.WordListItem || wordList.items?.wordlistitem || [];
+        const itemArr = Array.isArray(items) ? items : [items];
+        const words = [];
+        for (const item of itemArr) {
+            const text = item.Text || item.text;
+            if (text) {
+                const val = this.textOf(text);
+                if (val)
+                    words.push(val);
+            }
+            else if (item['#text'] !== undefined) {
+                words.push(String(item['#text']));
+            }
+            else if (typeof item === 'string') {
+                words.push(item);
+            }
+        }
+        return words;
+    }
     // Helper function to generate Grid3 commands from semantic actions
     generateCommandsFromSemanticAction(button, tree) {
         const semanticAction = button.semanticAction;
@@ -280,8 +309,45 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
             return undefined;
         if (typeof val === 'string')
             return val;
-        if (typeof val === 'object' && '#text' in val)
-            return String(val['#text']);
+        if (typeof val === 'number')
+            return String(val);
+        if (typeof val === 'object') {
+            if ('#text' in val)
+                return String(val['#text']);
+            // Handle Grid3 structured format <p><s><r>text</r></s></p>
+            // Can start at p, s, or r level
+            const parts = [];
+            const processS = (s) => {
+                if (!s)
+                    return;
+                if (s.r !== undefined) {
+                    const rElements = Array.isArray(s.r) ? s.r : [s.r];
+                    for (const r of rElements) {
+                        if (typeof r === 'object' && r !== null && '#text' in r) {
+                            parts.push(String(r['#text']));
+                        }
+                        else {
+                            parts.push(String(r));
+                        }
+                    }
+                }
+            };
+            if (val.p) {
+                const p = val.p;
+                const sElements = Array.isArray(p.s) ? p.s : p.s ? [p.s] : [];
+                sElements.forEach(processS);
+            }
+            else if (val.s) {
+                const sElements = Array.isArray(val.s) ? val.s : [val.s];
+                sElements.forEach(processS);
+            }
+            else if (val.r !== undefined) {
+                processS(val);
+            }
+            if (parts.length > 0) {
+                return parts.join('').trim();
+            }
+        }
         return undefined;
     }
     extractTexts(filePathOrBuffer) {
@@ -404,15 +470,21 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                     if (!grid)
                         return;
                     const gridId = this.textOf(grid.GridGuid || grid.gridGuid || grid.id);
-                    let gridName = this.textOf(grid.Name) || this.textOf(grid.name) || this.textOf(grid['@_Name']);
-                    if (!gridName) {
-                        const match = entry.entryName.match(/^Grids\/([^/]+)\//);
-                        if (match)
-                            gridName = match[1];
-                    }
-                    if (gridId && gridName) {
-                        gridNameToIdMap.set(gridName, gridId);
-                        gridIdToNameMap.set(gridId, gridName);
+                    const gridName = this.textOf(grid.Name) || this.textOf(grid.name) || this.textOf(grid['@_Name']);
+                    const folderMatch = entry.entryName.match(/^Grids\/([^/]+)\//);
+                    const folderName = folderMatch ? folderMatch[1] : undefined;
+                    if (gridId) {
+                        if (gridName) {
+                            gridNameToIdMap.set(gridName, gridId);
+                            gridIdToNameMap.set(gridId, gridName);
+                        }
+                        if (folderName) {
+                            // Folder name is often used as the grid name in Jump.To commands
+                            gridNameToIdMap.set(folderName, gridId);
+                            if (!gridName) {
+                                gridIdToNameMap.set(gridId, folderName);
+                            }
+                        }
                     }
                 }
                 catch (e) {
@@ -483,6 +555,32 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                     for (let r = 0; r < maxRows; r++) {
                         gridLayout[r] = new Array(maxCols).fill(null);
                     }
+                    const pagePredictedWords = new Set();
+                    // Extract words from grid-level AutoContentCommands (e.g., Prediction Bar)
+                    if (grid.AutoContentCommands) {
+                        const collections = grid.AutoContentCommands.AutoContentCommandCollection;
+                        const collectionArr = Array.isArray(collections)
+                            ? collections
+                            : collections
+                                ? [collections]
+                                : [];
+                        collectionArr.forEach((collection) => {
+                            const commands = collection.Commands?.Command;
+                            const commandArr = Array.isArray(commands) ? commands : commands ? [commands] : [];
+                            commandArr.forEach((command) => {
+                                const commandId = command['@_ID'] || command.ID || command.id;
+                                if (commandId === 'Prediction.PredictThis') {
+                                    const params = command.Parameter;
+                                    const paramArr = Array.isArray(params) ? params : params ? [params] : [];
+                                    const wordListParam = paramArr.find((p) => (p['@_Key'] || p.Key || p.key) === 'wordlist');
+                                    if (wordListParam) {
+                                        const words = this._extractWordsFromWordList(wordListParam);
+                                        words.forEach((w) => pagePredictedWords.add(w));
+                                    }
+                                }
+                            });
+                        });
+                    }
                     cellArr.forEach((cell, idx) => {
                         if (!cell || !cell.Content)
                             return;
@@ -526,7 +624,7 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                         // Extract label from CaptionAndImage/Caption
                         const content = cell.Content;
                         const captionAndImage = content.CaptionAndImage || content.captionAndImage;
-                        let label = captionAndImage?.Caption || captionAndImage?.caption || '';
+                        let label = this.textOf(captionAndImage?.Caption || captionAndImage?.caption) || '';
                         // Check if cell has an image/symbol (needed to decide if we should keep it)
                         const hasImageCandidate = !!(captionAndImage?.Image ||
                             captionAndImage?.image ||
@@ -586,6 +684,25 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                         if (commands) {
                             const commandArr = Array.isArray(commands) ? commands : [commands];
                             detectedCommands = commandArr.map((cmd) => (0, commands_1.detectCommand)(cmd));
+                            // Scan all commands for vocabulary (predictions) before identifying primary action
+                            commandArr.forEach((cmd) => {
+                                const id = cmd['@_ID'] || cmd.ID || cmd.id;
+                                if (id === 'Prediction.PredictThis') {
+                                    const params = cmd.Parameter || cmd.parameter;
+                                    const pArr = params ? (Array.isArray(params) ? params : [params]) : [];
+                                    let wlP;
+                                    for (const p of pArr) {
+                                        if (p['@_Key'] === 'wordlist' || p.Key === 'wordlist' || p.key === 'wordlist') {
+                                            wlP = p;
+                                            break;
+                                        }
+                                    }
+                                    if (wlP) {
+                                        const words = this._extractWordsFromWordList(wlP);
+                                        words.forEach((w) => pagePredictedWords.add(w));
+                                    }
+                                }
+                            });
                             for (const command of commandArr) {
                                 const commandId = command['@_ID'] || command.ID || command.id;
                                 const parameters = command.Parameter || command.parameter;
@@ -594,50 +711,52 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                         ? parameters
                                         : [parameters]
                                     : [];
-                                // Helper to extract text from Grid3's structured format <p><s><r>text</r></s></p>
-                                const extractStructuredText = (param) => {
-                                    // Try to extract from nested p.s structure
-                                    if (param.p) {
-                                        const p = param.p;
-                                        // Handle p.s array or single s element
-                                        const sElements = Array.isArray(p.s) ? p.s : p.s ? [p.s] : [];
-                                        // Extract all r values and concatenate
-                                        const parts = [];
-                                        for (const s of sElements) {
-                                            if (s && s.r !== undefined) {
-                                                parts.push(String(s.r));
-                                            }
-                                        }
-                                        if (parts.length > 0) {
-                                            return parts.join('');
+                                // Helper to get raw parameter object
+                                const getRawParam = (key) => {
+                                    for (const param of paramArr) {
+                                        if (param['@_Key'] === key || param.Key === key || param.key === key) {
+                                            return param;
                                         }
                                     }
                                     return undefined;
                                 };
                                 // Helper to get parameter value
                                 const getParam = (key) => {
-                                    if (!parameters)
+                                    const param = getRawParam(key);
+                                    if (param === undefined)
                                         return undefined;
-                                    for (const param of paramArr) {
-                                        if (param['@_Key'] === key || param.Key === key || param.key === key) {
-                                            // First try simple #text value
-                                            const simpleValue = param['#text'] ?? param.text ?? param.value;
-                                            if (typeof simpleValue === 'string') {
-                                                return simpleValue;
-                                            }
-                                            // Try to extract from structured format (Grid3's <p><s><r> format)
-                                            const structuredValue = extractStructuredText(param);
-                                            if (structuredValue !== undefined) {
-                                                return structuredValue;
-                                            }
-                                            // Fallback to string conversion
-                                            if (typeof param === 'string') {
-                                                return param;
-                                            }
-                                        }
-                                    }
+                                    const simpleValue = param['#text'] ?? param.text ?? param.value;
+                                    if (typeof simpleValue === 'string')
+                                        return simpleValue;
+                                    if (typeof simpleValue === 'number')
+                                        return String(simpleValue);
+                                    const structuredValue = this.textOf(param);
+                                    if (structuredValue !== undefined)
+                                        return structuredValue;
+                                    if (typeof param === 'string')
+                                        return param;
                                     return undefined;
                                 };
+                                // Skip PredictThis in primary action loop as it was handled in pre-pass
+                                // unless we need a primary action and nothing else exists
+                                if (commandId === 'Prediction.PredictThis') {
+                                    if (!semanticAction) {
+                                        const wlParam = getRawParam('wordlist');
+                                        if (wlParam) {
+                                            const words = this._extractWordsFromWordList(wlParam);
+                                            semanticAction = {
+                                                category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                                intent: treeStructure_1.AACSemanticIntent.PLATFORM_SPECIFIC,
+                                                text: words.slice(0, 3).join(', '),
+                                                platformData: {
+                                                    grid3: { commandId, parameters: { wordlist: words } },
+                                                },
+                                                fallback: { type: 'ACTION', message: 'Predict words' },
+                                            };
+                                        }
+                                    }
+                                    continue;
+                                }
                                 switch (commandId) {
                                     case 'Jump.To': {
                                         const gridTarget = getParam('grid');
@@ -689,10 +808,13 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                         };
                                         break;
                                     case 'Jump.Home':
+                                    case 'Jump.SetHome':
                                         // action
+                                        navigationTarget = tree.rootId || undefined;
                                         semanticAction = {
                                             category: treeStructure_1.AACSemanticCategory.NAVIGATION,
                                             intent: treeStructure_1.AACSemanticIntent.GO_HOME,
+                                            targetId: tree.rootId || undefined,
                                             platformData: {
                                                 grid3: {
                                                     commandId,
@@ -708,6 +830,79 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                             type: 'GO_HOME',
                                         };
                                         break;
+                                    case 'Jump.ToKeyboard': {
+                                        // Navigate to the set keyboard if we found one in settings
+                                        const keyboardGridName = tree.keyboardGridName;
+                                        const keyboardPageId = gridNameToIdMap.get(keyboardGridName);
+                                        if (keyboardPageId) {
+                                            navigationTarget = keyboardPageId;
+                                        }
+                                        semanticAction = {
+                                            category: treeStructure_1.AACSemanticCategory.NAVIGATION,
+                                            intent: treeStructure_1.AACSemanticIntent.GO_HOME, // Close enough to 'navigation to keyboard'
+                                            targetId: keyboardPageId,
+                                            platformData: {
+                                                grid3: {
+                                                    commandId,
+                                                    parameters: {},
+                                                },
+                                            },
+                                            fallback: {
+                                                type: 'NAVIGATE',
+                                                targetPageId: keyboardPageId,
+                                            },
+                                        };
+                                        break;
+                                    }
+                                    case 'Action.InsertTextAndSpeak': {
+                                        const insertText = getParam('text');
+                                        semanticAction = {
+                                            category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                            intent: treeStructure_1.AACSemanticIntent.SPEAK_IMMEDIATE,
+                                            text: insertText,
+                                            platformData: {
+                                                grid3: {
+                                                    commandId,
+                                                    parameters: { text: insertText },
+                                                },
+                                            },
+                                            fallback: {
+                                                type: 'SPEAK',
+                                                message: insertText,
+                                            },
+                                        };
+                                        break;
+                                    }
+                                    case 'Prediction.PredictThis': {
+                                        const wlParam = getRawParam('wordlist');
+                                        if (wlParam) {
+                                            const words = this._extractWordsFromWordList(wlParam);
+                                            // Add to page-wide set of predicted words
+                                            words.forEach((w) => pagePredictedWords.add(w));
+                                            // Store words in a way that analyzer can find them
+                                            // For now, we'll attach to semanticAction so it can be used later
+                                            // We only set this as the primary action if we don't have one yet
+                                            if (!semanticAction) {
+                                                semanticAction = {
+                                                    category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                                    intent: treeStructure_1.AACSemanticIntent.PLATFORM_SPECIFIC,
+                                                    text: words.slice(0, 3).join(', '), // Provide first few as preview
+                                                    platformData: {
+                                                        grid3: {
+                                                            commandId,
+                                                            parameters: { wordlist: words },
+                                                        },
+                                                    },
+                                                    fallback: {
+                                                        type: 'ACTION',
+                                                        message: 'Predict words',
+                                                    },
+                                                };
+                                            }
+                                        }
+                                        // Continue to check other commands (e.g. Action.InsertText)
+                                        continue;
+                                    }
                                     case 'Action.Speak': {
                                         // speak
                                         const speakUnit = getParam('unit');
@@ -963,6 +1158,19 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                             if (content.Style.FontSize)
                                 inlineStyle.fontSize = parseInt(String(content.Style.FontSize));
                         }
+                        // Extract grammar tags from commands (Smart Grammar)
+                        const grammar = {};
+                        detectedCommands.forEach((cmd) => {
+                            if (cmd.parameters.pos)
+                                grammar.pos = cmd.parameters.pos;
+                            if (cmd.parameters.person)
+                                grammar.person = cmd.parameters.person;
+                            if (cmd.parameters.number)
+                                grammar.number = cmd.parameters.number;
+                            if (cmd.parameters.feature)
+                                grammar.feature = cmd.parameters.feature;
+                        });
+                        const isSmartGrammarCell = Object.keys(grammar).length > 0;
                         const button = new treeStructure_1.AACButton({
                             id: `${gridId}_btn_${idx}`,
                             label: String(label),
@@ -998,6 +1206,8 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                 pluginMetadata: pluginMetadata, // Store full plugin metadata for future use
                                 grid3Commands: detectedCommands, // Store detected command metadata
                                 symbolLibraryRef: symbolLibraryRef, // Store full symbol reference
+                                grammar: isSmartGrammarCell ? grammar : undefined,
+                                isSmartGrammarCell: isSmartGrammarCell,
                             },
                         });
                         // Add button to page
@@ -1011,6 +1221,59 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                             }
                         }
                     });
+                    // Process predicted words: Populate AutoContent slots first, then add virtual buttons at bottom
+                    if (pagePredictedWords.size > 0) {
+                        const extraWords = Array.from(pagePredictedWords).filter((w) => w.trim().length > 0);
+                        if (extraWords.length > 0) {
+                            let wordIdx = 0;
+                            // Step 1: Fill dedicated AutoContent prediction slots (e.g. at the top)
+                            page.buttons.forEach((btn) => {
+                                if (btn.contentType === 'AutoContent' &&
+                                    btn.contentSubType === 'Prediction' &&
+                                    wordIdx < extraWords.length) {
+                                    const word = extraWords[wordIdx++];
+                                    btn.label = word;
+                                    btn.message = word;
+                                    btn.semanticAction = {
+                                        category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                        intent: treeStructure_1.AACSemanticIntent.INSERT_TEXT,
+                                        text: word,
+                                        fallback: { type: 'SPEAK', message: word },
+                                    };
+                                }
+                            });
+                            // Step 2: Add remaining words as virtual buttons at the bottom
+                            if (wordIdx < extraWords.length) {
+                                const remainingWords = extraWords.slice(wordIdx);
+                                const extraRowsCount = Math.ceil(remainingWords.length / maxCols);
+                                for (let r = 0; r < extraRowsCount; r++) {
+                                    const row = new Array(maxCols).fill(null);
+                                    for (let c = 0; c < maxCols; c++) {
+                                        const idx = r * maxCols + c;
+                                        if (idx < remainingWords.length) {
+                                            const word = remainingWords[idx];
+                                            const vBtn = new treeStructure_1.AACButton({
+                                                id: `${gridId}_vpredict_${wordIdx + idx}`,
+                                                label: word,
+                                                message: word,
+                                                x: c,
+                                                y: maxRows + r,
+                                                semanticAction: {
+                                                    category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                                    intent: treeStructure_1.AACSemanticIntent.INSERT_TEXT,
+                                                    text: word,
+                                                    fallback: { type: 'SPEAK', message: word },
+                                                },
+                                            });
+                                            row[c] = vBtn;
+                                            page.addButton(vBtn);
+                                        }
+                                    }
+                                    gridLayout.push(row);
+                                }
+                            }
+                        }
+                    }
                     // Set the page's grid layout
                     page.grid = gridLayout;
                     // Generate clone_id for each button in the grid
@@ -1068,6 +1331,11 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                         tree.rootId = homeGridId;
                     }
                 }
+                const keyboardGridName = settingsData?.GridSetSettings?.KeyboardGrid ||
+                    settingsData?.gridSetSettings?.keyboardGrid;
+                if (keyboardGridName && typeof keyboardGridName === 'string') {
+                    tree.keyboardGridName = keyboardGridName;
+                }
             }
         }
         catch (e) {