@willwade/aac-processors 0.2.3 → 0.2.4

package/dist/browser/core/treeStructure.js

@@ -51,7 +51,7 @@ export var AACScanType;
     AACScanType["BLOCK_COLUMN_ROW"] = "block-column-row";
 })(AACScanType || (AACScanType = {}));
 export class AACButton {
-    constructor({ id, label = '', message = '', targetPageId, semanticAction, audioRecording, style, contentType, contentSubType, image, resolvedImageEntry, symbolLibrary, symbolPath, x, y, columnSpan, rowSpan, scanBlocks, scanBlock, visibility, directActivate, parameters, predictions, semantic_id, clone_id, 
+    constructor({ id, label = '', message = '', targetPageId, semanticAction, audioRecording, style, contentType, contentSubType, image, resolvedImageEntry, symbolLibrary, symbolPath, x, y, columnSpan, rowSpan, scanBlocks, scanBlock, visibility, directActivate, parameters, predictions, pos, wordForms, semantic_id, clone_id, 
     // Legacy input support
     type, action, }) {
         this.id = id;
@@ -77,6 +77,8 @@ export class AACButton {
         this.directActivate = directActivate;
         this.parameters = parameters;
         this.predictions = predictions;
+        this.pos = pos;
+        this.wordForms = wordForms;
         this.semantic_id = semantic_id;
         this.clone_id = clone_id;
         // Legacy mapping: if no semanticAction provided, derive from legacy `action` first

package/dist/browser/metrics.js

@@ -12,6 +12,8 @@ export { MetricsCalculator } from './utilities/analytics/metrics/core';
 export { VocabularyAnalyzer } from './utilities/analytics/metrics/vocabulary';
 export { SentenceAnalyzer } from './utilities/analytics/metrics/sentence';
 export { ComparisonAnalyzer } from './utilities/analytics/metrics/comparison';
+export { MorphologyEngine } from './utilities/analytics/morphology';
+export { WordFormGenerator } from './utilities/analytics/morphology';
 export { ReferenceLoader } from './utilities/analytics/reference';
 export { InMemoryReferenceLoader, createBrowserReferenceLoader, loadReferenceDataFromUrl, } from './utilities/analytics/reference/browser';
 export * from './utilities/analytics/utils/idGenerator';

package/dist/browser/processors/astericsGridProcessor.js

@@ -605,7 +605,7 @@ class AstericsGridProcessor extends BaseProcessor {
                 });
             });
         }
-        catch (error) {
+        catch (_error) {
             // If JSON parsing fails, return empty array
         }
         return texts;
@@ -1021,7 +1021,7 @@ class AstericsGridProcessor extends BaseProcessor {
                 // Use detected format for filename
                 imageName = element.image.id || `image.${imageFormat}`;
             }
-            catch (e) {
+            catch (_e) {
                 // Invalid base64 data, skip image
             }
         }
@@ -1034,19 +1034,23 @@ class AstericsGridProcessor extends BaseProcessor {
             audioRecording: audioRecording,
             visibility: mapAstericsVisibility(element.hidden),
             image: imageName, // Store image filename/reference
-            parameters: imageData
-                ? {
-                    ...{ imageData: imageData }, // Store actual image data in parameters for conversion
-                }
-                : undefined,
             style: {
                 backgroundColor: finalBackgroundColor,
                 borderColor: colorStyles.borderColor || colorConfig?.elementBorderColor || '#CCCCCC',
                 borderWidth: colorConfig?.borderWidth || 1,
                 fontFamily: colorConfig?.fontFamily || 'Arial',
-                fontSize: colorConfig?.fontSizePct ? colorConfig.fontSizePct * 16 : 16, // Default to 16px
+                fontSize: colorConfig?.fontSizePct ? colorConfig.fontSizePct * 16 : 16,
                 fontColor: fontColor,
             },
+            wordForms: element.wordForms && element.wordForms.length > 0 ? element.wordForms : undefined,
+            parameters: {
+                ...(imageData ? { imageData: imageData } : {}),
+                ...(element.actions?.some((a) => a.modelName === 'GridActionWordForm')
+                    ? {
+                        wordFormActions: element.actions.filter((a) => a.modelName === 'GridActionWordForm'),
+                    }
+                    : {}),
+            },
         });
     }
     async processTexts(filePathOrBuffer, translations, outputPath) {
@@ -1313,6 +1317,11 @@ class AstericsGridProcessor extends BaseProcessor {
                     });
                 }
                 const locale = tree.metadata?.locale || 'en';
+                if (button.parameters?.wordFormActions &&
+                    Array.isArray(button.parameters.wordFormActions)) {
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+                    actions.push(...button.parameters.wordFormActions);
+                }
                 return {
                     id: button.id,
                     modelName: 'GridElement',
@@ -1322,7 +1331,7 @@ class AstericsGridProcessor extends BaseProcessor {
                     x: calculatedX,
                     y: calculatedY,
                     label: { [locale]: button.label },
-                    wordForms: [],
+                    wordForms: button.wordForms || [],
                     image: {
                         data: null,
                         author: undefined,
@@ -1414,7 +1423,7 @@ class AstericsGridProcessor extends BaseProcessor {
                             audioAction.durationMs = parsedMetadata.durationMs || audioAction.durationMs;
                             audioAction.filename = parsedMetadata.filename || audioAction.filename;
                         }
-                        catch (e) {
+                        catch (_e) {
                             // Use defaults if metadata parsing fails
                         }
                     }
@@ -1466,7 +1475,7 @@ class AstericsGridProcessor extends BaseProcessor {
                 });
             });
         }
-        catch (error) {
+        catch (_error) {
             // If JSON parsing fails, return empty array
         }
         return elementIds;
@@ -1491,7 +1500,7 @@ class AstericsGridProcessor extends BaseProcessor {
                 }
             }
         }
-        catch (error) {
+        catch (_error) {
             // If JSON parsing fails, return false
         }
         return false;

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

@@ -66,7 +66,7 @@ export async function openImage(gridsetBuffer, entryPath, password = resolveGrid
         }
         return data;
     }
-    catch (error) {
+    catch (_error) {
         return null;
     }
 }
@@ -156,7 +156,7 @@ export function getCommonDocumentsPath() {
             return match[1].trim();
         }
     }
-    catch (error) {
+    catch (_error) {
         // Registry access failed, fall back to default
     }
     // Default fallback path
@@ -212,7 +212,7 @@ export async function findGrid3UserPaths(fileAdapter = defaultFileAdapter) {
             }
         }
     }
-    catch (error) {
+    catch (_error) {
         // Silently fail if directory access fails
     }
     return results;

package/dist/browser/processors/gridsetProcessor.js

@@ -462,7 +462,7 @@ class GridsetProcessor extends BaseProcessor {
                 }
             }
         }
-        catch (e) {
+        catch (_e) {
             /* ignore: optional FileMap.xml may be missing or malformed */
         }
         // First, load styles from Settings0/Styles/styles.xml (Grid3 format)
@@ -533,7 +533,7 @@ class GridsetProcessor extends BaseProcessor {
                 const normalizedEntry = imageEntry.entryName.replace(/\\/g, '/');
                 imageDataCache.set(normalizedEntry, data);
             }
-            catch (err) {
+            catch (_err) {
                 // Silently fail - individual image loading failures shouldn't break the entire load
             }
         }
@@ -566,7 +566,7 @@ class GridsetProcessor extends BaseProcessor {
                         }
                     }
                 }
-                catch (e) {
+                catch (_e) {
                     // Skip errors in first pass
                 }
             }
@@ -581,7 +581,7 @@ class GridsetProcessor extends BaseProcessor {
                     xmlContent = decodeText(buffer);
                     console.log(`[Gridset] Raw XML content (first 200 chars) for ${entry.entryName}:`, xmlContent.substring(0, 200));
                 }
-                catch (e) {
+                catch (_e) {
                     // Skip unreadable files
                     continue;
                 }
@@ -940,6 +940,7 @@ class GridsetProcessor extends BaseProcessor {
                         // infer action type implicitly from commands; no explicit enum needed
                         let navigationTarget;
                         let detectedCommands = []; // Store detected command metadata
+                        let buttonPos; // Part-of-speech from Action.InsertText
                         const commands = content.Commands?.Command || content.commands?.command;
                         let predictionWords;
                         // Resolve image for this cell using FileMap and coordinate heuristics
@@ -1226,8 +1227,11 @@ class GridsetProcessor extends BaseProcessor {
                                         break;
                                     }
                                     case 'Action.InsertText': {
-                                        // speak
                                         const insertText = getParam('text');
+                                        const posParam = getParam('pos');
+                                        if (posParam) {
+                                            buttonPos = posParam;
+                                        }
                                         semanticAction = {
                                             category: AACSemanticCategory.COMMUNICATION,
                                             intent: AACSemanticIntent.INSERT_TEXT,
@@ -1235,7 +1239,7 @@ class GridsetProcessor extends BaseProcessor {
                                             platformData: {
                                                 grid3: {
                                                     commandId,
-                                                    parameters: { text: insertText },
+                                                    parameters: { text: insertText, pos: posParam },
                                                 },
                                             },
                                             fallback: {
@@ -1454,8 +1458,10 @@ class GridsetProcessor extends BaseProcessor {
                         }
                         // Extract grammar tags from commands (Smart Grammar)
                         const grammar = {};
+                        if (buttonPos)
+                            grammar.pos = buttonPos;
                         detectedCommands.forEach((cmd) => {
-                            if (cmd.parameters.pos)
+                            if (!grammar.pos && cmd.parameters.pos)
                                 grammar.pos = cmd.parameters.pos;
                             if (cmd.parameters.person)
                                 grammar.person = cmd.parameters.person;
@@ -1465,6 +1471,7 @@ class GridsetProcessor extends BaseProcessor {
                                 grammar.feature = cmd.parameters.feature;
                         });
                         const isSmartGrammarCell = Object.keys(grammar).length > 0;
+                        const effectivePos = buttonPos || grammar.pos || undefined;
                         const button = new AACButton({
                             id: `${gridId}_btn_${idx}`,
                             label: String(label),
@@ -1502,6 +1509,7 @@ class GridsetProcessor extends BaseProcessor {
                                 : gridPredictionWords.length > 0
                                     ? [...gridPredictionWords]
                                     : undefined,
+                            pos: effectivePos,
                             parameters: {
                                 pluginMetadata: pluginMetadata, // Store full plugin metadata for future use
                                 grid3Commands: detectedCommands, // Store detected command metadata
@@ -1673,7 +1681,7 @@ class GridsetProcessor extends BaseProcessor {
                 }
             }
         }
-        catch (e) {
+        catch (_e) {
             // If settings.xml parsing fails, tree.rootId will default to first page
         }
         // Set metadata on tree

package/dist/browser/processors/obfProcessor.js

@@ -48,7 +48,7 @@ class ObfProcessor extends BaseProcessor {
                     return null;
                 }
             }
-            catch (err) {
+            catch (_err) {
                 continue;
             }
         }
@@ -94,7 +94,7 @@ class ObfProcessor extends BaseProcessor {
                         return dataUrl;
                     }
                 }
-                catch (err) {
+                catch (_err) {
                     // Continue to next path
                     continue;
                 }
@@ -318,7 +318,7 @@ class ObfProcessor extends BaseProcessor {
                     return obj;
                 }
             }
-            catch (error) {
+            catch (_error) {
                 // Log parsing errors for debugging but don't throw
             }
             return null;
@@ -725,7 +725,7 @@ class ObfProcessor extends BaseProcessor {
             // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-unsafe-return
             return require('../validation/obfValidator').ObfValidator;
         }
-        catch (error) {
+        catch (_error) {
             throw new Error('Validation utilities are not available in this environment.');
         }
     }

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

@@ -24,7 +24,7 @@ async function collectFiles(root, matcher, maxDepth = 3, fileAdapter = defaultFi
         try {
             entries = await listDir(current.dir);
         }
-        catch (error) {
+        catch (_error) {
             continue;
         }
         for (const entry of entries) {
@@ -130,7 +130,7 @@ export async function openImage(dbOrFile, entryPath, fileAdapter = defaultFileAd
                 const dir = dirname(dbPath);
                 await removePath(dir);
             }
-            catch (e) {
+            catch (_e) {
                 // Ignore cleanup errors
             }
         }
@@ -174,7 +174,7 @@ export async function findSnapPackages(packageNamePattern = 'TobiiDynavox', file
             }
         }
     }
-    catch (error) {
+    catch (_error) {
         // Silently fail if directory access fails
     }
     return results;

package/dist/browser/processors/snapProcessor.js

@@ -215,7 +215,7 @@ class SnapProcessor extends BaseProcessor {
                             try {
                                 positions = JSON.parse(sg.SerializedGridPositions);
                             }
-                            catch (e) {
+                            catch (_e) {
                                 // Invalid JSON, skip this group
                                 return;
                             }
@@ -436,7 +436,7 @@ class SnapProcessor extends BaseProcessor {
                                 }
                             }
                         }
-                        catch (e) {
+                        catch (_e) {
                             // Ignore JSON parse errors in commands
                         }
                     }

package/dist/browser/processors/touchchatProcessor.js

@@ -101,7 +101,7 @@ class TouchChatProcessor extends BaseProcessor {
                     idMappings.set(mapping.numeric_id, mapping.string_id);
                 });
             }
-            catch (e) {
+            catch (_e) {
                 // No mapping table, use numeric IDs as strings
             }
             // Load styles
@@ -119,7 +119,7 @@ class TouchChatProcessor extends BaseProcessor {
                     pageStyles.set(style.id, style);
                 });
             }
-            catch (e) {
+            catch (_e) {
                 // console.log('No styles found:', e);
             }
             // First, load all pages and get their names from resources
@@ -307,7 +307,7 @@ class TouchChatProcessor extends BaseProcessor {
                     }
                 });
             }
-            catch (e) {
+            catch (_e) {
                 // console.log('No button box cells found:', e);
             }
             // Load buttons directly linked to pages via resources
@@ -366,7 +366,7 @@ class TouchChatProcessor extends BaseProcessor {
                         page.addButton(button);
                 });
             }
-            catch (e) {
+            catch (_e) {
                 // console.log('No direct page buttons found:', e);
             }
             // Load navigation actions
@@ -413,7 +413,7 @@ class TouchChatProcessor extends BaseProcessor {
                     }
                 });
             }
-            catch (e) {
+            catch (_e) {
                 // console.log('No navigation actions found:', e);
             }
             // Try to load root ID from multiple sources in order of priority
@@ -454,7 +454,7 @@ class TouchChatProcessor extends BaseProcessor {
                     tree.metadata.defaultHomePageId = rootPageId;
                 }
             }
-            catch (e) {
+            catch (_e) {
                 // No metadata table or other error, use first page as root
                 if (rootPageId) {
                     tree.rootId = rootPageId;

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

@@ -9,6 +9,7 @@
 import { AACSemanticCategory, AACScanType, } from '../../../core/treeStructure';
 import { CellScanningOrder, ScanningSelectionMethod } from '../../../types/aac';
 import { baseBoardEffort, distanceEffort, visualScanEffort, EFFORT_CONSTANTS, localScanEffort, scanningEffort, } from './effort';
+import { MorphologyEngine } from '../morphology';
 export class MetricsCalculator {
     constructor() {
         this.locale = 'en';
@@ -80,9 +81,11 @@ export class MetricsCalculator {
         });
         // Update buttons using dynamic spelling effort if applicable
         const buttons = Array.from(knownButtons.values()).sort((a, b) => a.effort - b.effort);
-        // Calculate metrics for word forms (smart grammar predictions) if enabled
-        // Default to true if not specified
-        const useSmartGrammar = options.useSmartGrammar !== false;
+        // Expand morphological predictions from POS tags if enabled or auto-detected
+        const useSmartGrammar = options.useSmartGrammar === true || this.treeHasPosTags(tree);
+        if (useSmartGrammar) {
+            this.expandMorphologicalPredictions(tree, options);
+        }
         if (useSmartGrammar) {
             const { wordFormMetrics, replacedLabels } = this.calculateWordFormMetrics(tree, buttons, options);
             // Remove buttons that were replaced by lower-effort word forms
@@ -151,13 +154,21 @@ export class MetricsCalculator {
                 }) || null;
         }
         if (!spellingPage)
-            return { spellingPage: null, spellingBaseEffort: 10, spellingAvgLetterEffort: 2.5 };
+            return {
+                spellingPage: null,
+                spellingBaseEffort: 10,
+                spellingAvgLetterEffort: 2.5,
+            };
         // Calculate effort to reach this page from root
         const rootBoard = tree.rootId
             ? tree.pages[tree.rootId]
             : Object.values(tree.pages).find((p) => !p.parentId);
         if (!rootBoard)
-            return { spellingPage, spellingBaseEffort: 10, spellingAvgLetterEffort: 2.5 };
+            return {
+                spellingPage,
+                spellingBaseEffort: 10,
+                spellingAvgLetterEffort: 2.5,
+            };
         // Analyze specifically to find the lowest effort path to the spelling page
         const result = this.analyzeFrom(tree, rootBoard, setPcts, true, options);
         const spellingBaseEffort = result.visitedBoardEfforts.get(spellingPage.id) ?? 10;
@@ -571,6 +582,157 @@ export class MetricsCalculator {
         boardPcts['all'] = totalLinks;
         return boardPcts;
     }
+    /**
+     * Quick check whether any button in the tree has a POS tag.
+     * Used to auto-enable smart grammar without requiring explicit opt-in.
+     */
+    treeHasPosTags(tree) {
+        for (const page of Object.values(tree.pages)) {
+            for (const row of page.grid) {
+                for (const btn of row) {
+                    if (btn?.pos && btn.pos !== 'Unknown' && btn.pos !== 'Ignore') {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Expand morphological predictions from POS tags on buttons
+     *
+     * For each button that has a POS tag (e.g., 'Verb', 'Noun'), use the
+     * MorphologyEngine to generate inflected word forms and populate the
+     * button's predictions array. This is done as a pre-processing step
+     * before calculateWordFormMetrics assigns effort to each form.
+     */
+    expandMorphologicalPredictions(tree, options) {
+        const locale = options.morphologyLocale || 'en-gb';
+        const morph = new MorphologyEngine(locale);
+        // Words that should never be POS-inferred (function words, determiners, etc.)
+        const skipInference = new Set([
+            'a',
+            'an',
+            'the',
+            'to',
+            'in',
+            'on',
+            'at',
+            'of',
+            'for',
+            'and',
+            'or',
+            'but',
+            'not',
+            'no',
+            'yes',
+            'is',
+            'am',
+            'are',
+            'was',
+            'were',
+            'be',
+            'been',
+            'being',
+            'has',
+            'have',
+            'had',
+            'do',
+            'does',
+            'did',
+            'will',
+            'would',
+            'could',
+            'should',
+            'shall',
+            'may',
+            'might',
+            'can',
+            'must',
+            'with',
+            'from',
+            'by',
+            'up',
+            'down',
+            'out',
+            'off',
+            'over',
+            'under',
+            'again',
+            'then',
+            'than',
+            'so',
+            'if',
+            'when',
+            'where',
+            'how',
+            'what',
+            'who',
+            'which',
+            'that',
+            'this',
+            'these',
+            'those',
+            'here',
+            'there',
+            'now',
+            'very',
+            'just',
+            'more',
+            'also',
+            'too',
+            'please',
+            'thank',
+            'hi',
+            'hello',
+            'bye',
+            'goodbye',
+            'okay',
+            'oh',
+            'wow',
+            'sorry',
+        ]);
+        for (const page of Object.values(tree.pages)) {
+            for (const row of page.grid) {
+                for (const btn of row) {
+                    if (!btn || !btn.label)
+                        continue;
+                    let pos = btn.pos;
+                    // If no POS tag (or Unknown/Ignore), attempt POS inference.
+                    // Many content words on topic pages lack POS tags even though
+                    // they are clearly nouns (e.g., "bird", "tree", "cloud").
+                    // Strategy: check irregular tables first for confident POS,
+                    // then fall back to Noun for single-word content labels.
+                    if (!pos || pos === 'Unknown' || pos === 'Ignore') {
+                        const lower = btn.label.toLowerCase();
+                        // Skip function words and multi-word labels
+                        if (!skipInference.has(lower) && !lower.includes(' ') && lower.length > 1) {
+                            // Check irregular tables for confident POS assignment
+                            const inferredPOS = morph.inferPOS(lower);
+                            if (inferredPOS) {
+                                pos = inferredPOS;
+                                btn.pos = inferredPOS;
+                            }
+                            else {
+                                // Default to Noun for untagged content words.
+                                // This generates plurals (e.g., bird → birds, tree → trees).
+                                pos = 'Noun';
+                                btn.pos = 'Noun';
+                            }
+                        }
+                    }
+                    if (!pos || pos === 'Unknown' || pos === 'Ignore')
+                        continue;
+                    const forms = morph.inflect(btn.label, pos);
+                    if (forms.length > 0) {
+                        const existing = btn.predictions || [];
+                        const merged = new Set([...existing, ...forms]);
+                        btn.predictions = Array.from(merged);
+                    }
+                }
+            }
+        }
+    }
     /**
      * Calculate metrics for word forms (smart grammar predictions)
      *
@@ -593,14 +755,53 @@ export class MetricsCalculator {
         // Track buttons by label to compare efforts
         const existingLabels = new Map();
         buttons.forEach((btn) => existingLabels.set(btn.label.toLowerCase(), btn));
+        // Build a map of POS tags from ALL tree buttons, keyed by lowercase label.
+        // This ensures words on BFS-unreachable pages still contribute POS data.
+        const treePosMap = new Map();
+        const treePredictionsMap = new Map();
+        Object.values(tree.pages).forEach((page) => {
+            page.grid.forEach((row) => {
+                row.forEach((btn) => {
+                    if (!btn || !btn.label)
+                        return;
+                    const lower = btn.label.toLowerCase();
+                    if (btn.pos && btn.pos !== 'Unknown' && btn.pos !== 'Ignore') {
+                        treePosMap.set(lower, btn.pos);
+                    }
+                    if (btn.predictions && btn.predictions.length > 0) {
+                        const existing = treePredictionsMap.get(lower);
+                        if (!existing || btn.predictions.length > existing.length) {
+                            treePredictionsMap.set(lower, btn.predictions);
+                        }
+                    }
+                });
+            });
+        });
+        // For metrics buttons that lack POS but have a tree counterpart with POS,
+        // propagate the POS tag so it's available in the output.
+        buttons.forEach((btn) => {
+            const lower = btn.label.toLowerCase();
+            if (!btn.pos || btn.pos === 'Unknown' || btn.pos === 'Ignore') {
+                const treePos = treePosMap.get(lower);
+                if (treePos)
+                    btn.pos = treePos;
+            }
+        });
+        // Note: buttons on pages unreachable via BFS from the root page are
+        // intentionally excluded. If there is no navigation path to a page,
+        // those buttons are not accessible to the user and should not count
+        // as available vocabulary.
         // Iterate through all pages to find buttons with predictions
         Object.values(tree.pages).forEach((page) => {
             page.grid.forEach((row) => {
                 row.forEach((btn) => {
                     if (!btn || !btn.predictions || btn.predictions.length === 0)
                         return;
-                    // Find the parent button's metrics
-                    const parentMetrics = buttons.find((b) => b.id === btn.id);
+                    // Find the parent button's metrics (by id first, then by label)
+                    let parentMetrics = buttons.find((b) => b.id === btn.id);
+                    if (!parentMetrics && btn.label) {
+                        parentMetrics = existingLabels.get(btn.label.toLowerCase());
+                    }
                     if (!parentMetrics)
                         return;
                     // Calculate effort for each word form
@@ -698,7 +899,11 @@ export class MetricsCalculator {
             // If no block assigned, treat as its own block at the end (fallback)
             if (blockId === null) {
                 const loop = board.grid.length + (board.grid[0]?.length || 0);
-                return { steps: rowIndex + colIndex + 1, selections: 1, loopSteps: loop };
+                return {
+                    steps: rowIndex + colIndex + 1,
+                    selections: 1,
+                    loopSteps: loop,
+                };
             }
             const blockConfig = board.scanBlocksConfig?.find((c) => c.id === blockId);
             const blockOrder = blockConfig?.order ?? blockId;