@willwade/aac-processors 0.0.15 → 0.0.17

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,28 @@ 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 effort to access a word via prediction
+ *
+ * When prediction is available, the user:
+ * 1. Navigates to the spelling/keyboard page (entryEffort)
+ * 2. Types first 1-3 letters to trigger predictions
+ * 3. Selects from 1-3 predictions (average selections)
+ *
+ * @param entryEffort - Effort to reach the spelling/keyboard page
+ * @param perLetterEffort - Average effort per letter on the keyboard
+ * @param avgSelections - Average number of predictions to check (default 1.5)
+ * @param lettersToType - Letters to type before prediction appears (default 2)
+ * @returns Prediction effort score
+ */
+export declare function predictionEffort(entryEffort?: number, perLetterEffort?: number, avgSelections?: number, lettersToType?: number): number;
 /**
  * Calculate base board effort
  * Combines button size and field size efforts
@@ -142,6 +160,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

@@ -13,6 +13,7 @@ exports.fieldSizeEffort = fieldSizeEffort;
 exports.visualScanEffort = visualScanEffort;
 exports.distanceEffort = distanceEffort;
 exports.spellingEffort = spellingEffort;
+exports.predictionEffort = predictionEffort;
 exports.baseBoardEffort = baseBoardEffort;
 exports.applyReuseDiscount = applyReuseDiscount;
 exports.calculateButtonEffort = calculateButtonEffort;
@@ -44,6 +45,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 +95,34 @@ 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 effort to access a word via prediction
+ *
+ * When prediction is available, the user:
+ * 1. Navigates to the spelling/keyboard page (entryEffort)
+ * 2. Types first 1-3 letters to trigger predictions
+ * 3. Selects from 1-3 predictions (average selections)
+ *
+ * @param entryEffort - Effort to reach the spelling/keyboard page
+ * @param perLetterEffort - Average effort per letter on the keyboard
+ * @param avgSelections - Average number of predictions to check (default 1.5)
+ * @param lettersToType - Letters to type before prediction appears (default 2)
+ * @returns Prediction effort score
+ */
+function predictionEffort(entryEffort = 10, perLetterEffort = 2.5, avgSelections = 1.5, lettersToType = 2) {
+    // Cost to navigate to keyboard + type first few letters + select from predictions
+    const typingCost = lettersToType * perLetterEffort;
+    const selectionCost = avgSelections * exports.EFFORT_CONSTANTS.SCAN_SELECTION_COST;
+    return entryEffort + typingCost + selectionCost;
 }
 /**
  * Calculate base board effort
@@ -204,8 +228,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,52 @@ 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;
+    /**
+     * Whether to use prediction for missing words
+     *
+     * When true (default): Words not in the board are assumed to be accessible
+     * via prediction at reduced effort (spelling_page_base + prediction_selection)
+     *
+     * When false: Words not in the board must be manually spelled at full effort
+     * (10 + word_length * 2.5 per letter)
+     *
+     * Only applies when the board has prediction capability (e.g., SwiftKey)
+     */
+    usePrediction?: boolean;
+    /**
+     * Average number of selections to find a word in prediction
+     *
+     * When prediction is enabled, this estimates how many prediction
+     * slots a user needs to check before finding their target word.
+     * Default is 1.5 (checking 1-2 predictions on average).
+     */
+    predictionSelections?: number;
+}
 /**
  * Comparison result between two board sets
  */
@@ -76,6 +128,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[];
@@ -104,6 +163,8 @@ export interface ComparisonResult extends MetricsResult {
         comp_fringe: number;
         common_fringe: number;
         comp_common_fringe: number;
+        care_score: number;
+        comp_care_score: number;
     };
     sentences: SentenceAnalysis[];
     fringe_words: FringeWord[];

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.d.ts

@@ -35,6 +35,12 @@ export declare class ReferenceLoader {
     loadBaseWords(): {
         [word: string]: boolean;
     };
+    /**
+     * Load common fringe vocabulary
+     * Common words that are NOT in core vocabulary lists
+     * (matching Ruby loader.rb:413-420)
+     */
+    loadCommonFringe(): string[];
     /**
      * Get all reference data at once
      */

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
@@ -85,6 +96,23 @@ class ReferenceLoader {
         const content = fs.readFileSync(filePath, 'utf-8');
         return JSON.parse(content);
     }
+    /**
+     * Load common fringe vocabulary
+     * Common words that are NOT in core vocabulary lists
+     * (matching Ruby loader.rb:413-420)
+     */
+    loadCommonFringe() {
+        const commonWordsData = this.loadCommonWords();
+        const commonWords = new Set(commonWordsData.words.map((w) => w.toLowerCase()));
+        const coreLists = this.loadCoreLists();
+        const coreWords = new Set();
+        coreLists.forEach((list) => {
+            list.words.forEach((word) => coreWords.add(word.toLowerCase()));
+        });
+        // Common fringe = common words - core words
+        const commonFringe = Array.from(commonWords).filter((word) => !coreWords.has(word));
+        return commonFringe;
+    }
     /**
      * Get all reference data at once
      */

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/package.json

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