@willwade/aac-processors 0.0.15 → 0.0.17

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

@@ -20,9 +20,10 @@ class MetricsCalculator {
      * 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) {
+    analyze(tree, options = {}) {
         // Get root board - prioritize tree.rootId, then fall back to boards with no parentId
         let rootBoard;
         if (tree.rootId) {
@@ -61,9 +62,11 @@ class MetricsCalculator {
         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);
+            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) {
@@ -78,10 +81,28 @@ class MetricsCalculator {
                 totalButtons = result.totalButtons;
             }
         });
-        // Convert to array and sort
+        // Update buttons using dynamic spelling effort if applicable
         const buttons = Array.from(knownButtons.values()).sort((a, b) => a.effort - b.effort);
         // 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,
@@ -92,6 +113,56 @@ class MetricsCalculator {
             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) {
+            // 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,
         };
     }
     /**
@@ -189,8 +260,9 @@ class MetricsCalculator {
     /**
      * Analyze starting from a specific board
      */
-    analyzeFrom(tree, brd, setPcts, _isRoot) {
+    analyzeFrom(tree, brd, setPcts, _isRoot, options = {}) {
         const visitedBoardIds = new Map();
+        const visitedBoardEfforts = new Map();
         const toVisit = [
             {
                 board: brd,
@@ -213,6 +285,7 @@ class MetricsCalculator {
                 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
@@ -237,194 +310,219 @@ class MetricsCalculator {
             boardEffort = Math.max(0, boardEffort - reuseDiscount);
             // Calculate board link percentages
             const boardPcts = this.calculateBoardLinkPercentages(tree, board);
-            // Get scanning configuration from page (if available)
-            const blockScanEnabled = board.scanningConfig?.blockScanEnabled || false;
+            // Get scanning configuration from page (if available) or options
+            const scanningConfig = options.scanningConfig || board.scanningConfig;
+            const blockScanEnabled = scanningConfig?.blockScanEnabled || false;
             // Process each button
             const priorScanBlocks = new Set();
             const btnHeight = 1.0 / rows;
             const btnWidth = 1.0 / cols;
-            board.grid.forEach((row, rowIndex) => {
-                row.forEach((btn, colIndex) => {
-                    // Skip null buttons and buttons with empty labels (matching Ruby behavior)
-                    if (!btn || (btn.label || '').length === 0) {
-                        // Don't count these toward prior_buttons (Ruby uses "next unless")
-                        return;
+            // Iterate over all buttons on the page to handle overlapping cells (common in some gridsets like Super Core 50)
+            // Sort buttons by position to ensure consistent prior_buttons/scanning calculation
+            const sortedButtons = [...board.buttons]
+                .filter((b) => (b.label || '').length > 0)
+                .sort((a, b) => {
+                if ((a.y ?? 0) !== (b.y ?? 0))
+                    return (a.y ?? 0) - (b.y ?? 0);
+                return (a.x ?? 0) - (b.x ?? 0);
+            });
+            sortedButtons.forEach((btn) => {
+                const rowIndex = btn.y ?? 0;
+                const colIndex = btn.x ?? 0;
+                const x = btnWidth / 2 + btnWidth * colIndex;
+                const y = btnHeight / 2 + btnHeight * rowIndex;
+                // Calculate prior items for visual scan effort
+                // If block scanning enabled, count unique scan blocks instead of individual buttons
+                const priorItems = this.countScanItems(board, rowIndex, colIndex, priorScanBlocks, blockScanEnabled);
+                // 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(`   Starting effort: ${buttonEffort.toFixed(6)}`);
+                }
+                // Apply semantic_id discounts
+                if (btn.semantic_id && boardPcts[btn.semantic_id]) {
+                    const discount = effort_1.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_1.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_1.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_1.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_1.EFFORT_CONSTANTS.SCAN_STEP_COST;
+                    const currentSelectionCost = options.scanSelectionCost ?? effort_1.EFFORT_CONSTANTS.SCAN_SELECTION_COST;
+                    // Step Scan 2 Switch: Every step is a physical selection with Switch 1
+                    if (scanningConfig?.selectionMethod === aac_1.ScanningSelectionMethod.StepScan2Switch) {
+                        // The cost of moving is now a selection cost
+                        currentStepCost = currentSelectionCost;
+                    }
+                    else if (scanningConfig?.selectionMethod === aac_1.ScanningSelectionMethod.StepScan1Switch) {
+                        // Single switch step scan: every step is a physical selection
+                        currentStepCost = currentSelectionCost;
                     }
-                    const x = btnWidth / 2 + btnWidth * colIndex;
-                    const y = btnHeight / 2 + btnHeight * rowIndex;
-                    // Calculate prior items for visual scan effort
-                    // If block scanning enabled, count unique scan blocks instead of individual buttons
-                    const priorItems = this.countScanItems(board, rowIndex, colIndex, priorScanBlocks, blockScanEnabled);
-                    // 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(`   Starting effort: ${buttonEffort.toFixed(6)}`);
+                    let sEffort = (0, effort_1.scanningEffort)(steps, selections, currentStepCost, currentSelectionCost);
+                    // Factor in error correction if enabled
+                    if (scanningConfig?.errorCorrectionEnabled) {
+                        const errorRate = scanningConfig.errorRate ?? effort_1.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 semantic_id discounts
+                    // Apply discounts to scanning effort (similar to touch)
                     if (btn.semantic_id && boardPcts[btn.semantic_id]) {
                         const discount = effort_1.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_1.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)})`);
+                        sEffort = Math.min(sEffort, sEffort * discount);
                     }
-                    // Apply clone_id discounts
-                    if (btn.clone_id && boardPcts[btn.clone_id]) {
+                    else if (btn.clone_id && boardPcts[btn.clone_id]) {
                         const discount = effort_1.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_1.EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT /
-                            boardPcts[`upstream-${btn.clone_id}`];
-                        buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
+                        sEffort = Math.min(sEffort, sEffort * discount);
                     }
-                    // Calculate button effort based on access method (Touch vs Scanning)
-                    const isScanning = !!board.scanningConfig || !!board.scanType;
-                    if (isScanning) {
-                        const { steps, selections } = this.calculateScanSteps(board, btn, rowIndex, colIndex);
-                        let sEffort = (0, effort_1.scanningEffort)(steps, selections);
-                        // Apply discounts to scanning effort (similar to touch)
-                        if (btn.semantic_id && boardPcts[btn.semantic_id]) {
+                    buttonEffort += sEffort;
+                }
+                else {
+                    // Add distance effort (Touch only)
+                    let distance = (0, effort_1.distanceEffort)(x, y, entryX, entryY);
+                    // Apply distance discounts
+                    if (btn.semantic_id) {
+                        if (boardPcts[btn.semantic_id]) {
                             const discount = effort_1.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.semantic_id];
-                            sEffort = Math.min(sEffort, sEffort * discount);
+                            distance = Math.min(distance, distance * discount);
                         }
-                        else if (btn.clone_id && boardPcts[btn.clone_id]) {
-                            const discount = effort_1.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.clone_id];
-                            sEffort = Math.min(sEffort, sEffort * discount);
+                        else if (boardPcts[`upstream-${btn.semantic_id}`]) {
+                            const discount = effort_1.EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT /
+                                boardPcts[`upstream-${btn.semantic_id}`];
+                            distance = Math.min(distance, distance * discount);
                         }
-                        buttonEffort += sEffort;
-                    }
-                    else {
-                        // Add distance effort (Touch only)
-                        let distance = (0, effort_1.distanceEffort)(x, y, entryX, entryY);
-                        // Apply distance discounts
-                        if (btn.semantic_id) {
-                            if (boardPcts[btn.semantic_id]) {
-                                const discount = effort_1.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_1.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_1.EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_OTHER_DISCOUNT /
-                                    setPcts[btn.semantic_id];
-                                distance = Math.min(distance, distance * discount);
-                            }
+                        else if (level > 0 && setPcts[btn.semantic_id]) {
+                            const discount = effort_1.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_1.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_1.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_1.EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT / setPcts[btn.clone_id];
-                                distance = Math.min(distance, distance * discount);
-                            }
+                    }
+                    if (btn.clone_id) {
+                        if (boardPcts[btn.clone_id]) {
+                            const discount = effort_1.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.clone_id];
+                            distance = Math.min(distance, distance * discount);
                         }
-                        buttonEffort += distance;
-                        // Add visual scan or local scan effort
-                        if (distance > effort_1.EFFORT_CONSTANTS.DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN ||
-                            (entryX === 1.0 && entryY === 1.0)) {
-                            buttonEffort += (0, effort_1.visualScanEffort)(priorItems);
+                        else if (boardPcts[`upstream-${btn.clone_id}`]) {
+                            const discount = effort_1.EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT /
+                                boardPcts[`upstream-${btn.clone_id}`];
+                            distance = Math.min(distance, distance * discount);
                         }
-                        else {
-                            buttonEffort += (0, effort_1.localScanEffort)(distance);
+                        else if (level > 0 && setPcts[btn.clone_id]) {
+                            const discount = effort_1.EFFORT_CONSTANTS.RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT / setPcts[btn.clone_id];
+                            distance = Math.min(distance, distance * discount);
                         }
                     }
-                    // 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);
-                        }
+                    buttonEffort += distance;
+                    // Add visual scan or local scan effort
+                    if (distance > effort_1.EFFORT_CONSTANTS.DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN ||
+                        (entryX === 1.0 && entryY === 1.0)) {
+                        buttonEffort += (0, effort_1.visualScanEffort)(priorItems);
                     }
-                    // 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_1.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,
-                                });
-                            }
-                        }
+                    else {
+                        buttonEffort += (0, effort_1.localScanEffort)(distance);
                     }
-                    // Track word if it speaks or adds to sentence
-                    const intent = String(btn.semanticAction?.intent || '');
-                    const isSpeak = btn.semanticAction?.category === treeStructure_1.AACSemanticCategory.COMMUNICATION ||
-                        intent === 'SPEAK_TEXT' ||
-                        intent === 'SPEAK_IMMEDIATE' ||
-                        intent === 'INSERT_TEXT' ||
-                        btn.semanticAction?.fallback?.type === 'SPEAK';
-                    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_1.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);
+                }
+                // 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_1.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 intent = String(btn.semanticAction?.intent || '');
+                const isSpeak = btn.semanticAction?.category === treeStructure_1.AACSemanticCategory.COMMUNICATION ||
+                    intent === 'SPEAK_TEXT' ||
+                    intent === 'SPEAK_IMMEDIATE' ||
+                    intent === 'INSERT_TEXT' ||
+                    btn.semanticAction?.fallback?.type === 'SPEAK';
+                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_1.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
@@ -435,10 +533,14 @@ class MetricsCalculator {
             }
             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: buttons.length,
+            totalButtons: calculatedTotalButtons,
+            visitedBoardEfforts,
         };
     }
     /**
@@ -496,11 +598,12 @@ class MetricsCalculator {
     /**
      * Calculate scanning steps and selections for a button based on access method
      */
-    calculateScanSteps(board, btn, rowIndex, colIndex) {
+    calculateScanSteps(board, btn, rowIndex, colIndex, overrideConfig) {
+        const config = overrideConfig || board.scanningConfig;
         // Determine scanning type from local scanType or scanningConfig
         let type = board.scanType || treeStructure_1.AACScanType.LINEAR;
-        if (board.scanningConfig?.cellScanningOrder) {
-            const order = board.scanningConfig.cellScanningOrder;
+        if (config?.cellScanningOrder) {
+            const order = config.cellScanningOrder;
             // String matching for CellScanningOrder
             if (order === aac_1.CellScanningOrder.RowColumnScan)
                 type = treeStructure_1.AACScanType.ROW_COLUMN;
@@ -512,63 +615,86 @@ class MetricsCalculator {
                 type = treeStructure_1.AACScanType.LINEAR;
         }
         // Force block scan if enabled in config
-        const isBlockScan = board.scanningConfig?.blockScanEnabled ||
+        const isBlockScan = config?.blockScanEnabled ||
             type === treeStructure_1.AACScanType.BLOCK_ROW_COLUMN ||
             type === treeStructure_1.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) {
-                return { steps: rowIndex + colIndex + 1, selections: 1 };
+                const loop = board.grid.length + (board.grid[0]?.length || 0);
+                return { steps: rowIndex + colIndex + 1, selections: 1, loopSteps: loop };
             }
-            const config = board.scanBlocksConfig?.find((c) => c.id === blockId);
-            const blockOrder = config?.order ?? blockId;
-            // Linear scan within the block
+            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 found = false;
+            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 && (b.scanBlock === blockId || b.scanBlocks?.includes(blockId))) {
-                        if (b === btn) {
-                            found = true;
-                            break;
+                    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;
+                            }
                         }
-                        btnInBlockIndex++;
                     }
                 }
-                if (found)
-                    break;
             }
             // 1 selection for block, 1 for item
-            return { steps: blockOrder + btnInBlockIndex + 1, selections: 2 };
+            return {
+                steps: blockOrder + btnInBlockIndex + 1,
+                selections: 2,
+                loopSteps: blocks.size + itemsInBlock,
+            };
         }
         switch (type) {
             case treeStructure_1.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) {
-                            if (b === btn) {
-                                found = true;
-                                break;
+                            totalVisible++;
+                            if (!found) {
+                                if (b === btn) {
+                                    found = true;
+                                }
+                                else {
+                                    index++;
+                                }
                             }
-                            index++;
                         }
                     }
-                    if (found)
-                        break;
                 }
-                return { steps: index + 1, selections: 1 };
+                return { steps: index + 1, selections: 1, loopSteps: totalVisible };
             }
             case treeStructure_1.AACScanType.ROW_COLUMN:
-                return { steps: rowIndex + 1 + (colIndex + 1), selections: 2 };
+                return {
+                    steps: rowIndex + 1 + (colIndex + 1),
+                    selections: 2,
+                    loopSteps: board.grid.length + (board.grid[0]?.length || 0),
+                };
             case treeStructure_1.AACScanType.COLUMN_ROW:
-                return { steps: colIndex + 1 + (rowIndex + 1), selections: 2 };
+                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 };
+                return {
+                    steps: rowIndex + 1 + (colIndex + 1),
+                    selections: 2,
+                    loopSteps: board.grid.length + (board.grid[0]?.length || 0),
+                };
         }
     }
 }