@willwade/aac-processors 0.0.12 → 0.0.13

package/dist/processors/gridsetProcessor.js

@@ -490,18 +490,62 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                         const cellY = Math.max(0, parseInt(String(cell['@_Y'] || '1'), 10) - 1);
                         const colSpan = parseInt(String(cell['@_ColumnSpan'] || '1'), 10);
                         const rowSpan = parseInt(String(cell['@_RowSpan'] || '1'), 10);
+                        // Extract scan block number (1-8) for block scanning support
+                        const scanBlock = parseInt(String(cell['@_ScanBlock'] || '1'), 10);
+                        // Extract visibility from Grid 3's <Visibility> child element
+                        // Grid 3 stores visibility as a child element, not an attribute
+                        // Valid values: Visible, Hidden, Disabled, PointerAndTouchOnly, TouchOnly, PointerOnly
+                        const grid3Visibility = cell.Visibility || cell.visibility;
+                        // Map Grid 3 visibility values to AAC standard values
+                        // Grid 3 can have additional values like TouchOnly, PointerOnly that map to PointerAndTouchOnly
+                        let cellVisibility;
+                        if (grid3Visibility) {
+                            const vis = String(grid3Visibility);
+                            // Direct mapping for standard values
+                            if (vis === 'Visible' ||
+                                vis === 'Hidden' ||
+                                vis === 'Disabled' ||
+                                vis === 'PointerAndTouchOnly') {
+                                cellVisibility = vis;
+                            }
+                            // Map Grid 3 specific values to AAC standard
+                            else if (vis === 'TouchOnly' || vis === 'PointerOnly') {
+                                cellVisibility = 'PointerAndTouchOnly';
+                            }
+                            // Grid 3 may use 'Empty' for cells that exist but have no content
+                            else if (vis === 'Empty') {
+                                cellVisibility = 'Empty';
+                            }
+                            // Unknown visibility - default to Visible
+                            else {
+                                cellVisibility = undefined; // Let it default
+                            }
+                        }
                         // Extract label from CaptionAndImage/Caption
                         const content = cell.Content;
                         const captionAndImage = content.CaptionAndImage || content.captionAndImage;
                         let label = captionAndImage?.Caption || captionAndImage?.caption || '';
+                        // Check if cell has an image/symbol (needed to decide if we should keep it)
+                        const hasImageCandidate = !!(captionAndImage?.Image ||
+                            captionAndImage?.image ||
+                            captionAndImage?.ImageName ||
+                            captionAndImage?.imageName ||
+                            captionAndImage?.Symbol ||
+                            captionAndImage?.symbol);
                         // If no caption, try other sources or create a placeholder
                         if (!label) {
-                            // For cells without captions (like AutoContent cells), create a meaningful label
+                            // For cells without captions, check if they have images/symbols before skipping
                             if (content.ContentType === 'AutoContent') {
                                 label = `AutoContent_${idx}`;
                             }
+                            else if (hasImageCandidate ||
+                                content.ContentType === 'Workspace' ||
+                                content.ContentType === 'LiveCell') {
+                                // Keep cells with images/symbols even if no caption
+                                label = `Cell_${idx}`;
+                            }
                             else {
-                                return; // Skip cells without labels
+                                return; // Skip cells without labels AND without images/symbols
                             }
                         }
                         const message = label; // Use caption as message
@@ -930,6 +974,7 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                             y: cellY,
                             columnSpan: colSpan,
                             rowSpan: rowSpan,
+                            scanBlock: scanBlock, // Add scan block number for block scanning metrics
                             contentType: pluginMetadata.cellType === pluginTypes_1.Grid3CellType.Regular
                                 ? 'Normal'
                                 : pluginMetadata.cellType === pluginTypes_1.Grid3CellType.Workspace
@@ -942,6 +987,7 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                 pluginMetadata.autoContentType,
                             symbolLibrary: symbolLibraryRef?.library || undefined,
                             symbolPath: symbolLibraryRef?.path || undefined,
+                            visibility: cellVisibility,
                             style: {
                                 ...cellStyle,
                                 ...inlineStyle, // Inline styles override referenced styles
@@ -1168,30 +1214,18 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                     GridGuid: page.id,
                     // Calculate grid dimensions based on actual layout
                     ColumnDefinitions: this.calculateColumnDefinitions(page),
-                    RowDefinitions: this.calculateRowDefinitions(page),
+                    RowDefinitions: this.calculateRowDefinitions(page, false), // No automatic workspace row injection
                     AutoContentCommands: '',
                     Cells: page.buttons.length > 0
                         ? {
                             Cell: [
-                                // Add workspace/message bar cell at the top of ALL pages
-                                // Grid3 uses 0-based coordinates; omit X and Y to use defaults (0, 0)
-                                {
-                                    '@_ColumnSpan': 4,
-                                    Content: {
-                                        ContentType: 'Workspace',
-                                        ContentSubType: 'Chat',
-                                        Style: {
-                                            BasedOnStyle: 'Workspace',
-                                        },
-                                    },
-                                },
                                 // Regular button cells
                                 ...this.filterPageButtons(page.buttons).map((button, btnIndex) => {
                                     const buttonStyleId = button.style ? addStyle(button.style) : '';
                                     // Find button position in grid layout
                                     const position = this.findButtonPosition(page, button, btnIndex);
-                                    // Shift all buttons down by 1 row to make room for workspace
-                                    const yOffset = 1;
+                                    // Use position directly from tree
+                                    const yOffset = 0;
                                     // Build CaptionAndImage object
                                     const captionAndImage = {
                                         Caption: button.label || '',
@@ -1232,6 +1266,8 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                         '@_ColumnSpan': position.columnSpan,
                                         '@_RowSpan': position.rowSpan,
                                         Content: {
+                                            ContentType: button.contentType === 'Normal' ? undefined : button.contentType,
+                                            ContentSubType: button.contentSubType,
                                             Commands: this.generateCommandsFromSemanticAction(button, tree),
                                             CaptionAndImage: captionAndImage,
                                         },
@@ -1347,15 +1383,16 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         };
     }
     // Helper method to calculate row definitions based on page layout
-    calculateRowDefinitions(page) {
+    calculateRowDefinitions(page, addWorkspaceOffset = false) {
         let maxRows = 4; // Default minimum
+        const offset = addWorkspaceOffset ? 1 : 0;
         if (page.grid && page.grid.length > 0) {
-            maxRows = Math.max(maxRows, page.grid.length);
+            maxRows = Math.max(maxRows, page.grid.length + offset);
         }
         else {
             // Fallback: estimate from button count
             const estimatedCols = Math.ceil(Math.sqrt(page.buttons.length));
-            maxRows = Math.max(4, Math.ceil(page.buttons.length / estimatedCols));
+            maxRows = Math.max(4, Math.ceil(page.buttons.length / estimatedCols)) + offset;
         }
         return {
             RowDefinition: Array(maxRows).fill({}),

package/dist/processors/obfProcessor.js

@@ -11,6 +11,17 @@ const adm_zip_1 = __importDefault(require("adm-zip"));
 const fs_1 = __importDefault(require("fs"));
 const obfValidator_1 = require("../validation/obfValidator");
 const OBF_FORMAT_VERSION = 'open-board-0.1';
+/**
+ * Map OBF hidden value to AAC standard visibility
+ * OBF: true = hidden, false/undefined = visible
+ * Maps to: 'Hidden' | 'Visible' | undefined
+ */
+function mapObfVisibility(hidden) {
+    if (hidden === undefined) {
+        return undefined; // Default to visible
+    }
+    return hidden ? 'Hidden' : 'Visible';
+}
 class ObfProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
@@ -41,6 +52,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 id: String(btn?.id || ''),
                 label: String(btn?.label || ''),
                 message: String(btn?.vocalization || btn?.label || ''),
+                visibility: mapObfVisibility(btn.hidden),
                 style: {
                     backgroundColor: btn.background_color,
                     borderColor: btn.border_color,

package/dist/processors/snap/helpers.d.ts

@@ -1,4 +1,4 @@
-import { AACTree } from '../../core/treeStructure';
+import { AACTree, AACSemanticCategory, AACSemanticIntent } from '../../core/treeStructure';
 /**
  * Build a map of button IDs to resolved image entries for a specific page.
  * Mirrors the Grid helper for consumers that expect image reference data.
@@ -33,6 +33,10 @@ export interface SnapUsageEntry {
         timestamp: Date;
         modeling?: boolean;
         accessMethod?: number | null;
+        type?: 'button' | 'action' | 'utterance' | 'note' | 'other';
+        buttonId?: string | null;
+        intent?: AACSemanticIntent | string;
+        category?: AACSemanticCategory;
     }>;
     platform?: {
         label?: string;

package/dist/processors/snap/helpers.js

@@ -37,6 +37,7 @@ exports.findSnapUserHistory = findSnapUserHistory;
 exports.isSnapInstalled = isSnapInstalled;
 exports.readSnapUsage = readSnapUsage;
 exports.readSnapUsageForUser = readSnapUsageForUser;
+const treeStructure_1 = require("../../core/treeStructure");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
@@ -271,6 +272,10 @@ function readSnapUsage(pagesetPath) {
             timestamp: (0, dotnetTicks_1.dotNetTicksToDate)(BigInt(row.TickValue ?? 0)),
             modeling: row.Modeling === 1,
             accessMethod: row.AccessMethod ?? null,
+            type: 'button',
+            buttonId: row.ButtonId,
+            intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+            category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
         });
         events.set(buttonId, entry);
     }

package/dist/processors/snapProcessor.d.ts

@@ -4,8 +4,10 @@ import { ValidationResult } from '../validation/validationTypes';
 declare class SnapProcessor extends BaseProcessor {
     private symbolResolver;
     private loadAudio;
+    private pageLayoutPreference;
     constructor(symbolResolver?: unknown | null, options?: ProcessorOptions & {
         loadAudio?: boolean;
+        pageLayoutPreference?: 'largest' | 'smallest' | 'scanning' | number;
     });
     extractTexts(filePathOrBuffer: string | Buffer): string[];
     loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;

package/dist/processors/snapProcessor.js

@@ -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.js

@@ -24,6 +24,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 +143,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 +177,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 +198,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 +321,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),

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/validation/gridsetValidator.js

@@ -243,6 +243,16 @@ class GridsetValidator extends baseValidator_1.BaseValidator {
                 this.warn(`cell ${cellIdx} on page ${pageIdx} should have a label or image`);
             }
         });
+        // Validate scan block number (Grid 3 attribute)
+        await this.add_check(`page[${pageIdx}]_cell[${cellIdx}]_scanblock`, `cell scan block`, async () => {
+            const scanBlock = cell.$.scanBlock || cell.$.ScanBlock;
+            if (scanBlock !== undefined) {
+                const blockNum = parseInt(scanBlock, 10);
+                if (isNaN(blockNum) || blockNum < 1 || blockNum > 8) {
+                    this.err(`cell ${cellIdx} on page ${pageIdx} has invalid scanBlock value: ${scanBlock} (must be 1-8)`, false);
+                }
+            }
+        });
         // Check for color attributes
         const backgroundColor = cell.$.backgroundColor || cell.$.BackgroundColor;
         const _color = cell.$.color || cell.$.Color;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "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",