@willwade/aac-processors 0.0.11 → 0.0.12

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

@@ -0,0 +1,422 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsCalculator = void 0;
+const treeStructure_1 = require("../../../core/treeStructure");
+const effort_1 = require("./effort");
+class MetricsCalculator {
+    constructor() {
+        this.locale = 'en';
+    }
+    /**
+     * Main analysis function - calculates metrics for an AAC tree
+     *
+     * @param tree - The AAC tree to analyze
+     * @returns Complete metrics result
+     */
+    analyze(tree) {
+        // 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 = 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;
+        // Analyze from each starting board
+        startBoards.forEach((startBoard) => {
+            const result = this.analyzeFrom(tree, startBoard, setPcts, startBoard === rootBoard);
+            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;
+            }
+        });
+        // Convert to array and sort
+        const buttons = Array.from(knownButtons.values()).sort((a, b) => a.effort - b.effort);
+        // Calculate grid dimensions
+        const grid = this.calculateGridDimensions(tree);
+        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,
+        };
+    }
+    /**
+     * 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 };
+    }
+    /**
+     * Analyze starting from a specific board
+     */
+    analyzeFrom(tree, brd, setPcts, _isRoot) {
+        const visitedBoardIds = 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();
+            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);
+            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 = (0, effort_1.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_1.EFFORT_CONSTANTS.REUSED_CLONE_FROM_OTHER_BONUS * setPcts[btn.clone_id];
+                    }
+                    else if (btn.semantic_id && setPcts[btn.semantic_id]) {
+                        reuseDiscount +=
+                            effort_1.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);
+            // Process each button
+            let priorButtons = 0;
+            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;
+                    }
+                    const x = btnWidth / 2 + btnWidth * colIndex;
+                    const y = btnHeight / 2 + btnHeight * rowIndex;
+                    // 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);
+                    }
+                    // Add distance effort
+                    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);
+                        }
+                    }
+                    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);
+                        }
+                    }
+                    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)(priorButtons);
+                    }
+                    else {
+                        buttonEffort += (0, effort_1.localScanEffort)(distance);
+                    }
+                    // Add cumulative prior effort
+                    buttonEffort += priorEffort;
+                    priorButtons += 1;
+                    // 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
+        const buttons = Array.from(knownButtons.values());
+        buttons.forEach((btn) => {
+            if (!levels[btn.level]) {
+                levels[btn.level] = [];
+            }
+            levels[btn.level].push(btn);
+        });
+        return {
+            buttons,
+            levels,
+            totalButtons: buttons.length,
+        };
+    }
+    /**
+     * 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 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),
+        };
+    }
+}
+exports.MetricsCalculator = MetricsCalculator;

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

@@ -0,0 +1,137 @@
+/**
+ * Effort Score Calculation Algorithms
+ *
+ * Implements the core effort calculation algorithms from the Ruby aac-metrics tool.
+ * These algorithms calculate how difficult it is to access each button based on
+ * distance, visual scanning, grid complexity, and motor planning support.
+ */
+/**
+ * Constants for effort score calculation
+ * Values match the Ruby implementation exactly
+ */
+export declare const EFFORT_CONSTANTS: {
+    readonly SQRT2: number;
+    readonly BUTTON_SIZE_MULTIPLIER: 0.09;
+    readonly FIELD_SIZE_MULTIPLIER: 0.005;
+    readonly VISUAL_SCAN_MULTIPLIER: 0.015;
+    readonly BOARD_CHANGE_PROCESSING_EFFORT: 1;
+    readonly BOARD_HOME_EFFORT: 1;
+    readonly COMBINED_WORDS_REMEMBERING_EFFORT: 1;
+    readonly DISTANCE_MULTIPLIER: 0.4;
+    readonly DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN: 0.1;
+    readonly SKIPPED_VISUAL_SCAN_DISTANCE_MULTIPLIER: 0.5;
+    readonly SAME_LOCATION_AS_PRIOR_DISCOUNT: 0.1;
+    readonly RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT: 0.5;
+    readonly RECOGNIZABLE_SEMANTIC_FROM_OTHER_DISCOUNT: 0.5;
+    readonly REUSED_SEMANTIC_FROM_OTHER_BONUS: 0.0025;
+    readonly RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT: 0.33;
+    readonly RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT: 0.33;
+    readonly REUSED_CLONE_FROM_OTHER_BONUS: 0.005;
+};
+/**
+ * Calculate button size effort based on grid dimensions
+ * Larger grids require more visual scanning and discrimination
+ *
+ * @param rows - Number of rows in the grid
+ * @param cols - Number of columns in the grid
+ * @returns Button size effort score
+ */
+export declare function buttonSizeEffort(rows: number, cols: number): number;
+/**
+ * Calculate field size effort based on number of visible buttons
+ * More buttons = more visual clutter = higher effort
+ *
+ * @param buttonCount - Number of visible buttons on the board
+ * @returns Field size effort score
+ */
+export declare function fieldSizeEffort(buttonCount: number): number;
+/**
+ * Calculate visual scanning effort
+ * Effort increases with each button that must be scanned before reaching target
+ *
+ * @param priorButtons - Number of buttons visually scanned before target
+ * @returns Visual scan effort score
+ */
+export declare function visualScanEffort(priorButtons: number): number;
+/**
+ * Calculate distance effort from entry point to button center
+ * Uses Euclidean distance normalized by sqrt(2)
+ *
+ * @param x - Button center X coordinate (0-1 normalized)
+ * @param y - Button center Y coordinate (0-1 normalized)
+ * @param entryX - Entry point X coordinate (0-1 normalized, default 1.0 = bottom-right)
+ * @param entryY - Entry point Y coordinate (0-1 normalized, default 1.0 = bottom-right)
+ * @returns Distance effort score
+ */
+export declare function distanceEffort(x: number, y: number, entryX?: number, entryY?: number): number;
+/**
+ * Calculate spelling effort for words not available in the board set
+ * Base cost + per-letter cost
+ *
+ * @param word - The word to spell
+ * @returns Spelling effort score
+ */
+export declare function spellingEffort(word: string): number;
+/**
+ * Calculate base board effort
+ * Combines button size and field size efforts
+ *
+ * @param rows - Number of rows in the grid
+ * @param cols - Number of columns in the grid
+ * @param buttonCount - Number of visible buttons
+ * @returns Base board effort score
+ */
+export declare function baseBoardEffort(rows: number, cols: number, buttonCount: number): number;
+/**
+ * Apply reuse discount based on semantic_id/clone_id frequency
+ *
+ * @param boardEffort - Current board effort
+ * @param reuseDiscount - Calculated reuse discount
+ * @returns Adjusted board effort
+ */
+export declare function applyReuseDiscount(boardEffort: number, reuseDiscount: number): number;
+/**
+ * Calculate button-level effort with motor planning discounts
+ *
+ * @param baseEffort - Base board effort
+ * @param boardPcts - Percentage of links matching semantic_id/clone_id
+ * @param button - Button data
+ * @returns Adjusted button effort
+ */
+export declare function calculateButtonEffort(baseEffort: number, boardPcts: {
+    [id: string]: number;
+}, button: {
+    semantic_id?: string;
+    clone_id?: string;
+}): number;
+/**
+ * Calculate distance with motor planning discounts
+ *
+ * @param distance - Raw distance effort
+ * @param boardPcts - Percentage of links matching semantic_id/clone_id
+ * @param button - Button data
+ * @param setPcts - Percentage of boards containing semantic_id/clone_id
+ * @returns Adjusted distance effort
+ */
+export declare function calculateDistanceWithDiscounts(distance: number, boardPcts: {
+    [id: string]: number;
+}, button: {
+    semantic_id?: string;
+    clone_id?: string;
+}, setPcts: {
+    [id: string]: number;
+}): number;
+/**
+ * Check if visual scan should be skipped (button close to previous)
+ *
+ * @param distance - Distance from previous button
+ * @returns True if close enough to skip full visual scan
+ */
+export declare function shouldSkipVisualScan(distance: number): boolean;
+/**
+ * Calculate local scan effort when buttons are close
+ *
+ * @param distance - Distance between buttons
+ * @returns Local scan effort
+ */
+export declare function localScanEffort(distance: number): number;