@willwade/aac-processors 0.0.12 → 0.0.14

package/dist/processors/gridsetProcessor.js

@@ -10,6 +10,7 @@ const adm_zip_1 = __importDefault(require("adm-zip"));
 const fs_1 = __importDefault(require("fs"));
 const fast_xml_parser_1 = require("fast-xml-parser");
 const resolver_1 = require("./gridset/resolver");
+const translationProcessor_1 = require("../utilities/translation/translationProcessor");
 const password_1 = require("./gridset/password");
 const crypto_1 = __importDefault(require("crypto"));
 const zlib_1 = __importDefault(require("zlib"));
@@ -19,7 +20,8 @@ const pluginTypes_1 = require("./gridset/pluginTypes");
 const commands_1 = require("./gridset/commands");
 const symbols_1 = require("./gridset/symbols");
 const resolver_2 = require("./gridset/resolver");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
+const symbolAlignment_1 = require("./gridset/symbolAlignment");
 class GridsetProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
@@ -490,18 +492,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 +976,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 +989,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
@@ -1038,17 +1086,51 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                 if (tPage)
                     page.name = tPage;
             }
-            // Translate button labels and messages
+            // Translate button labels and messages, preserving symbol positions
             page.buttons.forEach((button) => {
+                // Translate label
                 if (button.label && translations.has(button.label)) {
                     const tLabel = translations.get(button.label);
                     if (tLabel)
                         button.label = tLabel;
                 }
+                // Translate message with symbol preservation
                 if (button.message && translations.has(button.message)) {
-                    const tMsg = translations.get(button.message);
-                    if (tMsg)
-                        button.message = tMsg;
+                    const originalMessage = button.message;
+                    const translatedText = translations.get(originalMessage);
+                    if (translatedText) {
+                        // Extract symbols from the button (from richText or image fields)
+                        const symbols = (0, symbolAlignment_1.extractSymbolsFromButton)(button);
+                        if (symbols && symbols.length > 0) {
+                            // Use symbol-aware translation to preserve symbol positions
+                            const result = (0, symbolAlignment_1.translateWithSymbols)(originalMessage, translatedText, symbols);
+                            // Update the message
+                            button.message = result.text;
+                            // Update the rich text structure if it exists
+                            if (button.semanticAction?.richText) {
+                                button.semanticAction.richText.text = result.text;
+                                button.semanticAction.richText.symbols = result.richTextSymbols;
+                            }
+                            else if (result.richTextSymbols.length > 0) {
+                                // Create rich text structure if it doesn't exist but we have symbols
+                                if (!button.semanticAction) {
+                                    button.semanticAction = {
+                                        category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                        intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                        text: result.text,
+                                    };
+                                }
+                                button.semanticAction.richText = {
+                                    text: result.text,
+                                    symbols: result.richTextSymbols,
+                                };
+                            }
+                        }
+                        else {
+                            // No symbols to preserve, simple translation
+                            button.message = translatedText;
+                        }
+                    }
                 }
             });
         });
@@ -1056,6 +1138,86 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         this.saveFromTree(tree, outputPath);
         return fs_1.default.readFileSync(outputPath);
     }
+    /**
+     * Extract symbol information from a gridset for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to gridset file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Collect all buttons from all pages
+        const allButtons = [];
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                // Add page context to each button
+                button.pageId = page.id;
+                button.pageName = page.name || page.id;
+                allButtons.push(button);
+            });
+        });
+        // Use shared utility to extract buttons with translation context
+        return (0, translationProcessor_1.extractAllButtonsForTranslation)(allButtons, (button) => ({
+            pageId: button.pageId,
+            pageName: button.pageName,
+        }));
+    }
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to gridset file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated gridset
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated gridset
+     */
+    processLLMTranslations(filePathOrBuffer, llmTranslations, outputPath, options) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Validate translations using shared utility
+        const buttonIds = Object.values(tree.pages).flatMap((page) => page.buttons.map((b) => b.id));
+        (0, translationProcessor_1.validateTranslationResults)(llmTranslations, buttonIds, options);
+        // Create a map for quick lookup
+        const translationMap = new Map(llmTranslations.map((t) => [t.buttonId, t]));
+        // Apply translations
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                const translation = translationMap.get(button.id);
+                if (!translation)
+                    return;
+                // Apply label translation
+                if (translation.translatedLabel) {
+                    button.label = translation.translatedLabel;
+                }
+                // Apply message translation
+                if (translation.translatedMessage) {
+                    button.message = translation.translatedMessage;
+                    // Update rich text if symbols provided
+                    if (translation.symbols && translation.symbols.length > 0) {
+                        if (!button.semanticAction) {
+                            button.semanticAction = {
+                                category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                text: translation.translatedMessage,
+                            };
+                        }
+                        button.semanticAction.richText = {
+                            text: translation.translatedMessage,
+                            symbols: translation.symbols,
+                        };
+                    }
+                }
+            });
+        });
+        // Save and return
+        this.saveFromTree(tree, outputPath);
+        return fs_1.default.readFileSync(outputPath);
+    }
     saveFromTree(tree, outputPath) {
         const zip = new adm_zip_1.default();
         if (Object.keys(tree.pages).length === 0) {
@@ -1168,30 +1330,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 +1382,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 +1499,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.d.ts

@@ -1,6 +1,7 @@
 import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
 import { AACTree } from '../core/treeStructure';
 import { ValidationResult } from '../validation/validationTypes';
+import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 declare class ObfProcessor extends BaseProcessor {
     constructor(options?: ProcessorOptions);
     private processBoard;
@@ -26,5 +27,30 @@ declare class ObfProcessor extends BaseProcessor {
      * @returns Promise with validation result
      */
     validate(filePath: string): Promise<ValidationResult>;
+    /**
+     * Extract symbol information from an OBF/OBZ file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer: string | Buffer): ButtonForTranslation[];
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated OBF/OBZ file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated OBF/OBZ file
+     */
+    processLLMTranslations(filePathOrBuffer: string | Buffer, llmTranslations: LLMLTranslationResult[], outputPath: string, options?: {
+        allowPartial?: boolean;
+    }): Buffer;
 }
 export { ObfProcessor };

package/dist/processors/obfProcessor.js

@@ -6,11 +6,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObfProcessor = void 0;
 const baseProcessor_1 = require("../core/baseProcessor");
 const treeStructure_1 = require("../core/treeStructure");
-const idGenerator_1 = require("../optional/analytics/utils/idGenerator");
+const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const fs_1 = __importDefault(require("fs"));
 const obfValidator_1 = require("../validation/obfValidator");
+const translationProcessor_1 = require("../utilities/translation/translationProcessor");
 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 +53,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,
@@ -391,5 +404,85 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
     async validate(filePath) {
         return obfValidator_1.ObfValidator.validateFile(filePath);
     }
+    /**
+     * Extract symbol information from an OBF/OBZ file for LLM-based translation.
+     * Returns a structured format showing which buttons have symbols and their context.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @returns Array of symbol information for LLM processing
+     */
+    extractSymbolsForLLM(filePathOrBuffer) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Collect all buttons from all pages
+        const allButtons = [];
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                // Add page context to each button
+                button.pageId = page.id;
+                button.pageName = page.name || page.id;
+                allButtons.push(button);
+            });
+        });
+        // Use shared utility to extract buttons with translation context
+        return (0, translationProcessor_1.extractAllButtonsForTranslation)(allButtons, (button) => ({
+            pageId: button.pageId,
+            pageName: button.pageName,
+        }));
+    }
+    /**
+     * Apply LLM translations with symbol information.
+     * The LLM should provide translations with symbol attachments in the correct positions.
+     *
+     * This method uses shared translation utilities that work across all AAC formats.
+     *
+     * @param filePathOrBuffer - Path to OBF/OBZ file or buffer
+     * @param llmTranslations - Array of LLM translations with symbol info
+     * @param outputPath - Where to save the translated OBF/OBZ file
+     * @param options - Translation options (e.g., allowPartial for testing)
+     * @returns Buffer of the translated OBF/OBZ file
+     */
+    processLLMTranslations(filePathOrBuffer, llmTranslations, outputPath, options) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Validate translations using shared utility
+        const buttonIds = Object.values(tree.pages).flatMap((page) => page.buttons.map((b) => b.id));
+        (0, translationProcessor_1.validateTranslationResults)(llmTranslations, buttonIds, options);
+        // Create a map for quick lookup
+        const translationMap = new Map(llmTranslations.map((t) => [t.buttonId, t]));
+        // Apply translations
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((button) => {
+                const translation = translationMap.get(button.id);
+                if (!translation)
+                    return;
+                // Apply label translation
+                if (translation.translatedLabel) {
+                    button.label = translation.translatedLabel;
+                }
+                // Apply message translation (vocalization in OBF)
+                if (translation.translatedMessage) {
+                    button.message = translation.translatedMessage;
+                    // Update semantic action if symbols provided
+                    if (translation.symbols && translation.symbols.length > 0) {
+                        if (!button.semanticAction) {
+                            button.semanticAction = {
+                                category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                                intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                                text: translation.translatedMessage,
+                            };
+                        }
+                        button.semanticAction.richText = {
+                            text: translation.translatedMessage,
+                            symbols: translation.symbols,
+                        };
+                    }
+                }
+            });
+        });
+        // Save and return
+        this.saveFromTree(tree, outputPath);
+        return fs_1.default.readFileSync(outputPath);
+    }
 }
 exports.ObfProcessor = ObfProcessor;

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;