@willwade/aac-processors 0.0.21 → 0.0.22

package/dist/core/treeStructure.d.ts

@@ -1,5 +1,5 @@
-import { AACButton as IAACButton, AACPage as IAACPage, AACTree as IAACTree, AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata, AACStyle } from '../types/aac';
-export { AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata };
+import { AACButton as IAACButton, AACPage as IAACPage, AACTree as IAACTree, AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata, AACStyle, CellScanningOrder, ScanningSelectionMethod } from '../types/aac';
+export { AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata, CellScanningOrder, ScanningSelectionMethod, };
 export declare enum AACSemanticCategory {
     COMMUNICATION = "communication",// Speech, text output
     NAVIGATION = "navigation",// Page/grid navigation

package/dist/core/treeStructure.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AACTree = exports.AACPage = exports.AACButton = exports.AACScanType = exports.AACSemanticIntent = exports.AACSemanticCategory = void 0;
+exports.AACTree = exports.AACPage = exports.AACButton = exports.AACScanType = exports.AACSemanticIntent = exports.AACSemanticCategory = exports.ScanningSelectionMethod = exports.CellScanningOrder = void 0;
+const aac_1 = require("../types/aac");
+Object.defineProperty(exports, "CellScanningOrder", { enumerable: true, get: function () { return aac_1.CellScanningOrder; } });
+Object.defineProperty(exports, "ScanningSelectionMethod", { enumerable: true, get: function () { return aac_1.ScanningSelectionMethod; } });
 // Semantic action categories for cross-platform compatibility
 var AACSemanticCategory;
 (function (AACSemanticCategory) {

package/dist/processors/gridsetProcessor.js

@@ -1400,6 +1400,8 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                     const homeGridId = gridNameToIdMap.get(startGridName);
                     if (homeGridId) {
                         metadata.defaultHomePageId = homeGridId;
+                        // Also set tree.rootId so BoardViewer knows which page to show first
+                        tree.rootId = homeGridId;
                     }
                 }
                 const keyboardGridName = settingsData?.GridSetSettings?.KeyboardGrid ||

package/dist/processors/obfProcessor.js

@@ -29,6 +29,12 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
     }
     processBoard(boardData, _boardPath) {
         const sourceButtons = boardData.buttons || [];
+        // Calculate page ID first (used to make button IDs unique)
+        const pageId = _boardPath && _boardPath.endsWith('.obf') && !_boardPath.includes('/')
+            ? _boardPath // Zip entry - use filename to match navigation paths
+            : boardData?.id
+                ? String(boardData.id)
+                : _boardPath?.split('/').pop() || '';
         const buttons = sourceButtons.map((btn) => {
             const semanticAction = btn.load_board
                 ? {
@@ -50,7 +56,8 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                     },
                 };
             return new treeStructure_1.AACButton({
-                id: String(btn?.id || ''),
+                // Make button ID unique by combining page ID and button ID
+                id: `${pageId}::${btn?.id || ''}`,
                 label: String(btn?.label || ''),
                 message: String(btn?.vocalization || btn?.label || ''),
                 visibility: mapObfVisibility(btn.hidden),
@@ -65,7 +72,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
         });
         const buttonMap = new Map(buttons.map((btn) => [btn.id, btn]));
         const page = new treeStructure_1.AACPage({
-            id: String(boardData?.id || ''),
+            id: pageId, // Use the page ID we calculated earlier
             name: String(boardData?.name || ''),
             grid: [],
             buttons,
@@ -96,7 +103,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                                 return;
                             if (rowIndex >= rows || colIndex >= cols)
                                 return;
-                            const aacBtn = buttonMap.get(String(cellId));
+                            const aacBtn = buttonMap.get(`${pageId}::${cellId}`);
                             if (aacBtn) {
                                 grid[rowIndex][colIndex] = aacBtn;
                             }
@@ -109,7 +116,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                             const row = Math.floor(btn.box_id / cols);
                             const col = btn.box_id % cols;
                             if (row < rows && col < cols) {
-                                const aacBtn = buttonMap.get(String(btn.id));
+                                const aacBtn = buttonMap.get(`${pageId}::${btn.id}`);
                                 if (aacBtn) {
                                     grid[row][col] = aacBtn;
                                 }

package/dist/processors/snapProcessor.js

@@ -104,7 +104,8 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                     // Set toolbarId if there's a global toolbar
                     if (hasGlobalToolbar) {
                         tree.toolbarId = toolbarId || null;
-                        tree.rootId = toolbarId || defaultHomePageId || null;
+                        // Use defaultHomePageId as root (the content pageset), not the toolbar
+                        tree.rootId = defaultHomePageId || null;
                     }
                     else if (defaultHomePageId) {
                         tree.rootId = defaultHomePageId;
@@ -114,14 +115,7 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
             catch (e) {
                 console.warn('[SnapProcessor] Failed to load PageSetProperties:', e);
             }
-            // If still no root, look for a page titled "Tool Bar" or similar
-            if (!tree.rootId || tree.rootId === defaultHomePageId) {
-                const toolbarPage = pages.find((p) => p.Title === 'Tool Bar' || p.Name === 'Tool Bar');
-                if (toolbarPage) {
-                    tree.rootId = String(toolbarPage.UniqueId || toolbarPage.Id);
-                }
-            }
-            // If still no root, fallback to first page
+            // If still no root, fallback to first page (but don't override a valid defaultHomePageId)
             if (!tree.rootId && pages.length > 0) {
                 tree.rootId = String(pages[0].UniqueId || pages[0].Id);
             }
@@ -144,6 +138,22 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                 });
                 tree.addPage(page);
             });
+            // Try to find toolbar page even if not set in PageSetProperties
+            // Some SNAP files have a toolbar page but don't set ToolBarUniqueId
+            // This must be done AFTER pages are added to the tree
+            if (!tree.toolbarId || tree.toolbarId === '00000000-0000-0000-0000-000000000000') {
+                const toolbarPage = Object.values(tree.pages).find((p) => {
+                    const name = (p.name || '').toLowerCase();
+                    return name === 'tool bar' || name === 'toolbar';
+                });
+                if (toolbarPage) {
+                    tree.toolbarId = toolbarPage.id;
+                    // Update metadata to reflect toolbar detection
+                    if (tree.metadata) {
+                        tree.metadata.hasGlobalToolbar = true;
+                    }
+                }
+            }
             const scanGroupsByPageLayout = new Map();
             try {
                 const scanGroupRows = db

package/dist/processors/touchchatProcessor.js

@@ -159,7 +159,7 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
             });
             // Load button boxes and their cells
             const buttonBoxQuery = `
-        SELECT bbc.*, b.*, bb.id as box_id
+        SELECT bbc.*, b.*, bb.id as box_id, bb.layout_x, bb.layout_y
         FROM button_box_cells bbc
         JOIN buttons b ON b.resource_id = bbc.resource_id
         JOIN button_boxes bb ON bb.id = bbc.button_box_id
@@ -168,8 +168,14 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                 const buttonBoxCells = db.prepare(buttonBoxQuery).all();
                 const buttonBoxes = new Map();
                 buttonBoxCells.forEach((cell) => {
-                    if (!buttonBoxes.has(cell.box_id)) {
-                        buttonBoxes.set(cell.box_id, []);
+                    let boxData = buttonBoxes.get(cell.box_id);
+                    if (!boxData) {
+                        boxData = {
+                            layoutX: cell.layout_x || 10,
+                            layoutY: cell.layout_y || 6,
+                            buttons: [],
+                        };
+                        buttonBoxes.set(cell.box_id, boxData);
                     }
                     const style = buttonStyles.get(cell.button_style_id);
                     // Create semantic action for TouchChat button
@@ -213,7 +219,7 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                             labelOnTop: toBooleanOrUndefined(style?.label_on_top),
                         },
                     });
-                    buttonBoxes.get(cell.box_id)?.push({
+                    boxData.buttons.push({
                         button,
                         location: cell.location || 0,
                         spanX: cell.span_x || 1,
@@ -228,8 +234,8 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                     // Use mapped string ID if available, otherwise use numeric ID as string
                     const pageId = numericToRid.get(instance.page_id) || String(instance.page_id);
                     const page = tree.getPage(pageId);
-                    const buttons = buttonBoxes.get(instance.button_box_id);
-                    if (page && buttons) {
+                    const boxData = buttonBoxes.get(instance.button_box_id);
+                    if (page && boxData) {
                         // Initialize page grid if not exists (assume max 10x10 grid)
                         if (!pageGrids.has(pageId)) {
                             const grid = [];
@@ -243,15 +249,13 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                             return;
                         const boxX = Number(instance.position_x) || 0;
                         const boxY = Number(instance.position_y) || 0;
-                        const boxWidth = Number(instance.size_x) || 1;
+                        const boxWidth = boxData.layoutX; // Use layout_x from button_boxes, not size_x from instance
                         // boxHeight not currently used but kept for future span calculations
-                        // const boxHeight = Number(instance.size_y) || 1;
-                        buttons.forEach(({ button, location, spanX, spanY }) => {
+                        // const boxHeight = boxData.layoutY;
+                        boxData.buttons.forEach(({ button, location, spanX, spanY }) => {
                             const safeLocation = Number(location) || 0;
                             const safeSpanX = Number(spanX) || 1;
                             const safeSpanY = Number(spanY) || 1;
-                            // Add button to page
-                            page.addButton(button);
                             // Calculate button position within the button box
                             // location is a linear index, convert to grid coordinates
                             const buttonX = safeLocation % boxWidth;
@@ -259,6 +263,11 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                             // Calculate absolute position on page
                             const absoluteX = boxX + buttonX;
                             const absoluteY = boxY + buttonY;
+                            // Set button's x and y coordinates
+                            button.x = absoluteX;
+                            button.y = absoluteY;
+                            // Add button to page
+                            page.addButton(button);
                             // Place button in grid (handle span)
                             for (let r = absoluteY; r < absoluteY + safeSpanY && r < 10; r++) {
                                 for (let c = absoluteX; c < absoluteX + safeSpanX && c < 10; c++) {
@@ -412,21 +421,49 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
             catch (e) {
                 // console.log('No navigation actions found:', e);
             }
-            // Try to load root ID from metadata, fallback to first page
+            // Try to load root ID from multiple sources in order of priority
             try {
-                const metadataQuery = "SELECT value FROM tree_metadata WHERE key = 'rootId'";
-                const rootIdRow = db.prepare(metadataQuery).get();
-                if (rootIdRow && tree.getPage(rootIdRow.value)) {
-                    tree.rootId = rootIdRow.value;
+                // First, try to get HOME page from special_pages table (TouchChat specific)
+                const specialPagesQuery = "SELECT page_id FROM special_pages WHERE name = 'HOME'";
+                const homePageRow = db.prepare(specialPagesQuery).get();
+                if (homePageRow) {
+                    // The page_id is the page's id (not resource_id), need to get the RID
+                    const homePageIdQuery = `
+            SELECT p.id, r.rid
+            FROM pages p
+            JOIN resources r ON r.id = p.resource_id
+            WHERE p.id = ?
+            LIMIT 1
+          `;
+                    const homePage = db.prepare(homePageIdQuery).get(homePageRow.page_id);
+                    if (homePage) {
+                        const homePageUUID = homePage.rid || String(homePage.id);
+                        if (tree.getPage(homePageUUID)) {
+                            tree.rootId = homePageUUID;
+                            tree.metadata.defaultHomePageId = homePageUUID;
+                        }
+                    }
+                }
+                // If no HOME page found, try tree_metadata table (general fallback)
+                if (!tree.rootId) {
+                    const metadataQuery = "SELECT value FROM tree_metadata WHERE key = 'rootId'";
+                    const rootIdRow = db.prepare(metadataQuery).get();
+                    if (rootIdRow && tree.getPage(rootIdRow.value)) {
+                        tree.rootId = rootIdRow.value;
+                        tree.metadata.defaultHomePageId = rootIdRow.value;
+                    }
                 }
-                else if (rootPageId) {
+                // Final fallback: first page
+                if (!tree.rootId && rootPageId) {
                     tree.rootId = rootPageId;
+                    tree.metadata.defaultHomePageId = rootPageId;
                 }
             }
             catch (e) {
-                // No metadata table, use first page as root
+                // No metadata table or other error, use first page as root
                 if (rootPageId) {
                     tree.rootId = rootPageId;
+                    tree.metadata.defaultHomePageId = rootPageId;
                 }
             }
             // Set metadata for TouchChat files
@@ -519,7 +556,14 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
         );
 
         CREATE TABLE IF NOT EXISTS button_boxes (
-          id INTEGER PRIMARY KEY
+          id INTEGER PRIMARY KEY,
+          resource_id INTEGER,
+          layout_x INTEGER DEFAULT 10,
+          layout_y INTEGER DEFAULT 6,
+          init_size_x INTEGER DEFAULT 10000,
+          init_size_y INTEGER DEFAULT 10000,
+          scan_pattern_id INTEGER DEFAULT 0,
+          FOREIGN KEY (resource_id) REFERENCES resources (id)
         );
 
         CREATE TABLE IF NOT EXISTS button_box_cells (
@@ -677,8 +721,15 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                     }
                     // Create a button box for this page's buttons
                     const buttonBoxId = buttonBoxIdCounter++;
-                    const insertButtonBox = db.prepare('INSERT INTO button_boxes (id) VALUES (?)');
-                    insertButtonBox.run(buttonBoxId);
+                    // Create a resource for the button box
+                    const buttonBoxResourceId = resourceIdCounter++;
+                    const insertButtonBoxResource = db.prepare('INSERT INTO resources (id, name, type) VALUES (?, ?, ?)');
+                    insertButtonBoxResource.run(buttonBoxResourceId, page.name || 'ButtonBox', 0);
+                    // Insert button box with layout dimensions
+                    const insertButtonBox = db.prepare('INSERT INTO button_boxes (id, resource_id, layout_x, layout_y, init_size_x, init_size_y) VALUES (?, ?, ?, ?, ?, ?)');
+                    insertButtonBox.run(buttonBoxId, buttonBoxResourceId, gridWidth, gridHeight, 10000, // init_size_x in internal units
+                    10000 // init_size_y in internal units
+                    );
                     // Create button box instance with calculated dimensions
                     const insertButtonBoxInstance = db.prepare('INSERT INTO button_box_instances (id, page_id, button_box_id, position_x, position_y, size_x, size_y) VALUES (?, ?, ?, ?, ?, ?, ?)');
                     insertButtonBoxInstance.run(buttonBoxInstanceIdCounter++, numericPageId, buttonBoxId, 0, // Box starts at origin

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

@@ -30,7 +30,7 @@ export declare class MetricsCalculator {
      * Count scan items for visual scanning effort
      * When block scanning is enabled, count unique scan blocks instead of individual buttons
      */
-    private countScanItems;
+    private countScanBlocks;
     /**
      * Analyze starting from a specific board
      */

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

@@ -221,44 +221,26 @@ class MetricsCalculator {
      * Count scan items for visual scanning effort
      * When block scanning is enabled, count unique scan blocks instead of individual buttons
      */
-    countScanItems(board, currentRowIndex, currentColIndex, priorScanBlocks, blockScanEnabled) {
-        if (!blockScanEnabled) {
-            // Linear scanning: count all buttons before current position
-            let count = 0;
-            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 count;
-                    const btn = row[c];
-                    if (btn && (btn.label || btn.id).length > 0) {
-                        count++;
-                    }
-                }
-            }
-            return count;
-        }
+    countScanBlocks(board, currentRowIndex, currentColIndex, priorScanBlocks) {
         // Block scanning: count unique scan blocks before current position
-        const seenBlocks = new Set();
+        // 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 seenBlocks.size;
+                    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)
-                        seenBlocks.add(block);
+                        priorScanBlocks.add(block);
                 }
             }
         }
-        return seenBlocks.size;
+        return priorScanBlocks.size;
     }
     /**
      * Analyze starting from a specific board
@@ -317,216 +299,213 @@ class MetricsCalculator {
             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;
-            // 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;
-                    }
-                    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;
+            // 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 discounts to scanning effort (similar to touch)
+                    // 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];
-                        sEffort = Math.min(sEffort, sEffort * discount);
+                        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.clone_id && boardPcts[btn.clone_id]) {
+                    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];
-                        sEffort = Math.min(sEffort, sEffort * discount);
+                        buttonEffort = Math.min(buttonEffort, buttonEffort * 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 (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 (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 (scanningConfig?.selectionMethod === aac_1.ScanningSelectionMethod.StepScan1Switch) {
+                            // Single switch step scan: every step is a physical selection
+                            currentStepCost = currentSelectionCost;
                         }
-                    }
-                    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);
+                        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;
                         }
-                        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);
+                        // 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];
+                            sEffort = Math.min(sEffort, sEffort * 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);
+                        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);
                         }
-                    }
-                    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);
+                        buttonEffort += sEffort;
                     }
                     else {
-                        buttonEffort += (0, effort_1.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_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,
-                            });
+                        // 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);
+                            }
+                        }
+                        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)(priorItems);
+                        }
+                        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;
+                    // 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);
+                        }
                     }
-                    else if (btn.semantic_id && boardPcts[btn.semantic_id]) {
-                        const discount = Math.min(changeEffort, (changeEffort * 0.5) / boardPcts[btn.semantic_id]);
-                        finalEffort -= discount;
+                    // 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,
+                                });
+                            }
+                        }
                     }
-                    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);
+                    // Track word if it speaks or adds to sentence
+                    const isSpeak = btn.semanticAction?.category === treeStructure_1.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_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());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",