@willwade/aac-processors 0.2.5 → 0.2.7

package/dist/browser/processors/gridsetProcessor.js

@@ -2204,6 +2204,130 @@ class GridsetProcessor extends BaseProcessor {
             RowDefinition: Array(maxRows).fill({}),
         };
     }
+    /**
+     * Save a modified tree while preserving all original files (settings, images, assets)
+     * This method only updates the grid.xml files for pages in the tree, keeping everything else intact.
+     *
+     * @param originalPath - Path to the original gridset file
+     * @param tree - Modified AACTree with pages to save
+     * @param outputPath - Path where the modified gridset should be saved
+     */
+    async saveModifiedTree(originalPath, tree, outputPath) {
+        const { readBinaryFromInput, writeBinaryToPath } = this.options.fileAdapter;
+        if (Object.keys(tree.pages).length === 0) {
+            // Empty tree, just copy the original
+            const originalBuffer = await readBinaryFromInput(originalPath);
+            await writeBinaryToPath(outputPath, originalBuffer);
+            return;
+        }
+        const AdmZip = (await import('adm-zip')).default;
+        const originalZip = new AdmZip(originalPath);
+        const outputZip = new AdmZip();
+        // Collect styles from the tree for grid.xml files
+        const uniqueStyles = new Map();
+        let styleIdCounter = 1;
+        const addStyle = (style) => {
+            if (!style)
+                return '';
+            const normalizedStyle = { ...style };
+            const styleKey = JSON.stringify(normalizedStyle);
+            const existing = uniqueStyles.get(styleKey);
+            if (existing)
+                return existing.id;
+            const styleId = `Style${styleIdCounter++}`;
+            uniqueStyles.set(styleKey, { id: styleId, style: normalizedStyle });
+            return styleId;
+        };
+        // Collect all styles from pages and buttons
+        Object.values(tree.pages).forEach((page) => {
+            addStyle(page.style);
+            page.buttons.forEach((button) => {
+                addStyle(button.style);
+            });
+        });
+        // Track which grid files we're modifying
+        const modifiedGridFiles = new Set();
+        // Generate grid.xml files for pages in the tree
+        const newGridFiles = new Map();
+        for (const page of Object.values(tree.pages)) {
+            const gridPath = `Grids/${page.name}/grid.xml`;
+            modifiedGridFiles.add(gridPath);
+            // Build the grid XML content
+            const gridData = {
+                Grid: {
+                    '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+                    GridGuid: page.id,
+                    ColumnDefinitions: this.calculateColumnDefinitions(page),
+                    RowDefinitions: this.calculateRowDefinitions(page, false),
+                    AutoContentCommands: '',
+                    Cells: page.buttons.length > 0
+                        ? {
+                            Cell: this.filterPageButtons(page.buttons).map((button, btnIndex) => {
+                                const buttonStyleId = button.style ? addStyle(button.style) : '';
+                                const position = this.findButtonPosition(page, button, btnIndex);
+                                const captionAndImage = {
+                                    Caption: button.label || '',
+                                };
+                                // Handle image references
+                                if (button.image) {
+                                    captionAndImage.Image = `${button.image}`;
+                                }
+                                const cell = {
+                                    '@_Column': position.x,
+                                    '@_Row': position.y,
+                                    captionAndImage,
+                                };
+                                if (position.columnSpan > 1) {
+                                    cell['@_ColumnSpan'] = position.columnSpan;
+                                }
+                                if (position.rowSpan > 1) {
+                                    cell['@_RowSpan'] = position.rowSpan;
+                                }
+                                if (buttonStyleId) {
+                                    cell.CellStyle = buttonStyleId;
+                                }
+                                if (button.message && button.message !== button.label) {
+                                    // Use spoken message if different from label
+                                    const spoken = button.message;
+                                    const cellContent = {
+                                        spoken,
+                                        type: 'text',
+                                    };
+                                    cell['ContentCell'] = cellContent;
+                                }
+                                return cell;
+                            }),
+                        }
+                        : undefined,
+                },
+            };
+            const gridBuilder = new XMLBuilder({
+                ignoreAttributes: false,
+                format: true,
+                indentBy: '  ',
+                suppressEmptyNode: true,
+            });
+            newGridFiles.set(gridPath, gridBuilder.build(gridData));
+        }
+        // Copy all files from original zip, replacing modified grid files
+        for (const entry of originalZip.getEntries()) {
+            if (entry.isDirectory)
+                continue;
+            // Skip grid.xml files that we're modifying
+            if (modifiedGridFiles.has(entry.entryName)) {
+                const newContent = newGridFiles.get(entry.entryName);
+                if (newContent) {
+                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
+                }
+                continue;
+            }
+            // Copy all other files as-is
+            outputZip.addFile(entry.entryName, entry.getData());
+        }
+        // Write the output ZIP
+        const outputBuffer = outputZip.toBuffer();
+        await writeBinaryToPath(outputPath, outputBuffer);
+    }
     // Helper method to find button position with span information
     findButtonPosition(page, button, fallbackIndex) {
         if (page.grid && page.grid.length > 0) {

package/dist/browser/processors/obfProcessor.js

@@ -616,6 +616,75 @@ class ObfProcessor extends BaseProcessor {
             await writeBinaryToPath(outputPath, zipData);
         }
     }
+    /**
+     * Save a modified tree while preserving all original files (images, sounds, assets)
+     * This method only updates the .obf files for pages in the tree, keeping everything else intact.
+     *
+     * @param originalPath - Path to the original OBF/OBZ file
+     * @param tree - Modified AACTree with pages to save
+     * @param outputPath - Path where the modified file should be saved
+     */
+    async saveModifiedTree(originalPath, tree, outputPath) {
+        const { writeBinaryToPath, readBinaryFromInput } = this.options.fileAdapter;
+        // If output is .obf (single file), use regular save
+        if (outputPath.endsWith('.obf')) {
+            await this.saveFromTree(tree, outputPath);
+            return;
+        }
+        if (Object.keys(tree.pages).length === 0) {
+            // Empty tree, just copy the original
+            const originalBuffer = await readBinaryFromInput(originalPath);
+            await writeBinaryToPath(outputPath, originalBuffer);
+            return;
+        }
+        const AdmZip = (await import('adm-zip')).default;
+        const originalZip = new AdmZip(originalPath);
+        const outputZip = new AdmZip();
+        const getPageFilename = (id) => (id.endsWith('.obf') ? id : `${id}.obf`);
+        // Track which .obf files we're modifying
+        const modifiedObfFiles = new Set();
+        // Generate new .obf files for pages in the tree
+        const newObfFiles = new Map();
+        for (const page of Object.values(tree.pages)) {
+            const obfFilename = getPageFilename(page.id);
+            modifiedObfFiles.add(obfFilename);
+            const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
+            const obfContent = JSON.stringify(obfBoard, null, 2);
+            newObfFiles.set(obfFilename, obfContent);
+        }
+        // Generate updated manifest if we have pages
+        if (Object.keys(tree.pages).length > 0) {
+            modifiedObfFiles.add('manifest.json');
+            const manifest = {
+                format: OBF_FORMAT_VERSION,
+                root: tree.metadata.defaultHomePageId,
+                paths: {
+                    boards: Object.fromEntries(Object.entries(tree.pages).map(([id, page]) => [id, getPageFilename(page.id)])),
+                    images: {},
+                    sounds: {},
+                },
+            };
+            newObfFiles.set('manifest.json', JSON.stringify(manifest));
+        }
+        // Copy all files from original zip, replacing modified .obf files
+        for (const entry of originalZip.getEntries()) {
+            if (entry.isDirectory)
+                continue;
+            // Skip .obf files that we're modifying
+            if (modifiedObfFiles.has(entry.entryName)) {
+                const newContent = newObfFiles.get(entry.entryName);
+                if (newContent) {
+                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
+                }
+                continue;
+            }
+            // Copy all other files as-is (preserves images, sounds, etc.)
+            outputZip.addFile(entry.entryName, entry.getData());
+        }
+        // Write the output ZIP
+        const outputBuffer = outputZip.toBuffer();
+        await writeBinaryToPath(outputPath, outputBuffer);
+    }
     /**
      * Extract strings with metadata for aac-tools-platform compatibility
      * Uses the generic implementation from BaseProcessor

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

@@ -804,6 +804,10 @@ export class MetricsCalculator {
                     }
                     if (!parentMetrics)
                         return;
+                    // Build set of original Suggest Words predictions (from Prediction.PredictThis).
+                    // These require an extra confirmation tap from the user. Smart grammar
+                    // morphology outcomes are generated automatically and need no extra tap.
+                    const suggestWordsSet = new Set((btn.parameters?.predictions || []).map((w) => w.toLowerCase()));
                     // Calculate effort for each word form
                     btn.predictions.forEach((wordForm, index) => {
                         const wordFormLower = wordForm.toLowerCase();
@@ -816,8 +820,14 @@ export class MetricsCalculator {
                         // Using similar logic to button scanning effort
                         const predictionPriorItems = predictionRowIndex * predictionsGridCols + predictionColIndex;
                         const predictionSelectionEffort = visualScanEffort(predictionPriorItems);
-                        // Word form effort = parent button's cumulative effort + selection effort
-                        const wordFormEffort = parentMetrics.effort + predictionSelectionEffort;
+                        // 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;
                         // 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
@@ -838,9 +848,10 @@ export class MetricsCalculator {
                             semantic_id: parentMetrics.semantic_id,
                             clone_id: parentMetrics.clone_id,
                             temporary_home_id: parentMetrics.temporary_home_id,
-                            is_word_form: true, // Mark this as a word form metric
-                            parent_button_id: btn.id, // Track parent button
-                            parent_button_label: parentMetrics.label, // Track parent label
+                            is_word_form: true,
+                            is_suggest_words: suggestWordsSet.has(wordFormLower) || undefined,
+                            parent_button_id: btn.id,
+                            parent_button_label: parentMetrics.label,
                         };
                         wordFormMetrics.push(wordFormBtn);
                         existingLabels.set(wordFormLower, wordFormBtn);

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

@@ -31,6 +31,7 @@ export const EFFORT_CONSTANTS = {
     SCAN_SELECTION_COST: 0.1, // Cost of a switch selection
     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
 };
 /**
  * Calculate button size effort based on grid dimensions

package/dist/processors/gridsetProcessor.d.ts

@@ -51,6 +51,15 @@ declare class GridsetProcessor extends BaseProcessor {
     saveFromTree(tree: AACTree, outputPath: string): Promise<void>;
     private calculateColumnDefinitions;
     private calculateRowDefinitions;
+    /**
+     * Save a modified tree while preserving all original files (settings, images, assets)
+     * This method only updates the grid.xml files for pages in the tree, keeping everything else intact.
+     *
+     * @param originalPath - Path to the original gridset file
+     * @param tree - Modified AACTree with pages to save
+     * @param outputPath - Path where the modified gridset should be saved
+     */
+    saveModifiedTree(originalPath: string, tree: AACTree, outputPath: string): Promise<void>;
     private findButtonPosition;
     /**
      * Extract strings with metadata for aac-tools-platform compatibility

package/dist/processors/gridsetProcessor.js

@@ -1,4 +1,27 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GridsetProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
@@ -2207,6 +2230,130 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
             RowDefinition: Array(maxRows).fill({}),
         };
     }
+    /**
+     * Save a modified tree while preserving all original files (settings, images, assets)
+     * This method only updates the grid.xml files for pages in the tree, keeping everything else intact.
+     *
+     * @param originalPath - Path to the original gridset file
+     * @param tree - Modified AACTree with pages to save
+     * @param outputPath - Path where the modified gridset should be saved
+     */
+    async saveModifiedTree(originalPath, tree, outputPath) {
+        const { readBinaryFromInput, writeBinaryToPath } = this.options.fileAdapter;
+        if (Object.keys(tree.pages).length === 0) {
+            // Empty tree, just copy the original
+            const originalBuffer = await readBinaryFromInput(originalPath);
+            await writeBinaryToPath(outputPath, originalBuffer);
+            return;
+        }
+        const AdmZip = (await Promise.resolve().then(() => __importStar(require('adm-zip')))).default;
+        const originalZip = new AdmZip(originalPath);
+        const outputZip = new AdmZip();
+        // Collect styles from the tree for grid.xml files
+        const uniqueStyles = new Map();
+        let styleIdCounter = 1;
+        const addStyle = (style) => {
+            if (!style)
+                return '';
+            const normalizedStyle = { ...style };
+            const styleKey = JSON.stringify(normalizedStyle);
+            const existing = uniqueStyles.get(styleKey);
+            if (existing)
+                return existing.id;
+            const styleId = `Style${styleIdCounter++}`;
+            uniqueStyles.set(styleKey, { id: styleId, style: normalizedStyle });
+            return styleId;
+        };
+        // Collect all styles from pages and buttons
+        Object.values(tree.pages).forEach((page) => {
+            addStyle(page.style);
+            page.buttons.forEach((button) => {
+                addStyle(button.style);
+            });
+        });
+        // Track which grid files we're modifying
+        const modifiedGridFiles = new Set();
+        // Generate grid.xml files for pages in the tree
+        const newGridFiles = new Map();
+        for (const page of Object.values(tree.pages)) {
+            const gridPath = `Grids/${page.name}/grid.xml`;
+            modifiedGridFiles.add(gridPath);
+            // Build the grid XML content
+            const gridData = {
+                Grid: {
+                    '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+                    GridGuid: page.id,
+                    ColumnDefinitions: this.calculateColumnDefinitions(page),
+                    RowDefinitions: this.calculateRowDefinitions(page, false),
+                    AutoContentCommands: '',
+                    Cells: page.buttons.length > 0
+                        ? {
+                            Cell: this.filterPageButtons(page.buttons).map((button, btnIndex) => {
+                                const buttonStyleId = button.style ? addStyle(button.style) : '';
+                                const position = this.findButtonPosition(page, button, btnIndex);
+                                const captionAndImage = {
+                                    Caption: button.label || '',
+                                };
+                                // Handle image references
+                                if (button.image) {
+                                    captionAndImage.Image = `${button.image}`;
+                                }
+                                const cell = {
+                                    '@_Column': position.x,
+                                    '@_Row': position.y,
+                                    captionAndImage,
+                                };
+                                if (position.columnSpan > 1) {
+                                    cell['@_ColumnSpan'] = position.columnSpan;
+                                }
+                                if (position.rowSpan > 1) {
+                                    cell['@_RowSpan'] = position.rowSpan;
+                                }
+                                if (buttonStyleId) {
+                                    cell.CellStyle = buttonStyleId;
+                                }
+                                if (button.message && button.message !== button.label) {
+                                    // Use spoken message if different from label
+                                    const spoken = button.message;
+                                    const cellContent = {
+                                        spoken,
+                                        type: 'text',
+                                    };
+                                    cell['ContentCell'] = cellContent;
+                                }
+                                return cell;
+                            }),
+                        }
+                        : undefined,
+                },
+            };
+            const gridBuilder = new fast_xml_parser_1.XMLBuilder({
+                ignoreAttributes: false,
+                format: true,
+                indentBy: '  ',
+                suppressEmptyNode: true,
+            });
+            newGridFiles.set(gridPath, gridBuilder.build(gridData));
+        }
+        // Copy all files from original zip, replacing modified grid files
+        for (const entry of originalZip.getEntries()) {
+            if (entry.isDirectory)
+                continue;
+            // Skip grid.xml files that we're modifying
+            if (modifiedGridFiles.has(entry.entryName)) {
+                const newContent = newGridFiles.get(entry.entryName);
+                if (newContent) {
+                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
+                }
+                continue;
+            }
+            // Copy all other files as-is
+            outputZip.addFile(entry.entryName, entry.getData());
+        }
+        // Write the output ZIP
+        const outputBuffer = outputZip.toBuffer();
+        await writeBinaryToPath(outputPath, outputBuffer);
+    }
     // Helper method to find button position with span information
     findButtonPosition(page, button, fallbackIndex) {
         if (page.grid && page.grid.length > 0) {

package/dist/processors/obfProcessor.d.ts

@@ -23,6 +23,15 @@ declare class ObfProcessor extends BaseProcessor {
     private createObfBoardFromPage;
     processTexts(filePathOrBuffer: ProcessorInput, translations: Map<string, string>, outputPath: string): Promise<Uint8Array>;
     saveFromTree(tree: AACTree, outputPath: string): Promise<void>;
+    /**
+     * Save a modified tree while preserving all original files (images, sounds, assets)
+     * This method only updates the .obf files for pages in the tree, keeping everything else intact.
+     *
+     * @param originalPath - Path to the original OBF/OBZ file
+     * @param tree - Modified AACTree with pages to save
+     * @param outputPath - Path where the modified file should be saved
+     */
+    saveModifiedTree(originalPath: string, tree: AACTree, outputPath: string): Promise<void>;
     /**
      * Extract strings with metadata for aac-tools-platform compatibility
      * Uses the generic implementation from BaseProcessor

package/dist/processors/obfProcessor.js

@@ -1,4 +1,27 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObfProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
@@ -619,6 +642,75 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
             await writeBinaryToPath(outputPath, zipData);
         }
     }
+    /**
+     * Save a modified tree while preserving all original files (images, sounds, assets)
+     * This method only updates the .obf files for pages in the tree, keeping everything else intact.
+     *
+     * @param originalPath - Path to the original OBF/OBZ file
+     * @param tree - Modified AACTree with pages to save
+     * @param outputPath - Path where the modified file should be saved
+     */
+    async saveModifiedTree(originalPath, tree, outputPath) {
+        const { writeBinaryToPath, readBinaryFromInput } = this.options.fileAdapter;
+        // If output is .obf (single file), use regular save
+        if (outputPath.endsWith('.obf')) {
+            await this.saveFromTree(tree, outputPath);
+            return;
+        }
+        if (Object.keys(tree.pages).length === 0) {
+            // Empty tree, just copy the original
+            const originalBuffer = await readBinaryFromInput(originalPath);
+            await writeBinaryToPath(outputPath, originalBuffer);
+            return;
+        }
+        const AdmZip = (await Promise.resolve().then(() => __importStar(require('adm-zip')))).default;
+        const originalZip = new AdmZip(originalPath);
+        const outputZip = new AdmZip();
+        const getPageFilename = (id) => (id.endsWith('.obf') ? id : `${id}.obf`);
+        // Track which .obf files we're modifying
+        const modifiedObfFiles = new Set();
+        // Generate new .obf files for pages in the tree
+        const newObfFiles = new Map();
+        for (const page of Object.values(tree.pages)) {
+            const obfFilename = getPageFilename(page.id);
+            modifiedObfFiles.add(obfFilename);
+            const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
+            const obfContent = JSON.stringify(obfBoard, null, 2);
+            newObfFiles.set(obfFilename, obfContent);
+        }
+        // Generate updated manifest if we have pages
+        if (Object.keys(tree.pages).length > 0) {
+            modifiedObfFiles.add('manifest.json');
+            const manifest = {
+                format: OBF_FORMAT_VERSION,
+                root: tree.metadata.defaultHomePageId,
+                paths: {
+                    boards: Object.fromEntries(Object.entries(tree.pages).map(([id, page]) => [id, getPageFilename(page.id)])),
+                    images: {},
+                    sounds: {},
+                },
+            };
+            newObfFiles.set('manifest.json', JSON.stringify(manifest));
+        }
+        // Copy all files from original zip, replacing modified .obf files
+        for (const entry of originalZip.getEntries()) {
+            if (entry.isDirectory)
+                continue;
+            // Skip .obf files that we're modifying
+            if (modifiedObfFiles.has(entry.entryName)) {
+                const newContent = newObfFiles.get(entry.entryName);
+                if (newContent) {
+                    outputZip.addFile(entry.entryName, Buffer.from(newContent, 'utf8'));
+                }
+                continue;
+            }
+            // Copy all other files as-is (preserves images, sounds, etc.)
+            outputZip.addFile(entry.entryName, entry.getData());
+        }
+        // Write the output ZIP
+        const outputBuffer = outputZip.toBuffer();
+        await writeBinaryToPath(outputPath, outputBuffer);
+    }
     /**
      * Extract strings with metadata for aac-tools-platform compatibility
      * Uses the generic implementation from BaseProcessor

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

@@ -807,6 +807,10 @@ class MetricsCalculator {
                     }
                     if (!parentMetrics)
                         return;
+                    // Build set of original Suggest Words predictions (from Prediction.PredictThis).
+                    // These require an extra confirmation tap from the user. Smart grammar
+                    // morphology outcomes are generated automatically and need no extra tap.
+                    const suggestWordsSet = new Set((btn.parameters?.predictions || []).map((w) => w.toLowerCase()));
                     // Calculate effort for each word form
                     btn.predictions.forEach((wordForm, index) => {
                         const wordFormLower = wordForm.toLowerCase();
@@ -819,8 +823,14 @@ class MetricsCalculator {
                         // Using similar logic to button scanning effort
                         const predictionPriorItems = predictionRowIndex * predictionsGridCols + predictionColIndex;
                         const predictionSelectionEffort = (0, effort_1.visualScanEffort)(predictionPriorItems);
-                        // Word form effort = parent button's cumulative effort + selection effort
-                        const wordFormEffort = parentMetrics.effort + predictionSelectionEffort;
+                        // 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_1.EFFORT_CONSTANTS.SUGGEST_WORDS_SELECTION_EFFORT
+                            : 0;
+                        // Word form effort = parent button's cumulative effort + selection effort + confirmation
+                        const 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
@@ -841,9 +851,10 @@ class MetricsCalculator {
                             semantic_id: parentMetrics.semantic_id,
                             clone_id: parentMetrics.clone_id,
                             temporary_home_id: parentMetrics.temporary_home_id,
-                            is_word_form: true, // Mark this as a word form metric
-                            parent_button_id: btn.id, // Track parent button
-                            parent_button_label: parentMetrics.label, // Track parent label
+                            is_word_form: true,
+                            is_suggest_words: suggestWordsSet.has(wordFormLower) || undefined,
+                            parent_button_id: btn.id,
+                            parent_button_label: parentMetrics.label,
                         };
                         wordFormMetrics.push(wordFormBtn);
                         existingLabels.set(wordFormLower, wordFormBtn);

package/dist/utilities/analytics/metrics/effort.d.ts

@@ -31,6 +31,7 @@ export declare const EFFORT_CONSTANTS: {
     readonly SCAN_SELECTION_COST: 0.1;
     readonly DEFAULT_SCAN_ERROR_RATE: 0.1;
     readonly SCAN_RETRY_PENALTY: 1;
+    readonly SUGGEST_WORDS_SELECTION_EFFORT: 0.5;
 };
 /**
  * Calculate button size effort based on grid dimensions

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

@@ -47,6 +47,7 @@ exports.EFFORT_CONSTANTS = {
     SCAN_SELECTION_COST: 0.1, // Cost of a switch selection
     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
 };
 /**
  * Calculate button size effort based on grid dimensions

package/dist/utilities/analytics/metrics/types.d.ts

@@ -19,6 +19,7 @@ export interface ButtonMetrics {
     comp_level?: number;
     comp_effort?: number;
     is_word_form?: boolean;
+    is_suggest_words?: boolean;
     parent_button_id?: string;
     parent_button_label?: string;
     pos?: string;

package/package.json

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