@willwade/aac-processors 0.0.29 → 0.1.0

package/dist/browser/processors/opmlProcessor.js

@@ -0,0 +1,274 @@
+import { BaseProcessor, } from '../core/baseProcessor';
+import { AACTree, AACPage, AACButton, AACSemanticIntent } from '../core/treeStructure';
+// Removed unused import: FileProcessor
+import { XMLParser, XMLValidator, XMLBuilder } from 'fast-xml-parser';
+import { ValidationFailureError, buildValidationResultFromMessage, } from '../validation/validationTypes';
+import { getBasename, readBinaryFromInput, readTextFromInput, writeBinaryToPath, writeTextToPath, encodeText, } from '../utils/io';
+class OpmlProcessor extends BaseProcessor {
+    constructor(options) {
+        super(options);
+    }
+    processOutline(outline, parentId = null) {
+        if (!outline || typeof outline !== 'object') {
+            return { page: null, childPages: [] };
+        }
+        const text = outline['@_text'] ||
+            (outline._attributes && outline._attributes.text) ||
+            outline.text;
+        if (!text || typeof text !== 'string') {
+            // Skip invalid outlines
+            return { page: null, childPages: [] };
+        }
+        const page = new AACPage({
+            id: text.replace(/[^a-zA-Z0-9]/g, '_'),
+            name: text,
+            grid: [],
+            buttons: [],
+            parentId,
+        });
+        const childPages = [];
+        if (outline.outline) {
+            const children = Array.isArray(outline.outline) ? outline.outline : [outline.outline];
+            children.forEach((child) => {
+                const childText = child['@_text'] || (child._attributes && child._attributes.text) || child.text;
+                if (childText && typeof childText === 'string') {
+                    const button = new AACButton({
+                        id: `nav_${page.id}_${childText}`,
+                        label: childText,
+                        message: '',
+                        targetPageId: childText.replace(/[^a-zA-Z0-9]/g, '_'),
+                    });
+                    page.addButton(button);
+                    const { page: childPage, childPages: grandChildren } = this.processOutline(child, page.id);
+                    if (childPage && childPage.id)
+                        childPages.push(childPage, ...grandChildren);
+                }
+            });
+        }
+        if (!page || !page.id)
+            return { page: null, childPages: [] };
+        return { page, childPages };
+    }
+    async extractTexts(filePathOrBuffer) {
+        await Promise.resolve();
+        const content = readTextFromInput(filePathOrBuffer);
+        const parser = new XMLParser({ ignoreAttributes: false });
+        const data = parser.parse(content);
+        const texts = [];
+        function processNode(node) {
+            // Handle different attribute formats
+            let textValue;
+            if (node && node._attributes && typeof node._attributes.text === 'string') {
+                textValue = node._attributes.text;
+            }
+            else if (node && typeof node['@_text'] === 'string') {
+                textValue = node['@_text'];
+            }
+            else if (node && typeof node.text === 'string') {
+                textValue = node.text;
+            }
+            if (textValue) {
+                texts.push(textValue);
+            }
+            if (node && node.outline) {
+                const children = Array.isArray(node.outline) ? node.outline : [node.outline];
+                children.forEach(processNode);
+            }
+        }
+        const outlines = Array.isArray(data.opml.body.outline)
+            ? data.opml.body.outline
+            : [data.opml.body.outline];
+        outlines.forEach(processNode);
+        return texts;
+    }
+    async loadIntoTree(filePathOrBuffer) {
+        await Promise.resolve();
+        const filename = typeof filePathOrBuffer === 'string' ? getBasename(filePathOrBuffer) : 'upload.opml';
+        const buffer = readBinaryFromInput(filePathOrBuffer);
+        const content = readTextFromInput(buffer);
+        try {
+            if (!content || !content.trim()) {
+                const validationResult = buildValidationResultFromMessage({
+                    filename,
+                    filesize: buffer.byteLength,
+                    format: 'opml',
+                    message: 'Empty OPML content',
+                    type: 'content',
+                    description: 'OPML content is empty',
+                });
+                throw new ValidationFailureError('Empty OPML content', validationResult);
+            }
+            // Validate XML before parsing, fast-xml-parser is permissive by default
+            const validationResult = XMLValidator.validate(content);
+            if (validationResult !== true) {
+                const reason = validationResult?.err?.msg || JSON.stringify(validationResult);
+                const structured = buildValidationResultFromMessage({
+                    filename,
+                    filesize: buffer.byteLength,
+                    format: 'opml',
+                    message: `Invalid OPML XML: ${reason}`,
+                    type: 'xml',
+                    description: 'OPML XML validation',
+                });
+                throw new ValidationFailureError('Invalid OPML XML', structured);
+            }
+            const parser = new XMLParser({ ignoreAttributes: false });
+            const data = parser.parse(content);
+            const tree = new AACTree();
+            tree.metadata.format = 'opml';
+            // Handle case where body.outline might not exist or be in different formats
+            const bodyOutline = data.opml?.body?.outline;
+            if (!bodyOutline) {
+                const structured = buildValidationResultFromMessage({
+                    filename,
+                    filesize: buffer.byteLength,
+                    format: 'opml',
+                    message: 'Missing body.outline in OPML document',
+                    type: 'structure',
+                    description: 'OPML outline root',
+                });
+                throw new ValidationFailureError('Invalid OPML structure', structured);
+            }
+            const outlines = Array.isArray(bodyOutline) ? bodyOutline : [bodyOutline];
+            let firstRootId = null;
+            outlines.forEach((outline) => {
+                const { page, childPages } = this.processOutline(outline);
+                if (page && page.id) {
+                    tree.addPage(page);
+                    if (!firstRootId)
+                        firstRootId = page.id;
+                }
+                childPages.forEach((childPage) => {
+                    if (childPage && childPage.id)
+                        tree.addPage(childPage);
+                });
+            });
+            // Set rootId to first root page, or fallback to first page if any exist
+            if (firstRootId) {
+                tree.rootId = firstRootId;
+            }
+            else if (Object.keys(tree.pages).length > 0) {
+                tree.rootId = Object.keys(tree.pages)[0];
+            }
+            return tree;
+        }
+        catch (err) {
+            if (err instanceof ValidationFailureError) {
+                throw err;
+            }
+            const validationResult = buildValidationResultFromMessage({
+                filename,
+                filesize: buffer.byteLength,
+                format: 'opml',
+                message: err?.message || 'Failed to parse OPML',
+                type: 'parse',
+                description: 'Parse OPML XML',
+            });
+            throw new ValidationFailureError('Failed to load OPML file', validationResult, err);
+        }
+    }
+    async processTexts(filePathOrBuffer, translations, outputPath) {
+        await Promise.resolve();
+        const content = readTextFromInput(filePathOrBuffer);
+        let translatedContent = content;
+        // Apply translations to text attributes in OPML outline elements
+        translations.forEach((translation, originalText) => {
+            if (typeof originalText === 'string' && typeof translation === 'string') {
+                // Replace text attributes in outline elements
+                const textAttrRegex = new RegExp(`text="${originalText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"`, 'g');
+                translatedContent = translatedContent.replace(textAttrRegex, `text="${translation}"`);
+            }
+        });
+        const resultBuffer = encodeText(translatedContent);
+        writeBinaryToPath(outputPath, resultBuffer);
+        return resultBuffer;
+    }
+    async saveFromTree(tree, outputPath) {
+        await Promise.resolve();
+        // Helper to recursively build outline nodes with cycle detection
+        function buildOutline(page, visited = new Set()) {
+            // Prevent infinite recursion by tracking visited pages
+            if (visited.has(page.id)) {
+                return {
+                    '@_text': `${page.name || page.id} (circular reference)`,
+                };
+            }
+            visited.add(page.id);
+            const outline = {
+                '@_text': page.name || page.id,
+            };
+            // Find child pages (by NAVIGATE buttons)
+            const childOutlines = page.buttons
+                .filter((b) => b.semanticAction?.intent === AACSemanticIntent.NAVIGATE_TO &&
+                !!b.targetPageId &&
+                !!tree.pages[b.targetPageId])
+                .map((b) => {
+                const targetId = b.targetPageId;
+                if (!targetId) {
+                    return null;
+                }
+                const targetPage = tree.pages[targetId];
+                if (!targetPage) {
+                    return null;
+                }
+                return buildOutline(targetPage, new Set(visited));
+            })
+                .filter((childOutline) => childOutline !== null);
+            if (childOutlines.length)
+                outline.outline = childOutlines;
+            return outline;
+        }
+        // Find root pages (no parentId or not navigated to by any button)
+        const navigatedIds = new Set();
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((b) => {
+                if (b.semanticAction?.intent === AACSemanticIntent.NAVIGATE_TO && b.targetPageId)
+                    navigatedIds.add(b.targetPageId);
+            });
+        });
+        let rootPages = Object.values(tree.pages).filter((page) => !navigatedIds.has(page.id));
+        // If no rootPages, fall back to tree.rootId
+        const treeRootId = tree.rootId;
+        if ((!rootPages || rootPages.length === 0) && treeRootId && tree.pages[treeRootId]) {
+            rootPages = [tree.pages[treeRootId]];
+        }
+        else if (treeRootId) {
+            rootPages = rootPages.sort((a, b) => a.id === treeRootId ? -1 : b.id === treeRootId ? 1 : 0);
+        }
+        // Build outlines
+        const outlines = rootPages.map((page) => buildOutline(page));
+        // Compose OPML document
+        const opmlObj = {
+            opml: {
+                '@_version': '2.0',
+                head: { title: 'Exported OPML' },
+                body: { outline: outlines },
+            },
+        };
+        // Convert to XML
+        const builder = new XMLBuilder({
+            ignoreAttributes: false,
+            format: true,
+            indentBy: '    ',
+            suppressEmptyNode: false,
+            attributeNamePrefix: '@_',
+        });
+        const xml = '<?xml version="1.0" encoding="UTF-8"?>\n' + builder.build(opmlObj);
+        writeTextToPath(outputPath, xml);
+    }
+    /**
+     * Extract strings with metadata for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    extractStringsWithMetadata(filePath) {
+        return this.extractStringsWithMetadataGeneric(filePath);
+    }
+    /**
+     * Generate translated download for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    generateTranslatedDownload(filePath, translatedStrings, sourceStrings) {
+        return this.generateTranslatedDownloadGeneric(filePath, translatedStrings, sourceStrings);
+    }
+}
+export { OpmlProcessor };

package/dist/browser/types/aac.js

@@ -0,0 +1,38 @@
+// Note: AACSemanticAction is defined in core/treeStructure.ts to avoid circular dependency
+// Import it directly if needed: import { AACSemanticAction } from '../core/treeStructure';
+/**
+ * Scanning selection methods for switch access
+ * Determines how the scanning advances through items
+ */
+export var ScanningSelectionMethod;
+(function (ScanningSelectionMethod) {
+    /** Automatically advance through items at timed intervals (1 Switch) */
+    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 (Automatic) */
+    ScanningSelectionMethod["TapToAdvance"] = "TapToAdvance";
+    /** Tap switch to advance, another switch to select (2 Switch Step Scan) */
+    ScanningSelectionMethod["StepScan2Switch"] = "StepScan2Switch";
+    /** Tap switch 1 to advance, tap switch 1 again to select (1 Switch Step Scan) */
+    ScanningSelectionMethod["StepScan1Switch"] = "StepScan1Switch";
+})(ScanningSelectionMethod || (ScanningSelectionMethod = {}));
+/**
+ * Cell scanning order patterns
+ * Determines the sequence in which cells are highlighted
+ */
+export 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 || (CellScanningOrder = {}));

package/dist/browser/utilities/analytics/utils/idGenerator.js

@@ -0,0 +1,89 @@
+/**
+ * ID Generator Utility for AAC Metrics
+ *
+ * Generates clone_id values based on grid location and button label.
+ * Clone IDs help identify buttons that appear in the same location
+ * across different boards in an AAC system.
+ */
+/**
+ * Normalize a label for use in clone_id generation
+ * Converts to lowercase, removes apostrophes, trims whitespace
+ *
+ * @param label - The button label to normalize
+ * @returns Normalized label string
+ */
+export function normalizeLabelForCloneId(label) {
+    return label
+        .toLowerCase()
+        .replace(/['']/g, '') // Remove apostrophes
+        .replace(/\s+/g, '_') // Replace spaces with underscores
+        .trim();
+}
+/**
+ * Generate a clone_id based on grid location and button label
+ *
+ * Clone ID format: "{rows}x{cols}-{row}.{col}-{label_normalized}"
+ * Example: "6x4-2.3-more" for button "more" at row 2, col 3 in a 6x4 grid
+ *
+ * @param rows - Total number of rows in the grid
+ * @param cols - Total number of columns in the grid
+ * @param row - Zero-based row index of the button
+ * @param col - Zero-based column index of the button
+ * @param label - The button label
+ * @returns A clone_id string
+ */
+export function generateCloneId(rows, cols, row, col, label) {
+    const normalizedLabel = normalizeLabelForCloneId(label);
+    return `${rows}x${cols}-${row}.${col}-${normalizedLabel}`;
+}
+/**
+ * Generate a semantic_id based on button content
+ *
+ * Semantic IDs identify buttons with the same semantic meaning across boards.
+ * This is a fallback for formats that don't have explicit semantic IDs.
+ * Based on hash of message + label
+ *
+ * @param message - The button message/vocalization
+ * @param label - The button label
+ * @returns A semantic_id string (hash-based)
+ */
+export function generateSemanticId(message, label) {
+    const content = `${message || ''}::${label || ''}`;
+    // Simple hash function (djb2 algorithm)
+    let hash = 5381;
+    for (let i = 0; i < content.length; i++) {
+        hash = (hash * 33) ^ content.charCodeAt(i);
+    }
+    // Convert to positive hex string
+    return `semantic_${(hash >>> 0).toString(16)}`;
+}
+/**
+ * Extract all semantic_ids from a page's buttons
+ *
+ * @param buttons - Array of buttons to scan
+ * @returns Array of unique semantic_id strings
+ */
+export function extractSemanticIds(buttons) {
+    const ids = new Set();
+    for (const button of buttons) {
+        if (button.semantic_id) {
+            ids.add(button.semantic_id);
+        }
+    }
+    return Array.from(ids);
+}
+/**
+ * Extract all clone_ids from a page's buttons
+ *
+ * @param buttons - Array of buttons to scan
+ * @returns Array of unique clone_id strings
+ */
+export function extractCloneIds(buttons) {
+    const ids = new Set();
+    for (const button of buttons) {
+        if (button.clone_id) {
+            ids.add(button.clone_id);
+        }
+    }
+    return Array.from(ids);
+}

package/dist/browser/utilities/translation/translationProcessor.js

@@ -0,0 +1,200 @@
+/**
+ * LLM-Based Translation with Symbol Preservation
+ *
+ * This module provides utilities for translating AAC files while preserving
+ * symbol-to-word associations across different formats (gridset, OBF, Snap, etc.).
+ *
+ * The key insight: Different AAC formats have different internal structures,
+ * but they all share common concepts:
+ * - Buttons with labels and messages
+ * - Symbols attached to specific words
+ * - Need to preserve symbol positions during translation
+ *
+ * This module provides a format-agnostic way to:
+ * 1. Extract symbol information for LLM processing
+ * 2. Apply LLM translations with preserved symbols
+ *
+ * Usage:
+ * 1. Processor extracts buttons and calls extractSymbolsForLLM()
+ * 2. LLM translates and returns aligned symbols
+ * 3. Processor calls processLLMTranslations() to apply results
+ */
+/**
+ * Extract symbols from a button for LLM-based translation.
+ *
+ * This is a format-agnostic helper that processors can use to normalize
+ * their button data into a common format for LLM processing.
+ *
+ * @param buttonId - Unique identifier for the button
+ * @param label - Button label text
+ * @param message - Button message/speak text
+ * @param symbols - Array of symbols from the button
+ * @param context - Optional page context
+ * @returns Normalized button data for translation
+ */
+export function normalizeButtonForTranslation(buttonId, label, message, symbols, context, grammar) {
+    return {
+        buttonId,
+        label,
+        message,
+        textToTranslate: message || label, // Translate message if present, otherwise label
+        symbols,
+        grammar,
+        ...context,
+    };
+}
+/**
+ * Extract symbols from various button formats.
+ *
+ * This helper handles different ways symbols might be stored in button data:
+ * - semanticAction.richText.symbols (gridset format)
+ * - symbolLibrary + symbolPath fields
+ * - image field with [library]path format
+ *
+ * @param button - Button object from any AAC format
+ * @returns Array of symbol info, or undefined if no symbols
+ */
+export function extractSymbolsFromButton(button) {
+    const symbols = [];
+    // Method 1: Check for semanticAction.richText.symbols (gridset format)
+    if (button.semanticAction?.richText?.symbols) {
+        const richTextSymbols = button.semanticAction.richText.symbols;
+        if (Array.isArray(richTextSymbols) && richTextSymbols.length > 0) {
+            symbols.push(...richTextSymbols);
+            return symbols;
+        }
+    }
+    // Determine the text to attach symbol to
+    const text = button.label || button.message || '';
+    if (!text) {
+        return undefined;
+    }
+    // Method 2: Check for symbolLibrary + symbolPath fields
+    if (button.symbolLibrary && button.symbolPath) {
+        symbols.push({
+            text,
+            image: `[${button.symbolLibrary}]${button.symbolPath}`,
+            symbolLibrary: button.symbolLibrary,
+            symbolPath: button.symbolPath,
+        });
+        return symbols;
+    }
+    // Method 3: Check if image field contains a symbol reference
+    if (button.image && typeof button.image === 'string' && button.image.startsWith('[')) {
+        symbols.push({
+            text,
+            image: button.image,
+        });
+        return symbols;
+    }
+    // No symbols found
+    return undefined;
+}
+/**
+ * Extract all buttons from a file for LLM translation.
+ *
+ * This is a convenience method that processors can use to extract all
+ * translatable buttons with their symbols in a format-agnostic way.
+ *
+ * @param buttons - Array of button objects from any AAC format
+ * @param contextFn - Optional function to provide page context for each button
+ * @returns Array of normalized button data ready for LLM translation
+ */
+export function extractAllButtonsForTranslation(buttons, contextFn) {
+    const results = [];
+    for (const button of buttons) {
+        if (!button)
+            continue;
+        const buttonId = (button.id || button.buttonId || `button_${results.length}`);
+        const label = (button.label || '');
+        const message = (button.message || '');
+        const symbols = extractSymbolsFromButton(button);
+        // Only include buttons that have text to translate
+        if (!label && !message)
+            continue;
+        const context = contextFn ? contextFn(button) : undefined;
+        const grammar = button.parameters?.grammar || undefined;
+        results.push(normalizeButtonForTranslation(buttonId, label, message, symbols || [], context, grammar));
+    }
+    return results;
+}
+/**
+ * Create a prompt for LLM translation with symbol preservation.
+ *
+ * This generates a structured prompt that instructs the LLM to translate
+ * while preserving symbol-to-word associations.
+ *
+ * @param buttons - Buttons to translate
+ * @param targetLanguage - Target language for translation
+ * @returns Prompt string for LLM
+ */
+export function createTranslationPrompt(buttons, targetLanguage) {
+    const buttonsData = JSON.stringify(buttons, null, 2);
+    return `You are a translation assistant for AAC (Augmentative and Alternative Communication) systems.
+
+Your task is to translate the following buttons to ${targetLanguage} while preserving symbol associations.
+
+Each button has:
+- label: The text shown on the button
+- 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.
+
+Example:
+- Original: "I want apple" with apple symbol on "apple"
+- Spanish: "Yo quiero manzana" with apple symbol on "manzana" (NOT "Yo" or "quiero")
+- French: "Je veux une pomme" with apple symbol on "pomme"
+
+The symbols array should contain the translated word that each symbol should be attached to.
+
+Buttons to translate:
+${buttonsData}
+
+Return ONLY a JSON array with this exact structure:
+[
+  {
+    "buttonId": "...",
+    "translatedLabel": "...",
+    "translatedMessage": "...",
+    "symbols": [
+      {"text": "translated_word", "image": "[library]path"}
+    ]
+  }
+]
+
+Ensure all symbol image references are preserved exactly as provided.`;
+}
+/**
+ * Validate LLM translation results before applying.
+ *
+ * @param translations - LLM translation results
+ * @param originalButtonIds - Expected button IDs (optional, for validation)
+ * @param options - Validation options
+ * @throws Error if validation fails
+ */
+export function validateTranslationResults(translations, originalButtonIds, options) {
+    if (!Array.isArray(translations)) {
+        throw new Error('Translation results must be an array');
+    }
+    const translatedIds = new Set(translations.map((t) => t.buttonId));
+    // Check that all original buttons have translations (unless partial is allowed)
+    if (originalButtonIds && !options?.allowPartial) {
+        for (const id of originalButtonIds) {
+            if (!translatedIds.has(id)) {
+                throw new Error(`Missing translation for button: ${id}`);
+            }
+        }
+    }
+    // Check each translation has required fields
+    for (const trans of translations) {
+        if (!trans.buttonId) {
+            throw new Error('Translation missing buttonId');
+        }
+        if (!trans.translatedMessage && !trans.translatedLabel) {
+            throw new Error(`Translation for ${trans.buttonId} has no translated text`);
+        }
+    }
+}