@willwade/aac-processors 0.0.12 → 0.0.14

package/dist/processors/snapProcessor.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SnapProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
 const treeStructure_1 = require("../core/treeStructure");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
@@ -17,8 +17,11 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
         super(options);
         this.symbolResolver = null;
         this.loadAudio = false;
+        this.pageLayoutPreference = 'scanning'; // Default to scanning for metrics
         this.symbolResolver = symbolResolver;
         this.loadAudio = options.loadAudio !== undefined ? options.loadAudio : true;
+        this.pageLayoutPreference =
+            options.pageLayoutPreference !== undefined ? options.pageLayoutPreference : 'scanning'; // Default to scanning
     }
     extractTexts(filePathOrBuffer) {
         const tree = this.loadIntoTree(filePathOrBuffer);
@@ -79,11 +82,127 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                 });
                 tree.addPage(page);
             });
+            const scanGroupsByPageLayout = new Map();
+            try {
+                const scanGroupRows = db
+                    .prepare('SELECT Id, SerializedGridPositions, PageLayoutId FROM ScanGroup ORDER BY Id')
+                    .all();
+                if (scanGroupRows && scanGroupRows.length > 0) {
+                    // Group by PageLayoutId first
+                    const groupsByLayout = new Map();
+                    scanGroupRows.forEach((sg) => {
+                        if (!groupsByLayout.has(sg.PageLayoutId)) {
+                            groupsByLayout.set(sg.PageLayoutId, []);
+                        }
+                        const layoutGroups = groupsByLayout.get(sg.PageLayoutId);
+                        if (layoutGroups) {
+                            layoutGroups.push(sg);
+                        }
+                    });
+                    // For each PageLayout, assign scan block numbers based on order (1-based index)
+                    groupsByLayout.forEach((groups, layoutId) => {
+                        groups.forEach((sg, index) => {
+                            // Parse SerializedGridPositions JSON
+                            let positions = [];
+                            try {
+                                positions = JSON.parse(sg.SerializedGridPositions);
+                            }
+                            catch (e) {
+                                // Invalid JSON, skip this group
+                                return;
+                            }
+                            const scanGroup = {
+                                id: sg.Id,
+                                scanBlock: index + 1, // Scan block is 1-based index
+                                positions: positions,
+                            };
+                            if (!scanGroupsByPageLayout.has(layoutId)) {
+                                scanGroupsByPageLayout.set(layoutId, []);
+                            }
+                            const layoutGroups = scanGroupsByPageLayout.get(layoutId);
+                            if (layoutGroups) {
+                                layoutGroups.push(scanGroup);
+                            }
+                        });
+                    });
+                }
+            }
+            catch (e) {
+                // No ScanGroups table or error loading, continue without scan blocks
+                console.warn('[SnapProcessor] Failed to load ScanGroups:', e);
+            }
             // Load buttons per page, using UniqueId for page id
             for (const pageRow of pages) {
-                let buttons = [];
                 // Create a map to track page grid layouts
                 const pageGrids = new Map();
+                // Select PageLayout for this page based on preference
+                let selectedPageLayoutId = null;
+                try {
+                    const pageLayouts = db
+                        .prepare('SELECT Id, PageLayoutSetting FROM PageLayout WHERE PageId = ?')
+                        .all(pageRow.Id);
+                    if (pageLayouts && pageLayouts.length > 0) {
+                        // Parse PageLayoutSetting: "columns,rows,hasScanGroups,?"
+                        const layoutsWithInfo = pageLayouts.map((pl) => {
+                            const parts = pl.PageLayoutSetting.split(',');
+                            const cols = parseInt(parts[0], 10) || 0;
+                            const rows = parseInt(parts[1], 10) || 0;
+                            const hasScanning = parts[2] === 'True';
+                            const size = cols * rows;
+                            return { id: pl.Id, cols, rows, size, hasScanning };
+                        });
+                        // Select based on preference
+                        if (typeof this.pageLayoutPreference === 'number') {
+                            // Specific PageLayoutId
+                            selectedPageLayoutId = this.pageLayoutPreference;
+                        }
+                        else if (this.pageLayoutPreference === 'largest') {
+                            // Select layout with largest grid size, prefer layouts with ScanGroups
+                            layoutsWithInfo.sort((a, b) => {
+                                const sizeDiff = b.size - a.size;
+                                if (sizeDiff !== 0)
+                                    return sizeDiff;
+                                // Same size, prefer one with ScanGroups
+                                const aHasScanning = scanGroupsByPageLayout.has(a.id);
+                                const bHasScanning = scanGroupsByPageLayout.has(b.id);
+                                return (bHasScanning ? 1 : 0) - (aHasScanning ? 1 : 0);
+                            });
+                            selectedPageLayoutId = layoutsWithInfo[0].id;
+                        }
+                        else if (this.pageLayoutPreference === 'smallest') {
+                            // Select layout with smallest grid size, prefer layouts with ScanGroups
+                            layoutsWithInfo.sort((a, b) => {
+                                const sizeDiff = a.size - b.size;
+                                if (sizeDiff !== 0)
+                                    return sizeDiff;
+                                // Same size, prefer one with ScanGroups
+                                const aHasScanning = scanGroupsByPageLayout.has(a.id);
+                                const bHasScanning = scanGroupsByPageLayout.has(b.id);
+                                return (bHasScanning ? 1 : 0) - (aHasScanning ? 1 : 0);
+                            });
+                            selectedPageLayoutId = layoutsWithInfo[0].id;
+                        }
+                        else if (this.pageLayoutPreference === 'scanning') {
+                            // Select layout with scanning enabled (check against actual ScanGroups)
+                            const scanningLayouts = layoutsWithInfo.filter((l) => scanGroupsByPageLayout.has(l.id));
+                            if (scanningLayouts.length > 0) {
+                                scanningLayouts.sort((a, b) => b.size - a.size);
+                                selectedPageLayoutId = scanningLayouts[0].id;
+                            }
+                            else {
+                                // Fallback to largest
+                                layoutsWithInfo.sort((a, b) => b.size - a.size);
+                                selectedPageLayoutId = layoutsWithInfo[0].id;
+                            }
+                        }
+                    }
+                }
+                catch (e) {
+                    // Error selecting PageLayout, will load all buttons
+                    console.warn(`[SnapProcessor] Failed to select PageLayout for page ${pageRow.Id}:`, e);
+                }
+                // Load buttons
+                let buttons = [];
                 try {
                     const buttonColumns = getTableColumns('Button');
                     const selectFields = [
@@ -112,15 +231,19 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                             ? 'b.SerializedMessageSoundMetadata'
                             : 'NULL AS SerializedMessageSoundMetadata');
                     }
-                    selectFields.push('ep.GridPosition', 'er.PageId as ButtonPageId');
+                    const placementColumns = getTableColumns('ElementPlacement');
+                    selectFields.push(placementColumns.has('GridPosition') ? 'ep.GridPosition' : 'NULL AS GridPosition', placementColumns.has('PageLayoutId') ? 'ep.PageLayoutId' : 'NULL AS PageLayoutId', 'er.PageId as ButtonPageId');
                     const buttonQuery = `
             SELECT ${selectFields.join(', ')}
             FROM Button b
             INNER JOIN ElementReference er ON b.ElementReferenceId = er.Id
             LEFT JOIN ElementPlacement ep ON ep.ElementReferenceId = er.Id
-            WHERE er.PageId = ?
+            WHERE er.PageId = ? ${selectedPageLayoutId ? 'AND ep.PageLayoutId = ?' : ''}
           `;
-                    buttons = db.prepare(buttonQuery).all(pageRow.Id);
+                    const queryParams = selectedPageLayoutId
+                        ? [pageRow.Id, selectedPageLayoutId]
+                        : [pageRow.Id];
+                    buttons = db.prepare(buttonQuery).all(...queryParams);
                 }
                 catch (err) {
                     const errorMessage = err instanceof Error ? err.message : String(err);
@@ -252,6 +375,34 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                             const [xStr, yStr] = gridPositionStr.split(',');
                             const gridX = parseInt(xStr, 10);
                             const gridY = parseInt(yStr, 10);
+                            // Set button x,y properties (critical for metrics!)
+                            if (!isNaN(gridX) && !isNaN(gridY)) {
+                                button.x = gridX;
+                                button.y = gridY;
+                                // Determine scan block from ScanGroups (TD Snap "Group Scan")
+                                // IMPORTANT: Only match against ScanGroups from the SAME PageLayout
+                                // A button can exist in multiple layouts with different positions
+                                const buttonPageLayoutId = btnRow.PageLayoutId;
+                                if (buttonPageLayoutId && scanGroupsByPageLayout.has(buttonPageLayoutId)) {
+                                    const scanGroups = scanGroupsByPageLayout.get(buttonPageLayoutId);
+                                    if (scanGroups && scanGroups.length > 0) {
+                                        // Find which ScanGroup contains this button's position
+                                        for (const scanGroup of scanGroups) {
+                                            // Skip if positions array is null or undefined
+                                            if (!scanGroup.positions || !Array.isArray(scanGroup.positions)) {
+                                                continue;
+                                            }
+                                            const foundInGroup = scanGroup.positions.some((pos) => pos.Column === gridX && pos.Row === gridY);
+                                            if (foundInGroup) {
+                                                // Use the scan block number from the ScanGroup
+                                                // ScanGroup scanBlock is already 1-based (index + 1)
+                                                button.scanBlock = scanGroup.scanBlock;
+                                                break; // Found the scan block, stop looking
+                                            }
+                                        }
+                                    }
+                                }
+                            }
                             // Place button in grid if within bounds and coordinates are valid
                             if (!isNaN(gridX) &&
                                 !isNaN(gridY) &&

package/dist/processors/touchchatProcessor.d.ts

@@ -1,6 +1,7 @@
 import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
 import { AACTree } from '../core/treeStructure';
 import { ValidationResult } from '../validation/validationTypes';
+import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 declare class TouchChatProcessor extends BaseProcessor {
     private tree;
     private sourceFile;
@@ -30,5 +31,30 @@ declare class TouchChatProcessor extends BaseProcessor {
      * @returns Promise with validation result
      */
     validate(filePath: string): Promise<ValidationResult>;
+    /**
+     * Extract symbol information from a TouchChat file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer: string | Buffer): ButtonForTranslation[];
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated TouchChat file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated TouchChat file
+     */
+    processLLMTranslations(filePathOrBuffer: string | Buffer, llmTranslations: LLMLTranslationResult[], outputPath: string, options?: {
+        allowPartial?: boolean;
+    }): Buffer;
 }
 export { TouchChatProcessor };

package/dist/processors/touchchatProcessor.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TouchChatProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
 const treeStructure_1 = require("../core/treeStructure");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
 const stringCasing_1 = require("../core/stringCasing");
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
@@ -14,6 +14,7 @@ const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const touchChatValidator_1 = require("../validation/touchChatValidator");
+const translationProcessor_1 = require("../utilities/translation/translationProcessor");
 const toNumberOrUndefined = (value) => typeof value === 'number' ? value : undefined;
 const toStringOrUndefined = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
 const toBooleanOrUndefined = (value) => typeof value === 'number' ? value !== 0 : undefined;
@@ -24,6 +25,17 @@ function intToHex(colorInt) {
     // Assuming the color is in ARGB format, we mask out the alpha channel
     return `#${(colorInt & 0x00ffffff).toString(16).padStart(6, '0')}`;
 }
+/**
+ * Map TouchChat visible value to AAC standard visibility
+ * TouchChat: 0 = Hidden, 1 = Visible
+ * Maps to: 'Hidden' | 'Visible' | undefined
+ */
+function mapTouchChatVisibility(visible) {
+    if (visible === null || visible === undefined) {
+        return undefined; // Default to visible
+    }
+    return visible === 0 ? 'Hidden' : 'Visible';
+}
 class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
@@ -132,7 +144,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
         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
@@ -166,7 +178,11 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                         label: cell.label || '',
                         message: cell.message || '',
                         semanticAction: semanticAction,
-                        semantic_id: cell.symbol_link_id || cell.symbolLinkId || undefined, // Extract semantic_id from symbol_link_id
+                        semantic_id: (cell.symbol_link_id || cell.symbolLinkId) || undefined, // Extract semantic_id from symbol_link_id
+                        visibility: mapTouchChatVisibility(cell.visible || undefined),
+                        // Note: TouchChat does not use scan blocks in the file
+                        // Scanning is a runtime feature (linear/row-column patterns)
+                        // scanBlock defaults to 1 (no grouping)
                         style: {
                             backgroundColor: intToHex(style?.body_color),
                             borderColor: intToHex(style?.border_color),
@@ -183,9 +199,9 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                     });
                     buttonBoxes.get(cell.box_id)?.push({
                         button,
-                        location: cell.location,
-                        spanX: cell.span_x,
-                        spanY: cell.span_y,
+                        location: cell.location || 0,
+                        spanX: cell.span_x || 1,
+                        spanY: cell.span_y || 1,
                     });
                 });
                 // Map button boxes to pages
@@ -306,6 +322,10 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                         label: btnRow.label || '',
                         message: btnRow.message || '',
                         semanticAction: semanticAction,
+                        visibility: mapTouchChatVisibility(btnRow.visible),
+                        // Note: TouchChat does not use scan blocks in the file
+                        // Scanning is a runtime feature (linear/row-column patterns)
+                        // scanBlock defaults to 1 (no grouping)
                         style: {
                             backgroundColor: intToHex(style?.body_color),
                             borderColor: intToHex(style?.border_color),
@@ -823,5 +843,85 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
     async validate(filePath) {
         return touchChatValidator_1.TouchChatValidator.validateFile(filePath);
     }
+    /**
+     * Extract symbol information from a TouchChat file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Collect all buttons from all pages
+        const allButtons = [];
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                // Add page context to each button
+                button.pageId = page.id;
+                button.pageName = page.name || page.id;
+                allButtons.push(button);
+            });
+        });
+        // Use shared utility to extract buttons with translation context
+        return (0, translationProcessor_1.extractAllButtonsForTranslation)(allButtons, (button) => ({
+            pageId: button.pageId,
+            pageName: button.pageName,
+        }));
+    }
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to TouchChat .ce file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated TouchChat file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated TouchChat file
+     */
+    processLLMTranslations(filePathOrBuffer, llmTranslations, outputPath, options) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Validate translations using shared utility
+        const buttonIds = Object.values(tree.pages).flatMap((page) => page.buttons.map((b) => b.id));
+        (0, translationProcessor_1.validateTranslationResults)(llmTranslations, buttonIds, options);
+        // Create a map for quick lookup
+        const translationMap = new Map(llmTranslations.map((t) => [t.buttonId, t]));
+        // Apply translations
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                const translation = translationMap.get(button.id);
+                if (!translation)
+                    return;
+                // Apply label translation
+                if (translation.translatedLabel) {
+                    button.label = translation.translatedLabel;
+                }
+                // Apply message translation
+                if (translation.translatedMessage) {
+                    button.message = translation.translatedMessage;
+                    // Update semantic action if symbols provided
+                    if (translation.symbols && translation.symbols.length > 0) {
+                        if (!button.semanticAction) {
+                            button.semanticAction = {
+                                category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                text: translation.translatedMessage,
+                            };
+                        }
+                        button.semanticAction.richText = {
+                            text: translation.translatedMessage,
+                            symbols: translation.symbols,
+                        };
+                    }
+                }
+            });
+        });
+        // Save and return
+        this.saveFromTree(tree, outputPath);
+        return fs_1.default.readFileSync(outputPath);
+    }
 }
 exports.TouchChatProcessor = TouchChatProcessor;

package/dist/types/aac.d.ts

@@ -1,4 +1,54 @@
 import { AACSemanticAction } from '../core/treeStructure';
+/**
+ * Scanning selection methods for switch access
+ * Determines how the scanning advances through items
+ */
+export declare enum ScanningSelectionMethod {
+    /** Automatically advance through items at timed intervals */
+    AutoScan = "AutoScan",
+    /** Automatic scanning with overscan (two-stage scanning) */
+    AutoScanWithOverscan = "AutoScanWithOverscan",
+    /** Hold switch to advance, release to select */
+    HoldToAdvance = "HoldToAdvance",
+    /** Hold to advance with overscan */
+    HoldToAdvanceWithOverscan = "HoldToAdvanceWithOverscan",
+    /** Tap switch to advance, tap again to select */
+    TapToAdvance = "TapToAdvance"
+}
+/**
+ * Cell scanning order patterns
+ * Determines the sequence in which cells are highlighted
+ */
+export declare enum CellScanningOrder {
+    /** Simple linear scan across rows (left-to-right, top-to-bottom) */
+    SimpleScan = "SimpleScan",
+    /** Simple linear scan down columns (top-to-bottom, left-to-right) */
+    SimpleScanColumnsFirst = "SimpleScanColumnsFirst",
+    /** Row-group scanning: highlight rows first, then cells within selected row */
+    RowColumnScan = "RowColumnScan",
+    /** Column-group scanning: highlight columns first, then cells within selected column */
+    ColumnRowScan = "ColumnRowScan"
+}
+/**
+ * Scanning configuration for a page or pageset
+ * Controls how switch scanning operates
+ */
+export interface ScanningConfig {
+    /** Method for advancing through items */
+    selectionMethod?: ScanningSelectionMethod;
+    /** Order in which cells are scanned */
+    cellScanningOrder?: CellScanningOrder;
+    /** Whether block scanning is enabled (group cells by scanBlock number) */
+    blockScanEnabled?: boolean;
+    /** Whether to include the workspace/message bar in scanning */
+    scanWorkspace?: boolean;
+    /** Time in milliseconds to highlight each item */
+    forwardScanSpeed?: number;
+    /** Time in milliseconds to wait before auto-accepting selection */
+    dwellTime?: number;
+    /** How the selection is accepted */
+    acceptScanMethod?: 'Switch' | 'Timeout' | 'Hold';
+}
 export interface AACStyle {
     backgroundColor?: string;
     fontColor?: string;
@@ -35,7 +85,18 @@ export interface AACButton {
     y?: number;
     columnSpan?: number;
     rowSpan?: number;
+    /**
+     * Scan block number (1-8) for block scanning
+     * Buttons with the same scanBlock number are highlighted together
+     * @deprecated Use scanBlock instead (singular, not array)
+     */
     scanBlocks?: number[];
+    /**
+     * Scan block number (1-8) for block scanning
+     * Buttons with the same scanBlock number are highlighted together
+     * Reduces scanning effort by grouping buttons
+     */
+    scanBlock?: number;
     visibility?: 'Visible' | 'Hidden' | 'Disabled' | 'PointerAndTouchOnly' | 'Empty';
     directActivate?: boolean;
     audioDescription?: string;
@@ -58,6 +119,8 @@ export interface AACPage {
     sounds?: any[];
     semantic_ids?: string[];
     clone_ids?: string[];
+    scanningConfig?: ScanningConfig;
+    scanBlocksConfig?: any[];
 }
 export interface AACTree {
     pages: {

package/dist/types/aac.js

@@ -1,2 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CellScanningOrder = exports.ScanningSelectionMethod = void 0;
+/**
+ * Scanning selection methods for switch access
+ * Determines how the scanning advances through items
+ */
+var ScanningSelectionMethod;
+(function (ScanningSelectionMethod) {
+    /** Automatically advance through items at timed intervals */
+    ScanningSelectionMethod["AutoScan"] = "AutoScan";
+    /** Automatic scanning with overscan (two-stage scanning) */
+    ScanningSelectionMethod["AutoScanWithOverscan"] = "AutoScanWithOverscan";
+    /** Hold switch to advance, release to select */
+    ScanningSelectionMethod["HoldToAdvance"] = "HoldToAdvance";
+    /** Hold to advance with overscan */
+    ScanningSelectionMethod["HoldToAdvanceWithOverscan"] = "HoldToAdvanceWithOverscan";
+    /** Tap switch to advance, tap again to select */
+    ScanningSelectionMethod["TapToAdvance"] = "TapToAdvance";
+})(ScanningSelectionMethod || (exports.ScanningSelectionMethod = ScanningSelectionMethod = {}));
+/**
+ * Cell scanning order patterns
+ * Determines the sequence in which cells are highlighted
+ */
+var CellScanningOrder;
+(function (CellScanningOrder) {
+    /** Simple linear scan across rows (left-to-right, top-to-bottom) */
+    CellScanningOrder["SimpleScan"] = "SimpleScan";
+    /** Simple linear scan down columns (top-to-bottom, left-to-right) */
+    CellScanningOrder["SimpleScanColumnsFirst"] = "SimpleScanColumnsFirst";
+    /** Row-group scanning: highlight rows first, then cells within selected row */
+    CellScanningOrder["RowColumnScan"] = "RowColumnScan";
+    /** Column-group scanning: highlight columns first, then cells within selected column */
+    CellScanningOrder["ColumnRowScan"] = "ColumnRowScan";
+})(CellScanningOrder || (exports.CellScanningOrder = CellScanningOrder = {}));

package/dist/{optional → utilities}/analytics/history.d.ts

@@ -1,7 +1,8 @@
 import { dotNetTicksToDate } from '../../utils/dotnetTicks';
 import { Grid3UserPath } from '../../processors/gridset/helpers';
 import { SnapUserInfo } from '../../processors/snap/helpers';
-export type HistorySource = 'Grid' | 'Snap';
+import { AACSemanticCategory, AACSemanticIntent } from '../../core/treeStructure';
+export type HistorySource = 'Grid' | 'Snap' | 'OBL' | string;
 export interface HistoryOccurrence {
     timestamp: Date;
     latitude?: number | null;
@@ -9,12 +10,22 @@ export interface HistoryOccurrence {
     modeling?: boolean;
     accessMethod?: number | null;
     pageId?: string | null;
+    buttonId?: string | null;
+    boardId?: string | null;
+    spoken?: boolean;
+    vocalization?: string;
+    imageUrl?: string;
+    actions?: any[];
+    type?: 'button' | 'action' | 'utterance' | 'note' | 'other';
+    intent?: AACSemanticIntent | string;
+    category?: AACSemanticCategory;
 }
 export interface HistoryPlatformExtras {
     label?: string;
     message?: string;
     buttonId?: string;
     contentXml?: string;
+    [key: string]: any;
 }
 export interface HistoryEntry {
     id: string;

package/dist/{optional → utilities}/analytics/index.d.ts

@@ -13,6 +13,8 @@ export * from './metrics/types';
 export * from './metrics/effort';
 export * from './utils/idGenerator';
 export * from './history';
+export * from './metrics/obl-types';
+export { OblUtil, OblAnonymizer } from './metrics/obl';
 export { MetricsCalculator } from './metrics/core';
 export { VocabularyAnalyzer } from './metrics/vocabulary';
 export { SentenceAnalyzer } from './metrics/sentence';

package/dist/{optional → utilities}/analytics/index.js

@@ -28,7 +28,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReferenceLoader = exports.ComparisonAnalyzer = exports.SentenceAnalyzer = exports.VocabularyAnalyzer = exports.MetricsCalculator = void 0;
+exports.ReferenceLoader = exports.ComparisonAnalyzer = exports.SentenceAnalyzer = exports.VocabularyAnalyzer = exports.MetricsCalculator = exports.OblAnonymizer = exports.OblUtil = void 0;
 exports.getReferenceDataPath = getReferenceDataPath;
 exports.hasReferenceData = hasReferenceData;
 const path_1 = __importDefault(require("path"));
@@ -39,6 +39,11 @@ __exportStar(require("./metrics/effort"), exports);
 __exportStar(require("./utils/idGenerator"), exports);
 // Export history functionality
 __exportStar(require("./history"), exports);
+// Export OBL logging support
+__exportStar(require("./metrics/obl-types"), exports);
+var obl_1 = require("./metrics/obl");
+Object.defineProperty(exports, "OblUtil", { enumerable: true, get: function () { return obl_1.OblUtil; } });
+Object.defineProperty(exports, "OblAnonymizer", { enumerable: true, get: function () { return obl_1.OblAnonymizer; } });
 // Export core metrics calculator
 var core_1 = require("./metrics/core");
 Object.defineProperty(exports, "MetricsCalculator", { enumerable: true, get: function () { return core_1.MetricsCalculator; } });

package/dist/{optional → utilities}/analytics/metrics/comparison.js

@@ -87,13 +87,17 @@ class ComparisonAnalyzer {
             }
         });
         highEffortWords.sort((a, b) => {
-            const diffA = targetWords.get(a).effort - (compareWords.get(a)?.effort || 0);
-            const diffB = targetWords.get(b).effort - (compareWords.get(b)?.effort || 0);
+            const targetBtnA = targetWords.get(a);
+            const targetBtnB = targetWords.get(b);
+            const diffA = (targetBtnA?.effort || 0) - (compareWords.get(a)?.effort || 0);
+            const diffB = (targetBtnB?.effort || 0) - (compareWords.get(b)?.effort || 0);
             return diffB - diffA;
         });
         lowEffortWords.sort((a, b) => {
-            const diffA = (compareWords.get(a)?.effort || 0) - targetWords.get(a).effort;
-            const diffB = (compareWords.get(b)?.effort || 0) - targetWords.get(b).effort;
+            const targetBtnA = targetWords.get(a);
+            const targetBtnB = targetWords.get(b);
+            const diffA = (compareWords.get(a)?.effort || 0) - (targetBtnA?.effort || 0);
+            const diffB = (compareWords.get(b)?.effort || 0) - (targetBtnB?.effort || 0);
             return diffB - diffA;
         });
         // Sentence analysis

package/dist/{optional → utilities}/analytics/metrics/core.d.ts

@@ -21,6 +21,11 @@ export declare class MetricsCalculator {
      * Build reference maps for semantic_id and clone_id frequencies
      */
     private buildReferenceMaps;
+    /**
+     * Count scan items for visual scanning effort
+     * When block scanning is enabled, count unique scan blocks instead of individual buttons
+     */
+    private countScanItems;
     /**
      * Analyze starting from a specific board
      */
@@ -33,4 +38,8 @@ export declare class MetricsCalculator {
      * Calculate grid dimensions from the tree
      */
     private calculateGridDimensions;
+    /**
+     * Calculate scanning steps and selections for a button based on access method
+     */
+    private calculateScanSteps;
 }