@willwade/aac-processors 0.2.16 → 0.2.18

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

@@ -909,6 +909,61 @@ export function getAllPluginIds() {
     const plugins = new Set(Object.values(GRID3_COMMANDS).map((cmd) => cmd.pluginId));
     return Array.from(plugins).sort();
 }
+function textOfStructured(val) {
+    if (!val || typeof val !== 'object')
+        return undefined;
+    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 === 'number') {
+                    if (r !== 0)
+                        parts.push(String(r));
+                    continue;
+                }
+                if (typeof r === 'object' && r !== null) {
+                    if ('#text' in r)
+                        parts.push(String(r['#text']));
+                    else if ('#cdata' in r)
+                        parts.push(String(r['#cdata']));
+                    else
+                        parts.push(String(r));
+                }
+                else {
+                    parts.push(String(r));
+                }
+            }
+        }
+    };
+    if (val.p) {
+        const sElements = Array.isArray(val.p.s) ? val.p.s : val.p.s ? [val.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);
+    }
+    return parts.length > 0 ? parts.join('').trim() : undefined;
+}
+function extractParamValue(param) {
+    if (typeof param === 'string')
+        return param;
+    if (param.p || param.s || (param.r !== undefined && typeof param.r !== 'string')) {
+        const structured = textOfStructured(param);
+        if (structured !== undefined)
+            return structured;
+    }
+    const simple = param['#text'] ?? param.text ?? param.value;
+    if (simple !== undefined)
+        return simple;
+    return textOfStructured(param);
+}
 export function extractCommandParameters(command) {
     const parameters = {};
     const params = command.Parameter || command.parameter;
@@ -917,7 +972,7 @@ export function extractCommandParameters(command) {
     const paramArray = Array.isArray(params) ? params : [params];
     for (const param of paramArray) {
         const key = param['@_Key'] || param.Key || param.key;
-        let value = param['#text'] ?? param.text ?? param.value;
+        let value = extractParamValue(param);
         if (key && value !== undefined) {
             // Try to convert to number if it looks numeric
             if (typeof value === 'string' && /^\d+$/.test(value)) {

package/dist/browser/processors/gridsetProcessor.js

@@ -700,6 +700,13 @@ class GridsetProcessor extends BaseProcessor {
                             }
                         }
                     }
+                    if (pageWordListItems.length > 0) {
+                        page.wordListItems = pageWordListItems.map((item) => ({
+                            text: item.text,
+                            image: item.image,
+                            partOfSpeech: item.partOfSpeech,
+                        }));
+                    }
                     // Track WordList AutoContent cells and their positions for "more" button placement
                     const wordListAutoContentCells = [];
                     let wordListCellIndex = 0;
@@ -1032,6 +1039,15 @@ class GridsetProcessor extends BaseProcessor {
                                     const param = getRawParam(key);
                                     if (param === undefined)
                                         return undefined;
+                                    if (typeof param === 'string')
+                                        return param;
+                                    if (param.p ||
+                                        param.s ||
+                                        (param.r !== undefined && typeof param.r !== 'string')) {
+                                        const structuredValue = this.textOf(param);
+                                        if (structuredValue !== undefined)
+                                            return structuredValue;
+                                    }
                                     const simpleValue = param['#text'] ?? param.text ?? param.value;
                                     if (typeof simpleValue === 'string')
                                         return simpleValue;
@@ -1040,8 +1056,6 @@ class GridsetProcessor extends BaseProcessor {
                                     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

package/dist/browser/processors/snapProcessor.js

@@ -333,6 +333,9 @@ class SnapProcessor extends BaseProcessor {
                         buttonColumns.has('BackgroundColor') ? 'b.BackgroundColor' : 'NULL AS BackgroundColor',
                         buttonColumns.has('NavigatePageId') ? 'b.NavigatePageId' : 'NULL AS NavigatePageId',
                         buttonColumns.has('ContentType') ? 'b.ContentType' : 'NULL AS ContentType',
+                        buttonColumns.has('SerializedContentTypeHandler')
+                            ? 'b.SerializedContentTypeHandler'
+                            : 'NULL AS SerializedContentTypeHandler',
                     ];
                     if (this.loadAudio) {
                         selectFields.push(buttonColumns.has('MessageRecordingId')
@@ -548,22 +551,54 @@ class SnapProcessor extends BaseProcessor {
                             },
                         };
                     }
+                    let snapContentType;
+                    let snapContentSubType;
+                    let snapGrammarPos;
+                    let snapGrammarHandler;
+                    if (btnRow.ContentType === 1) {
+                        snapContentType = 'AutoContent';
+                        snapContentSubType = 'Prediction';
+                    }
+                    else if (btnRow.ContentType === 3 && btnRow.SerializedContentTypeHandler) {
+                        snapContentType = 'Inflector';
+                        snapGrammarHandler = String(btnRow.SerializedContentTypeHandler);
+                        const colonIdx = snapGrammarHandler.indexOf(':');
+                        if (colonIdx !== -1) {
+                            const subtype = snapGrammarHandler.substring(colonIdx + 1).split(',')[0];
+                            snapContentSubType = subtype;
+                            const { TDSnapLexiconParser, } = require('../utilities/analytics/morphology/tdsnapLexiconParser');
+                            snapGrammarPos = TDSnapLexiconParser.tagToPos(subtype);
+                        }
+                    }
                     const button = new AACButton({
                         id: String(btnRow.Id),
                         label: btnRow.Label || (btnRow.ContentType === 1 ? '[Prediction]' : ''),
                         message: btnRow.Message || (btnRow.ContentType === 1 ? '[Prediction]' : btnRow.Label || ''),
                         targetPageId: targetPageUniqueId,
                         semanticAction: semanticAction,
-                        contentType: btnRow.ContentType === 1 ? 'AutoContent' : undefined,
-                        contentSubType: btnRow.ContentType === 1 ? 'Prediction' : undefined,
+                        contentType: snapContentType,
+                        contentSubType: snapContentSubType,
                         audioRecording: audioRecording,
                         visibility: mapSnapVisibility(btnRow.Visible),
                         semantic_id: btnRow.LibrarySymbolId
                             ? `snap_symbol_${btnRow.LibrarySymbolId}`
-                            : undefined, // Extract semantic_id from LibrarySymbolId
+                            : undefined,
                         image: buttonImage,
                         resolvedImageEntry: buttonImage,
-                        parameters: Object.keys(buttonParameters).length > 0 ? buttonParameters : undefined,
+                        parameters: {
+                            ...(Object.keys(buttonParameters).length > 0 ? buttonParameters : {}),
+                            ...(snapGrammarHandler
+                                ? {
+                                    grammar: {
+                                        handler: snapGrammarHandler,
+                                        category: snapGrammarHandler.substring(0, snapGrammarHandler.indexOf(':') !== -1
+                                            ? snapGrammarHandler.indexOf(':')
+                                            : snapGrammarHandler.length),
+                                        subtype: snapContentSubType,
+                                    },
+                                }
+                                : {}),
+                        },
                         style: {
                             backgroundColor: btnRow.BackgroundColor
                                 ? `#${btnRow.BackgroundColor.toString(16)}`
@@ -576,6 +611,9 @@ class SnapProcessor extends BaseProcessor {
                             fontStyle: btnRow.FontStyle?.toString(),
                         },
                     });
+                    if (snapGrammarPos) {
+                        button.pos = snapGrammarPos;
+                    }
                     // Add to the intended parent page
                     const parentPage = tree.getPage(parentUniqueId);
                     if (parentPage) {

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

@@ -585,12 +585,20 @@ export class MetricsCalculator {
     /**
      * Quick check whether any button in the tree has a POS tag.
      * Used to auto-enable smart grammar without requiring explicit opt-in.
+     *
+     * IMPORTANT: Only counts POS from non-Inflector and non-Suffix buttons.
+     * TDSnap Inflector buttons and Grid3 Suffix buttons are grammar controls,
+     * not content words — they should NOT auto-enable morphology.
      */
     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') {
+                    if (btn?.pos &&
+                        btn.pos !== 'Unknown' &&
+                        btn.pos !== 'Ignore' &&
+                        btn.pos !== 'Suffix' &&
+                        btn.contentType !== 'Inflector') {
                         return true;
                     }
                 }
@@ -608,8 +616,44 @@ export class MetricsCalculator {
      */
     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.)
+        let morph;
+        if (options.tdsnapLexiconPath) {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { TDSnapLexiconParser } = require('../morphology/tdsnapLexiconParser');
+            const parser = new TDSnapLexiconParser();
+            const lexiconData = parser.parseDb(options.tdsnapLexiconPath, locale.replace('-', '_'));
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            morph = MorphologyEngine.fromTDSnapLexicon(lexiconData);
+            this.expandTDSnapPredictions(tree, morph);
+            return;
+        }
+        if (options.grid3VerbsPath) {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { Grid3VerbsParser } = require('../morphology/grid3VerbsParser');
+            const parser = new Grid3VerbsParser();
+            const verbForms = parser.parseZip(options.grid3VerbsPath);
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            morph = MorphologyEngine.fromGrid3Verbs(verbForms);
+            this.expandGrid3Predictions(tree, morph);
+            return;
+        }
+        morph = new MorphologyEngine(locale);
+        this.expandGrid3Predictions(tree, morph);
+    }
+    /**
+     * Expand morphological predictions for Grid3 pagesets.
+     *
+     * Grid3 uses suffix buttons (pos='Suffix') on the same page as content words.
+     * Different pages have different suffix buttons — e.g., topic pages may only
+     * have -s (plural), while the Magic Wand page has -s, -er, -est, -ly, -y, -'s.
+     *
+     * Rules:
+     * 1. Build a suffix→formSlot map (-s → plural, -er → comparative, etc.)
+     * 2. For each page, collect available suffix buttons
+     * 3. Only generate forms for slots that have matching suffix buttons on that page
+     * 4. POS inference is used for untagged content words (Grid3 grids often lack POS)
+     */
+    expandGrid3Predictions(tree, morph) {
         const skipInference = new Set([
             'a',
             'an',
@@ -692,30 +736,56 @@ export class MetricsCalculator {
             'wow',
             'sorry',
         ]);
+        // Map suffix button labels to the morphology slots they produce
+        const SUFFIX_TO_SLOT = {
+            '-s': ['plural'],
+            "-'s": ['possessive'],
+            '-er': ['comparative'],
+            '-est': ['superlative'],
+            '-ly': ['adverb'],
+            '-y': ['adjective'],
+        };
+        // POS → slots that POS can produce (for filtering)
+        const POS_TO_SUFFIX_SLOTS = {
+            Noun: new Set(['plural', 'possessive']),
+            Verb: new Set(['plural']),
+            Adjective: new Set(['comparative', 'superlative', 'adverb', 'adjective']),
+        };
         for (const page of Object.values(tree.pages)) {
+            // Collect suffix buttons on this page
+            const pageSuffixes = new Set();
+            const pageSuffixSlots = new Set();
+            for (const row of page.grid) {
+                for (const btn of row) {
+                    if (btn?.pos === 'Suffix' && btn.label) {
+                        pageSuffixes.add(btn.label);
+                        const slots = SUFFIX_TO_SLOT[btn.label];
+                        if (slots) {
+                            for (const s of slots)
+                                pageSuffixSlots.add(s);
+                        }
+                    }
+                }
+            }
+            // No suffix buttons on this page → no morphology
+            if (pageSuffixSlots.size === 0)
+                continue;
             for (const row of page.grid) {
                 for (const btn of row) {
                     if (!btn || !btn.label)
                         continue;
+                    if (btn.pos === 'Suffix')
+                        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';
                             }
@@ -723,16 +793,90 @@ export class MetricsCalculator {
                     }
                     if (!pos || pos === 'Unknown' || pos === 'Ignore')
                         continue;
-                    const forms = morph.inflect(btn.label, pos);
-                    if (forms.length > 0) {
+                    // Check if this POS can produce forms matching the page's suffix slots
+                    const posSlots = POS_TO_SUFFIX_SLOTS[pos];
+                    if (!posSlots)
+                        continue;
+                    const hasRelevantSlot = [...posSlots].some((s) => pageSuffixSlots.has(s));
+                    if (!hasRelevantSlot)
+                        continue;
+                    const allForms = morph.inflect(btn.label, pos);
+                    if (allForms.length === 0)
+                        continue;
+                    // Filter forms: only include those producible by suffixes on this page
+                    // For the built-in engine, we can't easily map forms to slots, so
+                    // include all forms when any relevant suffix exists. The per-page
+                    // gate (suffix presence) is the main filter.
+                    const existing = btn.predictions || [];
+                    const merged = new Set([...existing, ...allForms]);
+                    btn.predictions = Array.from(merged);
+                }
+            }
+        }
+    }
+    /**
+     * Expand morphological predictions for TDSnap pagesets.
+     *
+     * TDSnap uses Inflector buttons (ContentType=3) on "Word Forms" pages to
+     * provide morphology. These pages are loaded dynamically by the runtime,
+     * NOT via navigation buttons, so they are unreachable in our tree model.
+     *
+     * Rules:
+     * 1. If the pageset has NO Inflector buttons → no morphology at all
+     * 2. Only generate forms whose grammar tag matches an available Inflector
+     *    (e.g., if there's no -ly Inflector, don't generate "happily")
+     * 3. No POS inference — only the lexicon determines which words get forms
+     */
+    expandTDSnapPredictions(tree, morph) {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { TDSnapLexiconParser } = require('../morphology/tdsnapLexiconParser');
+        // Step 1: Collect available grammar tags from Inflector buttons
+        const availableTags = new Set();
+        for (const page of Object.values(tree.pages)) {
+            for (const row of page.grid) {
+                for (const btn of row) {
+                    if (btn?.contentType === 'Inflector' && btn.parameters?.grammar?.handler) {
+                        const parsed = TDSnapLexiconParser.parseContentTypeHandler(btn.parameters.grammar.handler);
+                        if (parsed) {
+                            const key = `${parsed.category}:${parsed.subtype}`;
+                            const tag = TDSnapLexiconParser.HANDLER_TAG_MAP[key];
+                            if (tag)
+                                availableTags.add(tag);
+                        }
+                    }
+                }
+            }
+        }
+        if (availableTags.size === 0)
+            return;
+        // Step 2: For each button, look up lexicon forms filtered by available tags
+        for (const page of Object.values(tree.pages)) {
+            for (const row of page.grid) {
+                for (const btn of row) {
+                    if (!btn || !btn.label || btn.contentType === 'Inflector')
+                        continue;
+                    const filtered = this.filterFormsByAvailableTags(morph, btn.label, availableTags);
+                    if (filtered.length > 0) {
                         const existing = btn.predictions || [];
-                        const merged = new Set([...existing, ...forms]);
+                        const merged = new Set([...existing, ...filtered]);
                         btn.predictions = Array.from(merged);
                     }
                 }
             }
         }
     }
+    filterFormsByAvailableTags(morph, base, availableTags) {
+        const entry = morph.getLexiconEntry(base.toLowerCase());
+        if (!entry)
+            return [];
+        const forms = [];
+        for (const f of entry.forms) {
+            if (availableTags.has(f.tag) && f.form.toLowerCase() !== base.toLowerCase()) {
+                forms.push(f.form);
+            }
+        }
+        return forms;
+    }
     /**
      * Calculate metrics for word forms (smart grammar predictions)
      *
@@ -749,7 +893,7 @@ export class MetricsCalculator {
      * @param options - Metrics options
      * @returns Object containing word form metrics and labels that were replaced
      */
-    calculateWordFormMetrics(tree, buttons, _options = {}) {
+    calculateWordFormMetrics(tree, buttons, options = {}) {
         const wordFormMetrics = [];
         const replacedLabels = new Set();
         // Track buttons by label to compare efforts
@@ -811,23 +955,28 @@ export class MetricsCalculator {
                     // Calculate effort for each word form
                     btn.predictions.forEach((wordForm, index) => {
                         const wordFormLower = wordForm.toLowerCase();
-                        // Calculate effort based on position in predictions array
-                        // Assume predictions are displayed in a grid layout (e.g., 2 columns)
-                        const predictionsGridCols = 2; // Typical predictions layout
-                        const predictionRowIndex = Math.floor(index / predictionsGridCols);
-                        const predictionColIndex = index % predictionsGridCols;
-                        // Calculate visual scan effort to reach this word form position
-                        // Using similar logic to button scanning effort
-                        const predictionPriorItems = predictionRowIndex * predictionsGridCols + predictionColIndex;
-                        const predictionSelectionEffort = visualScanEffort(predictionPriorItems);
-                        // Add confirmation cost for Suggest Words outcomes only.
-                        // Suggest Words requires an explicit tap on the prediction bar,
-                        // while smart grammar morphology forms are auto-generated (no extra tap).
-                        const suggestWordsConfirmation = suggestWordsSet.has(wordFormLower)
-                            ? EFFORT_CONSTANTS.SUGGEST_WORDS_SELECTION_EFFORT
-                            : 0;
-                        // Word form effort = parent button's cumulative effort + selection effort + confirmation
-                        const wordFormEffort = parentMetrics.effort + predictionSelectionEffort + suggestWordsConfirmation;
+                        const isSuggestWords = suggestWordsSet.has(wordFormLower);
+                        let wordFormEffort;
+                        if (options.tdsnapLexiconPath && !isSuggestWords) {
+                            // TDSnap Inflector-based form: the grammar overlay appears
+                            // dynamically when a word is selected. The cost is a fixed
+                            // single selection to tap the Inflector button.
+                            wordFormEffort =
+                                parentMetrics.effort + EFFORT_CONSTANTS.TDSNAP_GRAMMAR_OVERLAY_EFFORT;
+                        }
+                        else {
+                            // Grid-based prediction layout (Suggest Words, or Grid3 morphology)
+                            const predictionsGridCols = 2;
+                            const predictionRowIndex = Math.floor(index / predictionsGridCols);
+                            const predictionColIndex = index % predictionsGridCols;
+                            const predictionPriorItems = predictionRowIndex * predictionsGridCols + predictionColIndex;
+                            const predictionSelectionEffort = visualScanEffort(predictionPriorItems);
+                            const suggestWordsConfirmation = isSuggestWords
+                                ? EFFORT_CONSTANTS.SUGGEST_WORDS_SELECTION_EFFORT
+                                : 0;
+                            wordFormEffort =
+                                parentMetrics.effort + predictionSelectionEffort + suggestWordsConfirmation;
+                        }
                         // Check if this word already exists as a regular button
                         const existingBtn = existingLabels.get(wordFormLower);
                         // If word exists and has lower or equal effort, skip the word form

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

@@ -32,6 +32,7 @@ export const EFFORT_CONSTANTS = {
     DEFAULT_SCAN_ERROR_RATE: 0.1, // 10% chance of missing a selection
     SCAN_RETRY_PENALTY: 1.0, // Cost multiplier for a full loop retry
     SUGGEST_WORDS_SELECTION_EFFORT: 0.5, // Extra tap to confirm a Suggest Words prediction
+    TDSNAP_GRAMMAR_OVERLAY_EFFORT: 0.1, // Fixed cost: select an Inflector button from the dynamic grammar overlay
 };
 /**
  * Calculate button size effort based on grid dimensions

package/dist/browser/utilities/analytics/morphology/engine.js

@@ -1,4 +1,7 @@
 export class MorphologyEngine {
+    getLexiconEntry(word) {
+        return this.tdsnapLexicon?.words.get(word.toLowerCase());
+    }
     constructor(ruleSetOrLocale) {
         this.cache = new Map();
         if (typeof ruleSetOrLocale === 'string') {
@@ -18,6 +21,16 @@ export class MorphologyEngine {
         engine.grid3Verbs = verbForms.verbs;
         return engine;
     }
+    static fromTDSnapLexicon(lexiconData) {
+        const engine = new MorphologyEngine({
+            locale: lexiconData.locale,
+            version: 1,
+            irregular: {},
+            regular: {},
+        });
+        engine.tdsnapLexicon = lexiconData;
+        return engine;
+    }
     get locale() {
         return this.ruleSet.locale;
     }
@@ -26,9 +39,18 @@ export class MorphologyEngine {
         const cached = this.cache.get(key);
         if (cached)
             return cached;
+        if (this.tdsnapLexicon) {
+            const entry = this.tdsnapLexicon.words.get(base.toLowerCase());
+            if (entry) {
+                const forms = entry.forms.map((f) => f.form);
+                this.cache.set(key, forms);
+                return forms;
+            }
+        }
         if (this.grid3Verbs) {
-            const forms = this.grid3Verbs.get(base) || this.grid3Verbs.get(base.toLowerCase());
-            if (forms) {
+            const raw = this.grid3Verbs.get(base) || this.grid3Verbs.get(base.toLowerCase());
+            if (raw) {
+                const forms = raw.filter((f) => !f.includes('{'));
                 this.cache.set(key, forms);
                 return forms;
             }

package/dist/browser/utilities/analytics/morphology/index.js

@@ -1,2 +1,3 @@
 export { MorphologyEngine } from './engine';
 export { WordFormGenerator } from './wordFormGenerator';
+export { TDSnapLexiconParser } from './tdsnapLexiconParser';