@willwade/aac-processors 0.0.12 → 0.0.14

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

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetricsCalculator = void 0;
 const treeStructure_1 = require("../../../core/treeStructure");
+const aac_1 = require("../../../types/aac");
 const effort_1 = require("./effort");
 class MetricsCalculator {
     constructor() {
@@ -142,6 +143,49 @@ class MetricsCalculator {
         });
         return { setRefs, setPcts };
     }
+    /**
+     * 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;
+        }
+        // Block scanning: count unique scan blocks before current position
+        const seenBlocks = new Set();
+        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;
+                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);
+                }
+            }
+        }
+        return seenBlocks.size;
+    }
     /**
      * Analyze starting from a specific board
      */
@@ -159,6 +203,8 @@ class MetricsCalculator {
         const levels = {};
         while (toVisit.length > 0) {
             const item = toVisit.shift();
+            if (!item)
+                break;
             const { board, level, entryX, entryY, priorEffort = 0, temporaryHomeId } = item;
             // Skip if already visited at a lower level with equal or better prior effort
             // Skip if already visited at a strictly lower level
@@ -191,8 +237,10 @@ class MetricsCalculator {
             boardEffort = Math.max(0, boardEffort - reuseDiscount);
             // Calculate board link percentages
             const boardPcts = this.calculateBoardLinkPercentages(tree, board);
+            // Get scanning configuration from page (if available)
+            const blockScanEnabled = board.scanningConfig?.blockScanEnabled || false;
             // Process each button
-            let priorButtons = 0;
+            const priorScanBlocks = new Set();
             const btnHeight = 1.0 / rows;
             const btnWidth = 1.0 / cols;
             board.grid.forEach((row, rowIndex) => {
@@ -204,6 +252,9 @@ class MetricsCalculator {
                     }
                     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)
@@ -240,52 +291,76 @@ class MetricsCalculator {
                             boardPcts[`upstream-${btn.clone_id}`];
                         buttonEffort = Math.min(buttonEffort, buttonEffort * discount);
                     }
-                    // Add distance effort
-                    let distance = (0, effort_1.distanceEffort)(x, y, entryX, entryY);
-                    // Apply distance discounts
-                    if (btn.semantic_id) {
-                        if (boardPcts[btn.semantic_id]) {
+                    // Calculate button effort based on access method (Touch vs Scanning)
+                    const isScanning = !!board.scanningConfig || !!board.scanType;
+                    if (isScanning) {
+                        const { steps, selections } = this.calculateScanSteps(board, btn, rowIndex, colIndex);
+                        let sEffort = (0, effort_1.scanningEffort)(steps, selections);
+                        // Apply discounts to scanning effort (similar to touch)
+                        if (btn.semantic_id && boardPcts[btn.semantic_id]) {
                             const discount = effort_1.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.semantic_id];
-                            distance = Math.min(distance, distance * discount);
+                            sEffort = Math.min(sEffort, sEffort * discount);
                         }
-                        else if (boardPcts[`upstream-${btn.semantic_id}`]) {
-                            const discount = effort_1.EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT /
-                                boardPcts[`upstream-${btn.semantic_id}`];
-                            distance = Math.min(distance, distance * discount);
-                        }
-                        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 (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 += sEffort;
                     }
-                    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 {
+                        // Add distance effort (Touch only)
+                        let distance = (0, effort_1.distanceEffort)(x, y, entryX, entryY);
+                        // Apply distance discounts
+                        if (btn.semantic_id) {
+                            if (boardPcts[btn.semantic_id]) {
+                                const discount = effort_1.EFFORT_CONSTANTS.SAME_LOCATION_AS_PRIOR_DISCOUNT / boardPcts[btn.semantic_id];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                            else if (boardPcts[`upstream-${btn.semantic_id}`]) {
+                                const discount = effort_1.EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_PRIOR_DISCOUNT /
+                                    boardPcts[`upstream-${btn.semantic_id}`];
+                                distance = Math.min(distance, distance * discount);
+                            }
+                            else if (level > 0 && setPcts[btn.semantic_id]) {
+                                const discount = effort_1.EFFORT_CONSTANTS.RECOGNIZABLE_SEMANTIC_FROM_OTHER_DISCOUNT /
+                                    setPcts[btn.semantic_id];
+                                distance = Math.min(distance, distance * discount);
+                            }
                         }
-                        else if (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);
+                        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);
+                            }
                         }
-                        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);
                         }
-                    }
-                    buttonEffort += distance;
-                    // Add visual scan or local scan effort
-                    if (distance > effort_1.EFFORT_CONSTANTS.DISTANCE_THRESHOLD_TO_SKIP_VISUAL_SCAN ||
-                        (entryX === 1.0 && entryY === 1.0)) {
-                        buttonEffort += (0, effort_1.visualScanEffort)(priorButtons);
-                    }
-                    else {
-                        buttonEffort += (0, effort_1.localScanEffort)(distance);
                     }
                     // Add cumulative prior effort
                     buttonEffort += priorEffort;
-                    priorButtons += 1;
+                    // 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);
@@ -418,5 +493,83 @@ class MetricsCalculator {
             columns: Math.round(totalCols / count),
         };
     }
+    /**
+     * Calculate scanning steps and selections for a button based on access method
+     */
+    calculateScanSteps(board, btn, rowIndex, colIndex) {
+        // Determine scanning type from local scanType or scanningConfig
+        let type = board.scanType || treeStructure_1.AACScanType.LINEAR;
+        if (board.scanningConfig?.cellScanningOrder) {
+            const order = board.scanningConfig.cellScanningOrder;
+            // String matching for CellScanningOrder
+            if (order === aac_1.CellScanningOrder.RowColumnScan)
+                type = treeStructure_1.AACScanType.ROW_COLUMN;
+            else if (order === aac_1.CellScanningOrder.ColumnRowScan)
+                type = treeStructure_1.AACScanType.COLUMN_ROW;
+            else if (order === aac_1.CellScanningOrder.SimpleScanColumnsFirst)
+                type = treeStructure_1.AACScanType.COLUMN_ROW;
+            else if (order === aac_1.CellScanningOrder.SimpleScan)
+                type = treeStructure_1.AACScanType.LINEAR;
+        }
+        // Force block scan if enabled in config
+        const isBlockScan = board.scanningConfig?.blockScanEnabled ||
+            type === treeStructure_1.AACScanType.BLOCK_ROW_COLUMN ||
+            type === treeStructure_1.AACScanType.BLOCK_COLUMN_ROW;
+        if (isBlockScan) {
+            const blockId = btn.scanBlock || (btn.scanBlocks && btn.scanBlocks.length > 0 ? btn.scanBlocks[0] : null);
+            // If no block assigned, treat as its own block at the end (fallback)
+            if (blockId === null) {
+                return { steps: rowIndex + colIndex + 1, selections: 1 };
+            }
+            const config = board.scanBlocksConfig?.find((c) => c.id === blockId);
+            const blockOrder = config?.order ?? blockId;
+            // Linear scan within the block
+            let btnInBlockIndex = 0;
+            let found = false;
+            for (let r = 0; r < board.grid.length; r++) {
+                for (let c = 0; c < (board.grid[r]?.length || 0); c++) {
+                    const b = board.grid[r][c];
+                    if (b && (b.scanBlock === blockId || b.scanBlocks?.includes(blockId))) {
+                        if (b === btn) {
+                            found = true;
+                            break;
+                        }
+                        btnInBlockIndex++;
+                    }
+                }
+                if (found)
+                    break;
+            }
+            // 1 selection for block, 1 for item
+            return { steps: blockOrder + btnInBlockIndex + 1, selections: 2 };
+        }
+        switch (type) {
+            case treeStructure_1.AACScanType.LINEAR: {
+                let index = 0;
+                let found = false;
+                for (let r = 0; r < board.grid.length; r++) {
+                    for (let c = 0; c < board.grid[r].length; c++) {
+                        const b = board.grid[r][c];
+                        if (b && (b.label || '').length > 0) {
+                            if (b === btn) {
+                                found = true;
+                                break;
+                            }
+                            index++;
+                        }
+                    }
+                    if (found)
+                        break;
+                }
+                return { steps: index + 1, selections: 1 };
+            }
+            case treeStructure_1.AACScanType.ROW_COLUMN:
+                return { steps: rowIndex + 1 + (colIndex + 1), selections: 2 };
+            case treeStructure_1.AACScanType.COLUMN_ROW:
+                return { steps: colIndex + 1 + (rowIndex + 1), selections: 2 };
+            default:
+                return { steps: rowIndex + 1 + (colIndex + 1), selections: 2 };
+        }
+    }
 }
 exports.MetricsCalculator = MetricsCalculator;

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

@@ -27,6 +27,8 @@ export declare const EFFORT_CONSTANTS: {
     readonly RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT: 0.33;
     readonly RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT: 0.33;
     readonly REUSED_CLONE_FROM_OTHER_BONUS: 0.005;
+    readonly SCAN_STEP_COST: 0.015;
+    readonly SCAN_SELECTION_COST: 0.1;
 };
 /**
  * Calculate button size effort based on grid dimensions
@@ -135,3 +137,11 @@ export declare function shouldSkipVisualScan(distance: number): boolean;
  * @returns Local scan effort
  */
 export declare function localScanEffort(distance: number): number;
+/**
+ * Calculate effort for switch scanning
+ *
+ * @param steps - Number of scan steps to reach target
+ * @param selections - Number of switch selections required
+ * @returns Scanning effort score
+ */
+export declare function scanningEffort(steps: number, selections: number): number;

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

@@ -19,6 +19,7 @@ exports.calculateButtonEffort = calculateButtonEffort;
 exports.calculateDistanceWithDiscounts = calculateDistanceWithDiscounts;
 exports.shouldSkipVisualScan = shouldSkipVisualScan;
 exports.localScanEffort = localScanEffort;
+exports.scanningEffort = scanningEffort;
 /**
  * Constants for effort score calculation
  * Values match the Ruby implementation exactly
@@ -41,6 +42,8 @@ exports.EFFORT_CONSTANTS = {
     RECOGNIZABLE_CLONE_FROM_PRIOR_DISCOUNT: 0.33,
     RECOGNIZABLE_CLONE_FROM_OTHER_DISCOUNT: 0.33,
     REUSED_CLONE_FROM_OTHER_BONUS: 0.005,
+    SCAN_STEP_COST: 0.015, // Matches visual scan multiplier
+    SCAN_SELECTION_COST: 0.1, // Cost of a switch selection
 };
 /**
  * Calculate button size effort based on grid dimensions
@@ -196,3 +199,13 @@ function shouldSkipVisualScan(distance) {
 function localScanEffort(distance) {
     return distance * exports.EFFORT_CONSTANTS.SKIPPED_VISUAL_SCAN_DISTANCE_MULTIPLIER;
 }
+/**
+ * Calculate effort for switch scanning
+ *
+ * @param steps - Number of scan steps to reach target
+ * @param selections - Number of switch selections required
+ * @returns Scanning effort score
+ */
+function scanningEffort(steps, selections) {
+    return (steps * exports.EFFORT_CONSTANTS.SCAN_STEP_COST + selections * exports.EFFORT_CONSTANTS.SCAN_SELECTION_COST);
+}

package/dist/utilities/analytics/metrics/obl-types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * .obl (Open Board Logging) File Format Types
+ *
+ * Based on the .obl specification for AAC logging.
+ */
+export interface OblAction {
+    action: string;
+    destination_board_id?: string;
+    text?: string;
+    modification_type?: string;
+    [key: string]: any;
+}
+export interface OblEventBase {
+    id: string;
+    timestamp: string;
+    type: 'button' | 'action' | 'utterance' | 'note' | 'other' | string;
+    locale?: string;
+    geo?: [number, number, number?];
+    location_id?: string;
+    modeling?: boolean;
+    system?: string;
+    window_width?: number;
+    window_height?: number;
+    percent_x?: number;
+    percent_y?: number;
+    [key: string]: any;
+}
+export interface OblButtonEvent extends OblEventBase {
+    type: 'button';
+    label: string;
+    spoken: boolean;
+    button_id?: string;
+    board_id?: string;
+    vocalization?: string;
+    image_url?: string;
+    actions?: OblAction[];
+}
+export interface OblActionEvent extends OblEventBase {
+    type: 'action';
+    action: string;
+    destination_board_id?: string;
+    text?: string;
+    modification_type?: string;
+}
+export interface OblUtteranceEvent extends OblEventBase {
+    type: 'utterance';
+    text: string;
+    buttons?: Array<{
+        id?: string;
+        label?: string;
+        board_id?: string;
+        vocalization?: string;
+        action?: string;
+        text?: string;
+    }>;
+}
+export interface OblNoteEvent extends OblEventBase {
+    type: 'note';
+    text: string;
+    author_name?: string;
+    author_email?: string;
+    author_url?: string;
+}
+export type OblEvent = OblButtonEvent | OblActionEvent | OblUtteranceEvent | OblNoteEvent | OblEventBase;
+export interface OblSession {
+    id: string;
+    type: 'log' | string;
+    started: string;
+    ended: string;
+    device_id?: string;
+    locale?: string;
+    anonymizations?: string[];
+    events: OblEvent[];
+    [key: string]: any;
+}
+export interface OblFile {
+    format: 'open-board-log-0.1' | string;
+    user_id: string;
+    user_name?: string;
+    source?: string;
+    locale?: string;
+    anonymized?: boolean;
+    license?: {
+        type: string;
+        copyright_notice_url?: string;
+        source_url?: string;
+        author_name?: string;
+        author_url?: string;
+        author_email?: string;
+    };
+    sessions: OblSession[];
+    [key: string]: any;
+}

package/dist/utilities/analytics/metrics/obl-types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * .obl (Open Board Logging) File Format Types
+ *
+ * Based on the .obl specification for AAC logging.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,40 @@
+import { OblFile } from './obl-types';
+import { HistoryEntry } from '../history';
+/**
+ * .obl (Open Board Logging) Utility
+ *
+ * Provides parsing and generation support for the .obl format.
+ */
+export declare class OblUtil {
+    /**
+     * Parse an OBL JSON string.
+     * Handles the optional /* notice * / at the start of the file.
+     */
+    static parse(json: string): OblFile;
+    /**
+     * Stringify an OBL file object.
+     * Optionally adds the recommended notice comment.
+     */
+    static stringify(obl: OblFile, includeNotice?: boolean): string;
+    /**
+     * Convert an OBL file to internal HistoryEntry format.
+     */
+    static toHistoryEntries(obl: OblFile): HistoryEntry[];
+    /**
+     * Convert HistoryEntries to an OBL file object.
+     */
+    static fromHistoryEntries(entries: HistoryEntry[], userId: string, source?: string): OblFile;
+}
+/**
+ * .obl Anonymization Utility
+ */
+export declare class OblAnonymizer {
+    /**
+     * Apply anonymization to an OBL file.
+     */
+    static anonymize(obl: OblFile, types: string[]): OblFile;
+    private static applyTimestampShift;
+    private static applyGeolocationMasking;
+    private static applyUrlStripping;
+    private static applyNameMasking;
+}