@willwade/aac-processors 0.0.14 → 0.0.16

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

@@ -29,6 +29,8 @@ export declare const EFFORT_CONSTANTS: {
     readonly REUSED_CLONE_FROM_OTHER_BONUS: 0.005;
     readonly SCAN_STEP_COST: 0.015;
     readonly SCAN_SELECTION_COST: 0.1;
+    readonly DEFAULT_SCAN_ERROR_RATE: 0.1;
+    readonly SCAN_RETRY_PENALTY: 1;
 };
 /**
  * Calculate button size effort based on grid dimensions
@@ -68,12 +70,13 @@ export declare function visualScanEffort(priorButtons: number): number;
 export declare function distanceEffort(x: number, y: number, entryX?: number, entryY?: number): number;
 /**
  * Calculate spelling effort for words not available in the board set
- * Base cost + per-letter cost
  *
  * @param word - The word to spell
+ * @param entryEffort - Effort to reach the spelling/keyboard page
+ * @param perLetterEffort - Average effort per letter on the keyboard
  * @returns Spelling effort score
  */
-export declare function spellingEffort(word: string): number;
+export declare function spellingEffort(word: string, entryEffort?: number, perLetterEffort?: number): number;
 /**
  * Calculate base board effort
  * Combines button size and field size efforts
@@ -142,6 +145,8 @@ export declare function localScanEffort(distance: number): number;
  *
  * @param steps - Number of scan steps to reach target
  * @param selections - Number of switch selections required
+ * @param stepCost - Optional override for scan step cost
+ * @param selectionCost - Optional override for scan selection cost
  * @returns Scanning effort score
  */
-export declare function scanningEffort(steps: number, selections: number): number;
+export declare function scanningEffort(steps: number, selections: number, stepCost?: number, selectionCost?: number): number;

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

@@ -44,6 +44,8 @@ exports.EFFORT_CONSTANTS = {
     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
+    DEFAULT_SCAN_ERROR_RATE: 0.1, // 10% chance of missing a selection
+    SCAN_RETRY_PENALTY: 1.0, // Cost multiplier for a full loop retry
 };
 /**
  * Calculate button size effort based on grid dimensions
@@ -92,13 +94,14 @@ function distanceEffort(x, y, entryX = 1.0, entryY = 1.0) {
 }
 /**
  * Calculate spelling effort for words not available in the board set
- * Base cost + per-letter cost
  *
  * @param word - The word to spell
+ * @param entryEffort - Effort to reach the spelling/keyboard page
+ * @param perLetterEffort - Average effort per letter on the keyboard
  * @returns Spelling effort score
  */
-function spellingEffort(word) {
-    return 10 + word.length * 2.5;
+function spellingEffort(word, entryEffort = 10, perLetterEffort = 2.5) {
+    return entryEffort + word.length * perLetterEffort;
 }
 /**
  * Calculate base board effort
@@ -204,8 +207,10 @@ function localScanEffort(distance) {
  *
  * @param steps - Number of scan steps to reach target
  * @param selections - Number of switch selections required
+ * @param stepCost - Optional override for scan step cost
+ * @param selectionCost - Optional override for scan selection cost
  * @returns Scanning effort score
  */
-function scanningEffort(steps, selections) {
-    return (steps * exports.EFFORT_CONSTANTS.SCAN_STEP_COST + selections * exports.EFFORT_CONSTANTS.SCAN_SELECTION_COST);
+function scanningEffort(steps, selections, stepCost = exports.EFFORT_CONSTANTS.SCAN_STEP_COST, selectionCost = exports.EFFORT_CONSTANTS.SCAN_SELECTION_COST) {
+    return steps * stepCost + selections * selectionCost;
 }

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

@@ -40,10 +40,23 @@ class SentenceAnalyzer {
                 totalEffort += found.effort;
             }
             else {
-                // Word not found - use spelling effort
-                const spellEffort = (0, effort_1.spellingEffort)(word);
-                wordEfforts.push({ word, effort: spellEffort, typed: true });
-                totalEffort += spellEffort;
+                // Word not found - check for dynamic prediction fallback
+                let wordEffort = 0;
+                const isTyped = true;
+                const baseSpell = (0, effort_1.spellingEffort)(word, metrics.spelling_effort_base || 10, metrics.spelling_effort_per_letter || 2.5);
+                if (metrics.has_dynamic_prediction) {
+                    // Predictive fallback: Base + (limited letters) + selection
+                    // We assume on average typing 40% of the word finds it in the dictionary
+                    const predictiveEffort = (metrics.spelling_effort_base || 10) +
+                        word.length * 0.4 * (metrics.spelling_effort_per_letter || 2.5) +
+                        6.0; // Fixed selection cost from prediction bar
+                    wordEffort = Math.min(baseSpell, predictiveEffort);
+                }
+                else {
+                    wordEffort = baseSpell;
+                }
+                wordEfforts.push({ word, effort: wordEffort, typed: isTyped });
+                totalEffort += wordEffort;
                 typing = true;
                 missingWords.push(word);
             }

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

@@ -3,6 +3,7 @@
  *
  * Defines the data structures used for AAC metrics analysis
  */
+import { ScanningConfig } from '../../../types/aac';
 /**
  * Button-level metrics result
  */
@@ -52,6 +53,11 @@ export interface MetricsResult {
     alternates?: {
         [boardId: string]: AlternateBoardMetrics;
     };
+    spelling_effort_base?: number;
+    spelling_effort_per_letter?: number;
+    spelling_page_id?: string;
+    has_dynamic_prediction?: boolean;
+    prediction_page_id?: string;
     obfset?: any;
 }
 /**
@@ -63,6 +69,32 @@ export interface AlternateBoardMetrics {
         [level: number]: ButtonMetrics[];
     };
 }
+/**
+ * Options for metrics calculation
+ */
+export interface MetricsOptions {
+    /**
+     * Override scanning configuration
+     */
+    scanningConfig?: ScanningConfig;
+    /**
+     * Path to core vocabulary lists to use for analysis
+     */
+    coreLists?: string[];
+    /**
+     * Test sentences for sentence-level effort analysis
+     */
+    testSentences?: string[];
+    /**
+     * Custom scanning costs
+     */
+    scanStepCost?: number;
+    scanSelectionCost?: number;
+    /**
+     * Optional explicit ID of the spelling/keyboard page
+     */
+    spellingPageId?: string;
+}
 /**
  * Comparison result between two board sets
  */
@@ -76,6 +108,13 @@ export interface ComparisonResult extends MetricsResult {
         columns: number;
     };
     comp_effort_score: number;
+    comp_spelling_effort_base?: number;
+    comp_spelling_effort_per_letter?: number;
+    comp_spelling_page_id?: string;
+    has_dynamic_prediction?: boolean;
+    prediction_page_id?: string;
+    comp_has_dynamic_prediction?: boolean;
+    comp_prediction_page_id?: string;
     missing_words: string[];
     extra_words: string[];
     overlapping_words: string[];

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

@@ -130,7 +130,7 @@ class VocabularyAnalyzer {
         if (btn) {
             return btn.effort;
         }
-        return (0, effort_1.spellingEffort)(word);
+        return (0, effort_1.spellingEffort)(word, metrics.spelling_effort_base, metrics.spelling_effort_per_letter);
     }
     /**
      * Check if a word is in the board set

package/dist/utilities/analytics/reference/index.js

@@ -75,7 +75,18 @@ class ReferenceLoader {
     loadFringe() {
         const filePath = path.join(this.dataDir, `fringe.${this.locale}.json`);
         const content = fs.readFileSync(filePath, 'utf-8');
-        return JSON.parse(content);
+        const data = JSON.parse(content);
+        // Flatten nested category words if needed
+        if (Array.isArray(data) && data.length > 0 && data[0].categories) {
+            const flattened = [];
+            data.forEach((list) => {
+                list.categories.forEach((cat) => {
+                    flattened.push(...cat.words);
+                });
+            });
+            return flattened;
+        }
+        return data;
     }
     /**
      * Load base words hash map

package/dist/utilities/translation/translationProcessor.d.ts

@@ -39,6 +39,7 @@ export interface ButtonForTranslation {
     message: string;
     textToTranslate: string;
     symbols: SymbolInfo[];
+    grammar?: any;
 }
 /**
  * LLM translation result with symbol mappings
@@ -68,7 +69,7 @@ export interface LLMLTranslationResult {
 export declare function normalizeButtonForTranslation(buttonId: string, label: string, message: string, symbols: SymbolInfo[], context?: {
     pageId?: string;
     pageName?: string;
-}): ButtonForTranslation;
+}, grammar?: any): ButtonForTranslation;
 /**
  * Extract symbols from various button formats.
  *

package/dist/utilities/translation/translationProcessor.js

@@ -39,13 +39,14 @@ exports.validateTranslationResults = validateTranslationResults;
  * @param context - Optional page context
  * @returns Normalized button data for translation
  */
-function normalizeButtonForTranslation(buttonId, label, message, symbols, context) {
+function normalizeButtonForTranslation(buttonId, label, message, symbols, context, grammar) {
     return {
         buttonId,
         label,
         message,
         textToTranslate: message || label, // Translate message if present, otherwise label
         symbols,
+        grammar,
         ...context,
     };
 }
@@ -119,7 +120,8 @@ function extractAllButtonsForTranslation(buttons, contextFn) {
         if (!label && !message)
             continue;
         const context = contextFn ? contextFn(button) : undefined;
-        results.push(normalizeButtonForTranslation(buttonId, label, message, symbols || [], context));
+        const grammar = button.parameters?.grammar || undefined;
+        results.push(normalizeButtonForTranslation(buttonId, label, message, symbols || [], context, grammar));
     }
     return results;
 }
@@ -144,6 +146,7 @@ Each button has:
 - message: The text spoken when the button is activated
 - textToTranslate: The actual text to translate (usually the message)
 - symbols: Visual symbols attached to specific words
+- grammar: Grammatical context (e.g., pos: Part of Speech, person, number)
 
 IMPORTANT: After translation, you MUST reattach symbols to the correct translated words based on MEANING, not position.
 

package/dist/validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validation Namespace
+ *
+ * All validation functionality for AAC processors.
+ * Provides consistent validation across all supported formats.
+ */
+export { ValidationError, ValidationCheck, ValidationResult, ValidationOptions, ValidationRule, } from './validation/validationTypes';
+export { BaseValidator } from './validation/baseValidator';
+export { ObfValidator } from './validation/obfValidator';
+export { GridsetValidator } from './validation/gridsetValidator';
+export { SnapValidator } from './validation/snapValidator';
+export { TouchChatValidator } from './validation/touchChatValidator';
+export { getValidatorForFormat, getValidatorForFile } from './validation/index';

package/dist/validation.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Validation Namespace
+ *
+ * All validation functionality for AAC processors.
+ * Provides consistent validation across all supported formats.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidatorForFile = exports.getValidatorForFormat = exports.TouchChatValidator = exports.SnapValidator = exports.GridsetValidator = exports.ObfValidator = exports.BaseValidator = exports.ValidationError = void 0;
+// Validation types and interfaces
+var validationTypes_1 = require("./validation/validationTypes");
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return validationTypes_1.ValidationError; } });
+// Base validator
+var baseValidator_1 = require("./validation/baseValidator");
+Object.defineProperty(exports, "BaseValidator", { enumerable: true, get: function () { return baseValidator_1.BaseValidator; } });
+// Format-specific validators
+var obfValidator_1 = require("./validation/obfValidator");
+Object.defineProperty(exports, "ObfValidator", { enumerable: true, get: function () { return obfValidator_1.ObfValidator; } });
+var gridsetValidator_1 = require("./validation/gridsetValidator");
+Object.defineProperty(exports, "GridsetValidator", { enumerable: true, get: function () { return gridsetValidator_1.GridsetValidator; } });
+var snapValidator_1 = require("./validation/snapValidator");
+Object.defineProperty(exports, "SnapValidator", { enumerable: true, get: function () { return snapValidator_1.SnapValidator; } });
+var touchChatValidator_1 = require("./validation/touchChatValidator");
+Object.defineProperty(exports, "TouchChatValidator", { enumerable: true, get: function () { return touchChatValidator_1.TouchChatValidator; } });
+// Validator factory functions
+var index_1 = require("./validation/index");
+Object.defineProperty(exports, "getValidatorForFormat", { enumerable: true, get: function () { return index_1.getValidatorForFormat; } });
+Object.defineProperty(exports, "getValidatorForFile", { enumerable: true, get: function () { return index_1.getValidatorForFile; } });

package/package.json

@@ -1,9 +1,63 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./gridset": {
+      "types": "./dist/gridset.d.ts",
+      "default": "./dist/gridset.js"
+    },
+    "./snap": {
+      "types": "./dist/snap.d.ts",
+      "default": "./dist/snap.js"
+    },
+    "./obf": {
+      "types": "./dist/obf.d.ts",
+      "default": "./dist/obf.js"
+    },
+    "./obfset": {
+      "types": "./dist/obfset.d.ts",
+      "default": "./dist/obfset.js"
+    },
+    "./touchchat": {
+      "types": "./dist/touchchat.d.ts",
+      "default": "./dist/touchchat.js"
+    },
+    "./dot": {
+      "types": "./dist/dot.d.ts",
+      "default": "./dist/dot.js"
+    },
+    "./excel": {
+      "types": "./dist/excel.d.ts",
+      "default": "./dist/excel.js"
+    },
+    "./opml": {
+      "types": "./dist/opml.d.ts",
+      "default": "./dist/opml.js"
+    },
+    "./applePanels": {
+      "types": "./dist/applePanels.d.ts",
+      "default": "./dist/applePanels.js"
+    },
+    "./astericsGrid": {
+      "types": "./dist/astericsGrid.d.ts",
+      "default": "./dist/astericsGrid.js"
+    },
+    "./translation": {
+      "types": "./dist/translation.d.ts",
+      "default": "./dist/translation.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.ts",
+      "default": "./dist/validation.js"
+    }
+  },
   "files": [
     "dist/**/*",
     "docs/**/*",
@@ -69,8 +123,8 @@
   },
   "homepage": "https://github.com/willwade/AACProcessors-nodejs#readme",
   "engines": {
-    "node": ">=16.0.0",
-    "npm": ">=8.0.0"
+    "node": ">=20.0.0",
+    "npm": ">=9.0.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
@@ -96,7 +150,7 @@
     "@types/xml2js": "^0.4.14",
     "adm-zip": "^0.5.16",
     "axios": "^1.11.0",
-    "better-sqlite3": "^11.9.1",
+    "better-sqlite3": "^12.5.0",
     "commander": "^13.1.0",
     "exceljs": "^4.4.0",
     "fast-xml-parser": "^5.2.0",

package/dist/utilities/screenshotConverter.d.ts

@@ -1,69 +0,0 @@
-import { AACPage, AACTree } from '../core/treeStructure';
-export interface ScreenshotCell {
-    text: string;
-    row: number;
-    col: number;
-    isCategory?: boolean;
-    isNavigation?: boolean;
-    isEmpty?: boolean;
-    imageUrl?: string;
-}
-export interface ScreenshotGrid {
-    rows: number;
-    cols: number;
-    cells: ScreenshotCell[];
-    categories: string[];
-    metadata?: {
-        timestamp?: string;
-        battery?: string;
-        date?: string;
-    };
-}
-export interface ScreenshotPage {
-    filename: string;
-    grid: ScreenshotGrid;
-    extractedAt: Date;
-    pageName?: string;
-    parentPath?: string;
-    pageTitle?: string;
-}
-export interface PageHierarchy {
-    [pageId: string]: {
-        page: ScreenshotPage;
-        children: string[];
-        parent?: string;
-    };
-}
-export interface ScreenshotConversionOptions {
-    includeEmptyCells: boolean;
-    generateIds: boolean;
-    targetPlatform?: 'grid3' | 'asterics' | 'snap' | 'touchchat';
-    language: string;
-    fallbackCategory: string;
-    filenameDelimiter?: string;
-}
-export declare class ScreenshotConverter {
-    private static defaultOptions;
-    /**
-     * Parse filename to extract page hierarchy and names
-     * Examples:
-     * - "Home.png" → pageName: "Home", parentPath: ""
-     * - "Home->Fragen.png" → pageName: "Fragen", parentPath: "Home"
-     * - "Home->Settings->Profile.jpg" → pageName: "Profile", parentPath: "Home->Settings"
-     */
-    static parseFilename(filename: string, delimiter?: string): {
-        pageName: string;
-        parentPath: string;
-    };
-    /**
-     * Build page hierarchy from an array of screenshots
-     */
-    static buildPageHierarchy(screenshots: ScreenshotPage[]): PageHierarchy;
-    static parseOCRText(ocrResult: string): ScreenshotGrid;
-    private static isCategoryToken;
-    private static isNavigationToken;
-    static convertToAACPage(screenshotPage: ScreenshotPage, pageHierarchy?: PageHierarchy, options?: Partial<ScreenshotConversionOptions>): AACPage;
-    private static createSemanticAction;
-    static convertToAACTree(screenshotPages: ScreenshotPage[], options?: Partial<ScreenshotConversionOptions>): AACTree;
-    private static sanitizePageId;
-}