@willwade/aac-processors 0.1.7 → 0.1.8

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

@@ -0,0 +1,775 @@
+/**
+ * Core Metrics Analysis Engine
+ *
+ * Implements the main BFS traversal algorithm from the Ruby aac-metrics tool.
+ * Calculates effort scores for all buttons in an AAC board set.
+ *
+ * Based on: aac-metrics/lib/aac-metrics/metrics.rb
+ */
+import { AACSemanticCategory, AACScanType, } from '../../../core/treeStructure';
+import { CellScanningOrder, ScanningSelectionMethod } from '../../../types/aac';
+import { baseBoardEffort, distanceEffort, visualScanEffort, EFFORT_CONSTANTS, localScanEffort, scanningEffort, } from './effort';
+export class MetricsCalculator {
+    constructor() {
+        this.locale = 'en';
+    }
+    /**
+     * Main analysis function - calculates metrics for an AAC tree
+     *
+     * @param tree - The AAC tree to analyze
+     * @param options - Optional configuration for metrics calculation
+     * @returns Complete metrics result
+     */
+    analyze(tree, options = {}) {
+        // Get root board - prioritize tree.rootId, then fall back to boards with no parentId
+        let rootBoard;
+        if (tree.rootId) {
+            rootBoard = tree.pages[tree.rootId];
+        }
+        if (!rootBoard) {
+            rootBoard = Object.values(tree.pages).find((p) => !p.parentId);
+        }
+        if (!rootBoard) {
+            throw new Error('No root board found in tree');
+        }
+        this.locale = tree.metadata?.locale || rootBoard.locale || 'en';
+        // Step 1: Build semantic/clone reference maps
+        const { setRefs, setPcts } = this.buildReferenceMaps(tree);
+        // Step 2: BFS traversal from root board
+        const startBoards = [rootBoard];
+        // Find boards with temporary_home settings
+        Object.values(tree.pages).forEach((board) => {
+            board.buttons.forEach((btn) => {
+                if (btn.targetPageId && btn.semanticAction) {
+                    // Check for temporary_home in platformData or fallback
+                    const tempHome = btn.semanticAction.platformData?.grid3?.parameters?.temporary_home ||
+                        btn.semanticAction.fallback?.temporary_home;
+                    if (tempHome === 'prior') {
+                        startBoards.push(board);
+                    }
+                    else if (tempHome === true && btn.targetPageId) {
+                        const targetBoard = tree.getPage(btn.targetPageId);
+                        if (targetBoard && !startBoards.includes(targetBoard)) {
+                            startBoards.push(targetBoard);
+                        }
+                    }
+                }
+            });
+        });
+        const knownButtons = new Map();
+        const levels = {};
+        let totalButtons = 0;
+        // Identify spelling/keyboard page and its access effort
+        const { spellingPage, spellingBaseEffort, spellingAvgLetterEffort } = this.identifySpellingMetrics(tree, options, setPcts);
+        // Analyze from each starting board
+        startBoards.forEach((startBoard) => {
+            const result = this.analyzeFrom(tree, startBoard, setPcts, startBoard === rootBoard, options);
+            result.buttons.forEach((btn) => {
+                const existing = knownButtons.get(btn.label);
+                if (!existing || btn.effort < existing.effort) {
+                    knownButtons.set(btn.label, btn);
+                }
+                if (btn.count && existing && existing.count) {
+                    btn.count += existing.count;
+                }
+            });
+            if (startBoard === rootBoard) {
+                Object.assign(levels, result.levels);
+                totalButtons = result.totalButtons;
+            }
+        });
+        // 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;
+        if (useSmartGrammar) {
+            const { wordFormMetrics, replacedLabels } = this.calculateWordFormMetrics(tree, buttons, options);
+            // Remove buttons that were replaced by lower-effort word forms
+            const filteredButtons = buttons.filter((btn) => !replacedLabels.has(btn.label.toLowerCase()));
+            // Add word forms and re-sort
+            filteredButtons.push(...wordFormMetrics);
+            filteredButtons.sort((a, b) => a.effort - b.effort);
+            // Replace the original buttons array
+            buttons.length = 0;
+            buttons.push(...filteredButtons);
+        }
+        // Calculate grid dimensions
+        const grid = this.calculateGridDimensions(tree);
+        // Identify prediction metrics
+        let predictionPageId;
+        let hasDynamicPrediction = false;
+        // A page is prediction-capable if it has an AutoContent Prediction button reachable from root
+        // We already have analyzed from rootBoard
+        if (rootBoard) {
+            const rootAnalysis = this.analyzeFrom(tree, rootBoard, setPcts, true, options);
+            // Scan reached pages for prediction slots
+            for (const [pageId, _] of rootAnalysis.visitedBoardEfforts) {
+                const page = tree.getPage(pageId);
+                const hasPredictionSlot = page?.buttons.some((b) => b.contentType === 'AutoContent' && b.contentSubType === 'Prediction');
+                if (hasPredictionSlot) {
+                    hasDynamicPrediction = true;
+                    predictionPageId = pageId;
+                    break;
+                }
+            }
+        }
+        return {
+            analysis_version: '0.2',
+            locale: this.locale,
+            total_boards: Object.keys(tree.pages).length,
+            total_buttons: totalButtons,
+            total_words: buttons.length,
+            reference_counts: setRefs,
+            grid,
+            buttons,
+            levels,
+            spelling_effort_base: spellingBaseEffort,
+            spelling_effort_per_letter: spellingAvgLetterEffort,
+            spelling_page_id: spellingPage?.id,
+            has_dynamic_prediction: hasDynamicPrediction,
+            prediction_page_id: predictionPageId,
+        };
+    }
+    /**
+     * Identify keyboard/spelling page and calculate base/avg effort
+     */
+    identifySpellingMetrics(tree, options, setPcts) {
+        let spellingPage = null;
+        if (options.spellingPageId) {
+            spellingPage = tree.getPage(options.spellingPageId) || null;
+        }
+        if (!spellingPage && tree.metadata?.defaultKeyboardPageId) {
+            spellingPage = tree.getPage(tree.metadata.defaultKeyboardPageId) || null;
+        }
+        if (!spellingPage) {
+            // Look for pages with keyboard-like names or content
+            spellingPage =
+                Object.values(tree.pages).find((p) => {
+                    const name = p.name.toLowerCase();
+                    return name.includes('keyboard') || name.includes('spelling') || name.includes('abc');
+                }) || null;
+        }
+        if (!spellingPage)
+            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 };
+        // 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;
+        // Calculate average effort of alphabetical buttons on that page
+        const letters = spellingPage.buttons.filter((b) => b.label.length === 1 && /[a-zA-Z]/.test(b.label));
+        let avgEffort = 2.5;
+        if (letters.length > 0) {
+            // We need to calculate the effort of these buttons relative to the spelling page itself
+            // (as if the user is already on the keyboard)
+            const keyboardResult = this.analyzeFrom(tree, spellingPage, setPcts, false, options);
+            const keyboardLetters = keyboardResult.buttons.filter((b) => b.label.length === 1 && /[a-zA-Z]/.test(b.label));
+            if (keyboardLetters.length > 0) {
+                avgEffort = keyboardLetters.reduce((sum, b) => sum + b.effort, 0) / keyboardLetters.length;
+            }
+        }
+        return {
+            spellingPage,
+            spellingBaseEffort,
+            spellingAvgLetterEffort: avgEffort,
+        };
+    }
+    /**
+     * Build reference maps for semantic_id and clone_id frequencies
+     */
+    buildReferenceMaps(tree) {
+        const setRefs = {};
+        const cellRefs = {};
+        let rootRows = 0;
+        let rootCols = 0;
+        // First pass: calculate dimensions and count references
+        Object.values(tree.pages).forEach((board) => {
+            rootRows = rootRows || board.grid.length;
+            rootCols = rootCols || board.grid[0]?.length || 0;
+            // Count semantic_id and clone_id occurrences from board properties (upstream)
+            board.semantic_ids?.forEach((id) => {
+                setRefs[id] = (setRefs[id] || 0) + 1;
+            });
+            board.clone_ids?.forEach((id) => {
+                setRefs[id] = (setRefs[id] || 0) + 1;
+            });
+            // Count cell references
+            for (let r = 0; r < board.grid.length; r++) {
+                for (let c = 0; c < (board.grid[r]?.length || 0); c++) {
+                    const ref = `${r}.${c}`;
+                    const hasButton = board.grid[r][c] !== null;
+                    cellRefs[ref] = (cellRefs[ref] || 0) + (hasButton ? 1.0 : 0.25);
+                }
+            }
+        });
+        // Calculate percentages
+        const setPcts = {};
+        const totalBoards = Object.keys(tree.pages).length;
+        Object.entries(setRefs).forEach(([id, count]) => {
+            // Extract location from ID (Ruby uses id.split(/-/)[1])
+            const parts = id.split('-');
+            if (parts.length >= 2) {
+                const loc = parts[1];
+                const cellCount = cellRefs[loc] || totalBoards;
+                setPcts[id] = count / cellCount;
+                if (setPcts[id] > 1.0) {
+                    // console.log(`⚠️ setPcts[${id}] = ${setPcts[id].toFixed(4)} (count=${count}, cellCount=${cellCount.toFixed(2)})`);
+                    setPcts[id] = 1.0; // Cap at 1.0 like Ruby effectively does
+                }
+            }
+            else {
+                setPcts[id] = count / totalBoards;
+            }
+        });
+        return { setRefs, setPcts };
+    }
+    /**
+     * Count scan items for visual scanning effort
+     * When block scanning is enabled, count unique scan blocks instead of individual buttons
+     */
+    countScanBlocks(board, currentRowIndex, currentColIndex, priorScanBlocks) {
+        // Block scanning: count unique scan blocks before current position
+        // Reuse the priorScanBlocks set from the parent scope
+        for (let r = 0; r <= currentRowIndex; r++) {
+            const row = board.grid[r];
+            if (!row)
+                continue;
+            for (let c = 0; c < row.length; c++) {
+                if (r === currentRowIndex && c === currentColIndex)
+                    return priorScanBlocks.size;
+                const btn = row[c];
+                if (btn && (btn.label || btn.id).length > 0) {
+                    const block = btn.scanBlock ||
+                        (btn.scanBlocks && btn.scanBlocks.length > 0 ? btn.scanBlocks[0] : null);
+                    if (block !== null)
+                        priorScanBlocks.add(block);
+                }
+            }
+        }
+        return priorScanBlocks.size;
+    }
+    /**
+     * Analyze starting from a specific board
+     */
+    analyzeFrom(tree, brd, setPcts, _isRoot, options = {}) {
+        const visitedBoardIds = new Map();
+        const visitedBoardEfforts = new Map();
+        const toVisit = [
+            {
+                board: brd,
+                level: 0,
+                entryX: 1.0,
+                entryY: 1.0,
+            },
+        ];
+        const knownButtons = new Map();
+        const levels = {};
+        while (toVisit.length > 0) {
+            const item = toVisit.shift();
+            if (!item)
+                break;
+            const { board, level, entryX, entryY, priorEffort = 0, temporaryHomeId } = item;
+            // Skip if already visited at a lower level with equal or better prior effort
+            // Skip if already visited at a strictly lower level
+            const existingLevel = visitedBoardIds.get(board.id);
+            if (existingLevel !== undefined && existingLevel < level) {
+                continue;
+            }
+            visitedBoardIds.set(board.id, level);
+            visitedBoardEfforts.set(board.id, priorEffort);
+            const rows = board.grid.length;
+            const cols = board.grid[0]?.length || 0;
+            // Calculate board-level effort
+            // Ruby uses grid size (rows * cols) for field size effort
+            const gridSize = rows * cols;
+            let boardEffort = baseBoardEffort(rows, cols, gridSize);
+            // Apply reuse discounts - iterate through grid cells like Ruby does
+            let reuseDiscount = 0.0;
+            board.grid.forEach((row) => {
+                row.forEach((btn) => {
+                    if (!btn)
+                        return;
+                    if (btn.clone_id && setPcts[btn.clone_id]) {
+                        reuseDiscount += EFFORT_CONSTANTS.REUSED_CLONE_FROM_OTHER_BONUS * setPcts[btn.clone_id];
+                    }
+                    else if (btn.semantic_id && setPcts[btn.semantic_id]) {
+                        reuseDiscount +=
+                            EFFORT_CONSTANTS.REUSED_SEMANTIC_FROM_OTHER_BONUS * setPcts[btn.semantic_id];
+                    }
+                });
+            });
+            boardEffort = Math.max(0, boardEffort - reuseDiscount);
+            // Calculate board link percentages
+            const boardPcts = this.calculateBoardLinkPercentages(tree, board);
+            // Get scanning configuration from page (if available) or options
+            const scanningConfig = options.scanningConfig || board.scanningConfig;
+            const blockScanEnabled = scanningConfig?.blockScanEnabled || false;
+            // Process each button
+            const btnHeight = 1.0 / rows;
+            const btnWidth = 1.0 / cols;
+            // Track scan blocks for block scanning
+            const priorScanBlocks = new Set();
+            // Iterate over grid positions directly (not just buttons)
+            // This matches Ruby's nested loop: rows.times do |row_idx|; columns.times do |col_idx|
+            for (let rowIndex = 0; rowIndex < rows; rowIndex++) {
+                for (let colIndex = 0; colIndex < cols; colIndex++) {
+                    const btn = board.grid[rowIndex]?.[colIndex];
+                    if (!btn)
+                        continue; // Skip empty cells
+                    const x = btnWidth / 2 + btnWidth * colIndex;
+                    const y = btnHeight / 2 + btnHeight * rowIndex;
+                    // Calculate prior grid positions (not just buttons)
+                    // This matches Ruby's prior_buttons which increments for each grid position
+                    const priorGridPositions = rowIndex * cols + colIndex;
+                    // For block scanning, count unique scan blocks instead
+                    const priorItems = blockScanEnabled
+                        ? this.countScanBlocks(board, rowIndex, colIndex, priorScanBlocks)
+                        : priorGridPositions;
+                    // Calculate button-level effort
+                    let buttonEffort = boardEffort;
+                    // Debug for specific button (disabled for production)
+                    const debugSpecificButton = btn.label === '$938c2cc0dc';
+                    if (debugSpecificButton) {
+                        console.log(`\n🔍 DEBUG Button ${btn.label} at [${rowIndex},${colIndex}] on ${board.id}:`);
+                        console.log(`   Entry point: (${entryX.toFixed(4)}, ${entryY.toFixed(4)})`);
+                        console.log(`   Current level: ${level}`);
+                        console.log(`   Prior positions: ${priorItems}`);
+                        console.log(`   Starting effort: ${buttonEffort.toFixed(6)}`);
+                    }
+                    // Apply semantic_id discounts
+                    if (btn.semantic_id && boardPcts[btn.semantic_id]) {
+                        const discount = EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.semantic_id];
+                        const old = buttonEffort;
+                        buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
+                        if (debugSpecificButton)
+                            console.log(`   Semantic board discount: ${old.toFixed(6)} -> ${buttonEffort.toFixed(6)} (pct=${boardPcts[btn.semantic_id].toFixed(4)})`);
+                    }
+                    else if (btn.semantic_id && boardPcts[`upstream-${btn.semantic_id}`]) {
+                        const discount = EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT /
+                            boardPcts[`upstream-${btn.semantic_id}`];
+                        const old = buttonEffort;
+                        buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
+                        if (debugSpecificButton)
+                            console.log(`   Semantic upstream discount: ${old.toFixed(6)} -> ${buttonEffort.toFixed(6)} (pct=${boardPcts[`upstream-${btn.semantic_id}`].toFixed(4)})`);
+                    }
+                    // Apply clone_id discounts
+                    if (btn.clone_id && boardPcts[btn.clone_id]) {
+                        const discount = EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.clone_id];
+                        buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
+                    }
+                    else if (btn.clone_id && boardPcts[`upstream-${btn.clone_id}`]) {
+                        const discount = EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT /
+                            boardPcts[`upstream-${btn.clone_id}`];
+                        buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
+                    }
+                    // Calculate button effort based on access method (Touch vs Scanning)
+                    const isScanning = !!scanningConfig || !!board.scanType;
+                    if (isScanning) {
+                        const { steps, selections, loopSteps } = this.calculateScanSteps(board, btn, rowIndex, colIndex, scanningConfig);
+                        // Determine effective costs based on selection method
+                        let currentStepCost = options.scanStepCost ?? EFFORT_CONSTANTS.SCAN_STEP_COST;
+                        const currentSelectionCost = options.scanSelectionCost ?? EFFORT_CONSTANTS.SCAN_SELECTION_COST;
+                        // Step Scan 2 Switch: Every step is a physical selection with Switch 1
+                        if (scanningConfig?.selectionMethod === ScanningSelectionMethod.StepScan2Switch) {
+                            // The cost of moving is now a selection cost
+                            currentStepCost = currentSelectionCost;
+                        }
+                        else if (scanningConfig?.selectionMethod === ScanningSelectionMethod.StepScan1Switch) {
+                            // Single switch step scan: every step is a physical selection
+                            currentStepCost = currentSelectionCost;
+                        }
+                        let sEffort = scanningEffort(steps, selections, currentStepCost, currentSelectionCost);
+                        // Factor in error correction if enabled
+                        if (scanningConfig?.errorCorrectionEnabled) {
+                            const errorRate = scanningConfig.errorRate ?? EFFORT_CONSTANTS.DEFAULT_SCAN_ERROR_RATE;
+                            // A "miss" results in needing to wait for a loop (or part of one)
+                            // We model this as errorRate * (loopSteps * stepCost)
+                            const retryPenalty = loopSteps * currentStepCost;
+                            sEffort += errorRate * retryPenalty;
+                        }
+                        // Apply discounts to scanning effort (similar to touch)
+                        if (btn.semantic_id && boardPcts[btn.semantic_id]) {
+                            const discount = EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.semantic_id];
+                            sEffort = Math.min(sEffort, sEffort * discount);
+                        }
+                        else if (btn.clone_id && boardPcts[btn.clone_id]) {
+                            const discount = EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.clone_id];
+                            sEffort = Math.min(sEffort, sEffort * discount);
+                        }
+                        buttonEffort += sEffort;
+                    }
+                    else {
+                        // Add distance effort (Touch only)
+                        let distance = distanceEffort(x, y, entryX, entryY);
+                        // Apply distance discounts
+                        if (btn.semantic_id) {
+                            if (boardPcts[btn.semantic_id]) {
+                                const discount = EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.semantic_id];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                            else if (boardPcts[`upstream-${btn.semantic_id}`]) {
+                                const discount = EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT /
+                                    boardPcts[`upstream-${btn.semantic_id}`];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                            else if (level > 0 && setPcts[btn.semantic_id]) {
+                                const discount = EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_OTHER_DISCOUNT /
+                                    setPcts[btn.semantic_id];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                        }
+                        if (btn.clone_id) {
+                            if (boardPcts[btn.clone_id]) {
+                                const discount = EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.clone_id];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                            else if (boardPcts[`upstream-${btn.clone_id}`]) {
+                                const discount = EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT /
+                                    boardPcts[`upstream-${btn.clone_id}`];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                            else if (level > 0 && setPcts[btn.clone_id]) {
+                                const discount = EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT / setPcts[btn.clone_id];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                        }
+                        buttonEffort += distance;
+                        // Add visual scan or local scan effort
+                        if (distance > EFFORT_CONSTANTS.DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN ||
+                            (entryX === 1.0 && entryY === 1.0)) {
+                            buttonEffort += visualScanEffort(priorItems);
+                        }
+                        else {
+                            buttonEffort += localScanEffort(distance);
+                        }
+                    }
+                    // Add cumulative prior effort
+                    buttonEffort += priorEffort;
+                    // Track scan blocks for block scanning, otherwise track individual buttons
+                    if (blockScanEnabled) {
+                        const scanBlockId = btn.scanBlock ?? btn.scanBlocks?.[0];
+                        if (scanBlockId !== undefined && scanBlockId !== null) {
+                            priorScanBlocks.add(scanBlockId);
+                        }
+                    }
+                    // Handle navigation buttons
+                    if (btn.targetPageId) {
+                        const nextBoard = tree.getPage(btn.targetPageId);
+                        if (nextBoard) {
+                            // Only add to toVisit if this board hasn't been visited yet at any level
+                            // The visitedBoardIds map stores the *lowest* level a board was visited.
+                            // If it's already in the map, it means we've processed it or scheduled it at a lower level.
+                            if (visitedBoardIds.get(nextBoard.id) === undefined) {
+                                const changeEffort = EFFORT_CONSTANTS.BOARD_CHANGE_PROCESSING_EFFORT;
+                                const tempHomeId = btn.semanticAction?.platformData?.grid3?.parameters?.temporary_home === 'prior'
+                                    ? board.id
+                                    : btn.semanticAction?.platformData?.grid3?.parameters?.temporary_home === true
+                                        ? btn.targetPageId
+                                        : temporaryHomeId;
+                                toVisit.push({
+                                    board: nextBoard,
+                                    level: level + 1,
+                                    priorEffort: buttonEffort + changeEffort,
+                                    temporaryHomeId: tempHomeId,
+                                    entryX: x,
+                                    entryY: y,
+                                    entryCloneId: btn.clone_id,
+                                    entrySemanticId: btn.semantic_id,
+                                });
+                            }
+                        }
+                    }
+                    // Track word if it speaks or adds to sentence
+                    const isSpeak = btn.semanticAction?.category === AACSemanticCategory.COMMUNICATION && !btn.targetPageId; // Must not be a navigation button
+                    const addToSentence = btn.semanticAction?.platformData?.grid3?.parameters?.add_to_sentence ||
+                        btn.semanticAction?.fallback?.add_to_sentence;
+                    if (isSpeak || addToSentence) {
+                        let finalEffort = buttonEffort;
+                        // Apply Board Change Processing Effort Discount (matching Ruby lines 347-350)
+                        const changeEffort = EFFORT_CONSTANTS.BOARD_CHANGE_PROCESSING_EFFORT;
+                        if (btn.clone_id && boardPcts[btn.clone_id]) {
+                            const discount = Math.min(changeEffort, (changeEffort * 0.3) / boardPcts[btn.clone_id]);
+                            finalEffort -= discount;
+                        }
+                        else if (btn.semantic_id && boardPcts[btn.semantic_id]) {
+                            const discount = Math.min(changeEffort, (changeEffort * 0.5) / boardPcts[btn.semantic_id]);
+                            finalEffort -= discount;
+                        }
+                        const existing = knownButtons.get(btn.label);
+                        const knownBtn = {
+                            id: btn.id,
+                            label: btn.label,
+                            level,
+                            effort: finalEffort,
+                            count: (existing?.count || 0) + 1,
+                            semantic_id: btn.semantic_id,
+                            clone_id: btn.clone_id,
+                            temporary_home_id: temporaryHomeId || undefined,
+                        };
+                        if (!existing || finalEffort < existing.effort) {
+                            knownButtons.set(btn.label, knownBtn);
+                        }
+                    }
+                }
+            }
+        }
+        // Convert to array and group by level
+        const buttons = Array.from(knownButtons.values());
+        buttons.forEach((btn) => {
+            if (!levels[btn.level]) {
+                levels[btn.level] = [];
+            }
+            levels[btn.level].push(btn);
+        });
+        // Calculate total_buttons as sum of all button counts (matching Ruby line 136)
+        // Ruby: total_buttons: buttons.map{|b| b[:count] || 1}.sum
+        const calculatedTotalButtons = buttons.reduce((sum, btn) => sum + (btn.count || 1), 0);
+        return {
+            buttons,
+            levels,
+            totalButtons: calculatedTotalButtons,
+            visitedBoardEfforts,
+        };
+    }
+    /**
+     * Calculate what percentage of links to this board match semantic_id/clone_id
+     */
+    calculateBoardLinkPercentages(tree, board) {
+        const boardPcts = {};
+        let totalLinks = 0;
+        Object.values(tree.pages).forEach((sourceBoard) => {
+            sourceBoard.buttons.forEach((btn) => {
+                if (btn.targetPageId === board.id) {
+                    totalLinks++;
+                    if (btn.semantic_id) {
+                        boardPcts[btn.semantic_id] = (boardPcts[btn.semantic_id] || 0) + 1;
+                    }
+                    if (btn.clone_id) {
+                        boardPcts[btn.clone_id] = (boardPcts[btn.clone_id] || 0) + 1;
+                    }
+                    // Also count IDs present on the source board that links to this one
+                    sourceBoard.semantic_ids?.forEach((id) => {
+                        boardPcts[`upstream-${id}`] = (boardPcts[`upstream-${id}`] || 0) + 1;
+                    });
+                    sourceBoard.clone_ids?.forEach((id) => {
+                        boardPcts[`upstream-${id}`] = (boardPcts[`upstream-${id}`] || 0) + 1;
+                    });
+                }
+            });
+        });
+        // Convert counts to percentages
+        if (totalLinks > 0) {
+            Object.keys(boardPcts).forEach((id) => {
+                boardPcts[id] = boardPcts[id] / totalLinks;
+            });
+        }
+        boardPcts['all'] = totalLinks;
+        return boardPcts;
+    }
+    /**
+     * Calculate metrics for word forms (smart grammar predictions)
+     *
+     * Word forms are dynamically generated and not part of the tree structure.
+     * Their effort is calculated as:
+     * - Parent button's cumulative effort (to reach the button)
+     * - + Effort to select the word form from its position in predictions grid
+     *
+     * If a word exists as both a regular button and a word form, the version
+     * with lower effort is kept.
+     *
+     * @param tree - The AAC tree
+     * @param buttons - Already calculated button metrics
+     * @param options - Metrics options
+     * @returns Object containing word form metrics and labels that were replaced
+     */
+    calculateWordFormMetrics(tree, buttons, _options = {}) {
+        const wordFormMetrics = [];
+        const replacedLabels = new Set();
+        // Track buttons by label to compare efforts
+        const existingLabels = new Map();
+        buttons.forEach((btn) => existingLabels.set(btn.label.toLowerCase(), btn));
+        // 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);
+                    if (!parentMetrics)
+                        return;
+                    // 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);
+                        // Word form effort = parent button's cumulative effort + selection effort
+                        const wordFormEffort = parentMetrics.effort + predictionSelectionEffort;
+                        // 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
+                        if (existingBtn && existingBtn.effort <= wordFormEffort) {
+                            return;
+                        }
+                        // If word exists but word form has lower effort, mark for replacement
+                        if (existingBtn && existingBtn.effort > wordFormEffort) {
+                            replacedLabels.add(wordFormLower);
+                        }
+                        // Create word form metric
+                        const wordFormBtn = {
+                            id: `${btn.id}_wordform_${index}`,
+                            label: wordForm,
+                            level: parentMetrics.level,
+                            effort: wordFormEffort,
+                            count: 1,
+                            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
+                        };
+                        wordFormMetrics.push(wordFormBtn);
+                        existingLabels.set(wordFormLower, wordFormBtn);
+                    });
+                });
+            });
+        });
+        console.log(`📝 Calculated ${wordFormMetrics.length} word form metrics` +
+            (replacedLabels.size > 0
+                ? ` (${replacedLabels.size} replaced higher-effort buttons: ${Array.from(replacedLabels).join(', ')})`
+                : ''));
+        return { wordFormMetrics, replacedLabels };
+    }
+    /**
+     * Calculate grid dimensions from the tree
+     */
+    calculateGridDimensions(tree) {
+        let totalRows = 0;
+        let totalCols = 0;
+        let count = 0;
+        Object.values(tree.pages).forEach((page) => {
+            totalRows += page.grid.length;
+            totalCols += page.grid[0]?.length || 0;
+            count++;
+        });
+        return {
+            rows: Math.round(totalRows / count),
+            columns: Math.round(totalCols / count),
+        };
+    }
+    /**
+     * Calculate scanning steps and selections for a button based on access method
+     */
+    calculateScanSteps(board, btn, rowIndex, colIndex, overrideConfig) {
+        const config = overrideConfig || board.scanningConfig;
+        // Determine scanning type from local scanType or scanningConfig
+        let type = board.scanType || AACScanType.LINEAR;
+        if (config?.cellScanningOrder) {
+            const order = config.cellScanningOrder;
+            // String matching for CellScanningOrder
+            if (order === CellScanningOrder.RowColumnScan)
+                type = AACScanType.ROW_COLUMN;
+            else if (order === CellScanningOrder.ColumnRowScan)
+                type = AACScanType.COLUMN_ROW;
+            else if (order === CellScanningOrder.SimpleScanColumnsFirst)
+                type = AACScanType.COLUMN_ROW;
+            else if (order === CellScanningOrder.SimpleScan)
+                type = AACScanType.LINEAR;
+        }
+        // Force block scan if enabled in config
+        const isBlockScan = config?.blockScanEnabled ||
+            type === AACScanType.BLOCK_ROW_COLUMN ||
+            type === AACScanType.BLOCK_COLUMN_ROW;
+        if (isBlockScan) {
+            const blockId = btn.scanBlock || (btn.scanBlocks && btn.scanBlocks.length > 0 ? btn.scanBlocks[0] : null);
+            // 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 };
+            }
+            const blockConfig = board.scanBlocksConfig?.find((c) => c.id === blockId);
+            const blockOrder = blockConfig?.order ?? blockId;
+            // Count unique blocks
+            const blocks = new Set();
+            let btnInBlockIndex = 0;
+            let itemsInBlock = 0;
+            for (let r = 0; r < board.grid.length; r++) {
+                for (let c = 0; c < (board.grid[r]?.length || 0); c++) {
+                    const b = board.grid[r][c];
+                    if (b) {
+                        const id = b.scanBlock ?? b.scanBlocks?.[0];
+                        if (id !== undefined && id !== null)
+                            blocks.add(id);
+                        if (id === blockId) {
+                            itemsInBlock++;
+                            if (b === btn) {
+                                btnInBlockIndex = itemsInBlock - 1;
+                            }
+                        }
+                    }
+                }
+            }
+            // 1 selection for block, 1 for item
+            return {
+                steps: blockOrder + btnInBlockIndex + 1,
+                selections: 2,
+                loopSteps: blocks.size + itemsInBlock,
+            };
+        }
+        switch (type) {
+            case AACScanType.LINEAR: {
+                let index = 0;
+                let found = false;
+                let totalVisible = 0;
+                for (let r = 0; r < board.grid.length; r++) {
+                    for (let c = 0; c < board.grid[r].length; c++) {
+                        const b = board.grid[r][c];
+                        if (b && (b.label || '').length > 0) {
+                            totalVisible++;
+                            if (!found) {
+                                if (b === btn) {
+                                    found = true;
+                                }
+                                else {
+                                    index++;
+                                }
+                            }
+                        }
+                    }
+                }
+                return { steps: index + 1, selections: 1, loopSteps: totalVisible };
+            }
+            case AACScanType.ROW_COLUMN:
+                return {
+                    steps: rowIndex + 1 + (colIndex + 1),
+                    selections: 2,
+                    loopSteps: board.grid.length + (board.grid[0]?.length || 0),
+                };
+            case AACScanType.COLUMN_ROW:
+                return {
+                    steps: colIndex + 1 + (rowIndex + 1),
+                    selections: 2,
+                    loopSteps: (board.grid[0]?.length || 0) + board.grid.length,
+                };
+            default:
+                return {
+                    steps: rowIndex + 1 + (colIndex + 1),
+                    selections: 2,
+                    loopSteps: board.grid.length + (board.grid[0]?.length || 0),
+                };
+        }
+    }
+}