@willwade/aac-processors 0.1.5 → 0.1.7

package/dist/browser/processors/snapProcessor.js

@@ -0,0 +1,1031 @@
+import { BaseProcessor, } from '../core/baseProcessor';
+import { AACTree, AACPage, AACButton, AACSemanticCategory, AACSemanticIntent, } from '../core/treeStructure';
+import { generateCloneId } from '../utilities/analytics/utils/idGenerator';
+import { SnapValidator } from '../validation/snapValidator';
+import { getFs, getNodeRequire, getPath, isNodeRuntime } from '../utils/io';
+import { openSqliteDatabase, requireBetterSqlite3 } from '../utils/sqlite';
+/**
+ * Map Snap Visible value to AAC standard visibility
+ * Snap: 0 = hidden, 1 (or non-zero) = visible
+ * Maps to: 'Hidden' | 'Visible' | undefined
+ */
+function mapSnapVisibility(visible) {
+    if (visible === null || visible === undefined) {
+        return undefined; // Default to visible
+    }
+    return visible === 0 ? 'Hidden' : 'Visible';
+}
+class SnapProcessor extends BaseProcessor {
+    constructor(symbolResolver = null, options = {}) {
+        super(options);
+        this.symbolResolver = null;
+        this.loadAudio = false;
+        this.pageLayoutPreference = 'scanning'; // Default to scanning for metrics
+        this.symbolResolver = symbolResolver;
+        this.loadAudio = options.loadAudio !== undefined ? options.loadAudio : true;
+        this.pageLayoutPreference =
+            options.pageLayoutPreference !== undefined ? options.pageLayoutPreference : 'scanning'; // Default to scanning
+    }
+    async extractTexts(filePathOrBuffer) {
+        const tree = await this.loadIntoTree(filePathOrBuffer);
+        const texts = [];
+        for (const pageId in tree.pages) {
+            const page = tree.pages[pageId];
+            // Include page names
+            if (page.name)
+                texts.push(page.name);
+            // Include button texts
+            page.buttons.forEach((btn) => {
+                if (btn.label)
+                    texts.push(btn.label);
+                if (btn.message && btn.message !== btn.label)
+                    texts.push(btn.message);
+            });
+        }
+        return texts;
+    }
+    async loadIntoTree(filePathOrBuffer) {
+        await Promise.resolve();
+        const tree = new AACTree();
+        let dbResult = null;
+        try {
+            dbResult = await openSqliteDatabase(filePathOrBuffer, { readonly: true });
+            const db = dbResult.db;
+            const getTableColumns = (tableName) => {
+                try {
+                    const rows = db.prepare(`PRAGMA table_info(${tableName})`).all();
+                    return new Set(rows.map((row) => row.name));
+                }
+                catch {
+                    return new Set();
+                }
+            };
+            // Load pages first, using UniqueId as canonical id
+            const pages = db.prepare('SELECT * FROM Page').all();
+            // Load PageSetProperties to find default Keyboard and Home pages
+            let defaultKeyboardPageId;
+            let defaultHomePageId;
+            let dashboardPageId;
+            let toolbarId;
+            try {
+                const properties = db.prepare('SELECT * FROM PageSetProperties').get();
+                if (properties) {
+                    defaultKeyboardPageId = properties.DefaultKeyboardPageUniqueId;
+                    defaultHomePageId = properties.DefaultHomePageUniqueId;
+                    dashboardPageId = properties.DashboardUniqueId;
+                    toolbarId = properties.ToolBarUniqueId;
+                    const hasGlobalToolbar = toolbarId && toolbarId !== '00000000-0000-0000-0000-000000000000';
+                    // Store metadata in tree
+                    const metadata = {
+                        format: 'snap',
+                        name: properties.Name || properties.PageSetName || undefined,
+                        description: properties.Description || undefined,
+                        author: properties.Author || undefined,
+                        locale: properties.Locale || undefined,
+                        languages: properties.Locale ? [properties.Locale] : undefined,
+                        defaultKeyboardPageId: defaultKeyboardPageId || undefined,
+                        defaultHomePageId: defaultHomePageId || undefined,
+                        dashboardId: dashboardPageId || undefined,
+                        hasGlobalToolbar: !!hasGlobalToolbar,
+                    };
+                    tree.metadata = metadata;
+                    // Set toolbarId if there's a global toolbar
+                    if (hasGlobalToolbar) {
+                        tree.toolbarId = toolbarId || null;
+                        // Use defaultHomePageId as root (the content pageset), not the toolbar
+                        tree.rootId = defaultHomePageId || null;
+                    }
+                    else if (defaultHomePageId) {
+                        tree.rootId = defaultHomePageId;
+                    }
+                }
+            }
+            catch (e) {
+                console.warn('[SnapProcessor] Failed to load PageSetProperties:', e);
+            }
+            // If still no root, fallback to first page (but don't override a valid defaultHomePageId)
+            if (!tree.rootId && pages.length > 0) {
+                tree.rootId = String(pages[0].UniqueId || pages[0].Id);
+            }
+            // Map from numeric Id -> UniqueId for later lookup
+            const idToUniqueId = {};
+            pages.forEach((pageRow) => {
+                const uniqueId = String(pageRow.UniqueId || pageRow.Id);
+                idToUniqueId[String(pageRow.Id)] = uniqueId;
+                const page = new AACPage({
+                    id: uniqueId,
+                    name: pageRow.Title || pageRow.Name,
+                    grid: [],
+                    buttons: [],
+                    parentId: null, // ParentId will be set via navigation buttons below
+                    style: {
+                        backgroundColor: pageRow.BackgroundColor
+                            ? `#${pageRow.BackgroundColor.toString(16)}`
+                            : undefined,
+                    },
+                });
+                tree.addPage(page);
+            });
+            // Try to find toolbar page even if not set in PageSetProperties
+            // Some SNAP files have a toolbar page but don't set ToolBarUniqueId
+            // This must be done AFTER pages are added to the tree
+            if (!tree.toolbarId || tree.toolbarId === '00000000-0000-0000-0000-000000000000') {
+                const toolbarPage = Object.values(tree.pages).find((p) => {
+                    const name = (p.name || '').toLowerCase();
+                    return name === 'tool bar' || name === 'toolbar';
+                });
+                if (toolbarPage) {
+                    tree.toolbarId = toolbarPage.id;
+                    // Update metadata to reflect toolbar detection
+                    if (tree.metadata) {
+                        tree.metadata.hasGlobalToolbar = true;
+                    }
+                }
+            }
+            const scanGroupsByPageLayout = new Map();
+            try {
+                const scanGroupRows = db
+                    .prepare('SELECT Id, SerializedGridPositions, PageLayoutId FROM ScanGroup ORDER BY Id')
+                    .all();
+                if (scanGroupRows && scanGroupRows.length > 0) {
+                    // Group by PageLayoutId first
+                    const groupsByLayout = new Map();
+                    scanGroupRows.forEach((sg) => {
+                        if (!groupsByLayout.has(sg.PageLayoutId)) {
+                            groupsByLayout.set(sg.PageLayoutId, []);
+                        }
+                        const layoutGroups = groupsByLayout.get(sg.PageLayoutId);
+                        if (layoutGroups) {
+                            layoutGroups.push(sg);
+                        }
+                    });
+                    // For each PageLayout, assign scan block numbers based on order (1-based index)
+                    groupsByLayout.forEach((groups, layoutId) => {
+                        groups.forEach((sg, index) => {
+                            // Parse SerializedGridPositions JSON
+                            let positions = [];
+                            try {
+                                positions = JSON.parse(sg.SerializedGridPositions);
+                            }
+                            catch (e) {
+                                // Invalid JSON, skip this group
+                                return;
+                            }
+                            const scanGroup = {
+                                id: sg.Id,
+                                scanBlock: index + 1, // Scan block is 1-based index
+                                positions: positions,
+                            };
+                            if (!scanGroupsByPageLayout.has(layoutId)) {
+                                scanGroupsByPageLayout.set(layoutId, []);
+                            }
+                            const layoutGroups = scanGroupsByPageLayout.get(layoutId);
+                            if (layoutGroups) {
+                                layoutGroups.push(scanGroup);
+                            }
+                        });
+                    });
+                }
+            }
+            catch (e) {
+                // No ScanGroups table or error loading, continue without scan blocks
+                console.warn('[SnapProcessor] Failed to load ScanGroups:', e);
+            }
+            // Load buttons per page, using UniqueId for page id
+            for (const pageRow of pages) {
+                // Create a map to track page grid layouts
+                const pageGrids = new Map();
+                // Select PageLayout for this page based on preference
+                let selectedPageLayoutId = null;
+                try {
+                    const pageLayouts = db
+                        .prepare('SELECT Id, PageLayoutSetting FROM PageLayout WHERE PageId = ?')
+                        .all(pageRow.Id);
+                    if (pageLayouts && pageLayouts.length > 0) {
+                        // Parse PageLayoutSetting: "columns,rows,hasScanGroups,?"
+                        const layoutsWithInfo = pageLayouts.map((pl) => {
+                            const parts = pl.PageLayoutSetting.split(',');
+                            const cols = parseInt(parts[0], 10) || 0;
+                            const rows = parseInt(parts[1], 10) || 0;
+                            const hasScanning = parts[2] === 'True';
+                            const size = cols * rows;
+                            return { id: pl.Id, cols, rows, size, hasScanning };
+                        });
+                        // Select based on preference
+                        if (typeof this.pageLayoutPreference === 'number') {
+                            // Specific PageLayoutId
+                            selectedPageLayoutId = this.pageLayoutPreference;
+                        }
+                        else if (this.pageLayoutPreference === 'largest') {
+                            // Select layout with largest grid size, prefer layouts with ScanGroups
+                            layoutsWithInfo.sort((a, b) => {
+                                const sizeDiff = b.size - a.size;
+                                if (sizeDiff !== 0)
+                                    return sizeDiff;
+                                // Same size, prefer one with ScanGroups
+                                const aHasScanning = scanGroupsByPageLayout.has(a.id);
+                                const bHasScanning = scanGroupsByPageLayout.has(b.id);
+                                return (bHasScanning ? 1 : 0) - (aHasScanning ? 1 : 0);
+                            });
+                            selectedPageLayoutId = layoutsWithInfo[0].id;
+                        }
+                        else if (this.pageLayoutPreference === 'smallest') {
+                            // Select layout with smallest grid size, prefer layouts with ScanGroups
+                            layoutsWithInfo.sort((a, b) => {
+                                const sizeDiff = a.size - b.size;
+                                if (sizeDiff !== 0)
+                                    return sizeDiff;
+                                // Same size, prefer one with ScanGroups
+                                const aHasScanning = scanGroupsByPageLayout.has(a.id);
+                                const bHasScanning = scanGroupsByPageLayout.has(b.id);
+                                return (bHasScanning ? 1 : 0) - (aHasScanning ? 1 : 0);
+                            });
+                            selectedPageLayoutId = layoutsWithInfo[0].id;
+                        }
+                        else if (this.pageLayoutPreference === 'scanning') {
+                            // Select layout with scanning enabled (check against actual ScanGroups)
+                            const scanningLayouts = layoutsWithInfo.filter((l) => scanGroupsByPageLayout.has(l.id));
+                            if (scanningLayouts.length > 0) {
+                                scanningLayouts.sort((a, b) => b.size - a.size);
+                                selectedPageLayoutId = scanningLayouts[0].id;
+                            }
+                            else {
+                                // Fallback to largest
+                                layoutsWithInfo.sort((a, b) => b.size - a.size);
+                                selectedPageLayoutId = layoutsWithInfo[0].id;
+                            }
+                        }
+                    }
+                }
+                catch (e) {
+                    // Error selecting PageLayout, will load all buttons
+                    console.warn(`[SnapProcessor] Failed to select PageLayout for page ${pageRow.Id}:`, e);
+                }
+                // Load buttons
+                let buttons = [];
+                try {
+                    const buttonColumns = getTableColumns('Button');
+                    const selectFields = [
+                        'b.Id',
+                        'b.Label',
+                        'b.Message',
+                        buttonColumns.has('LibrarySymbolId') ? 'b.LibrarySymbolId' : 'NULL AS LibrarySymbolId',
+                        buttonColumns.has('PageSetImageId') ? 'b.PageSetImageId' : 'NULL AS PageSetImageId',
+                        buttonColumns.has('BorderColor') ? 'b.BorderColor' : 'NULL AS BorderColor',
+                        buttonColumns.has('BorderThickness') ? 'b.BorderThickness' : 'NULL AS BorderThickness',
+                        buttonColumns.has('FontSize') ? 'b.FontSize' : 'NULL AS FontSize',
+                        buttonColumns.has('FontFamily') ? 'b.FontFamily' : 'NULL AS FontFamily',
+                        buttonColumns.has('FontStyle') ? 'b.FontStyle' : 'NULL AS FontStyle',
+                        buttonColumns.has('LabelColor') ? 'b.LabelColor' : 'NULL AS LabelColor',
+                        buttonColumns.has('BackgroundColor') ? 'b.BackgroundColor' : 'NULL AS BackgroundColor',
+                        buttonColumns.has('NavigatePageId') ? 'b.NavigatePageId' : 'NULL AS NavigatePageId',
+                        buttonColumns.has('ContentType') ? 'b.ContentType' : 'NULL AS ContentType',
+                    ];
+                    if (this.loadAudio) {
+                        selectFields.push(buttonColumns.has('MessageRecordingId')
+                            ? 'b.MessageRecordingId'
+                            : 'NULL AS MessageRecordingId');
+                        selectFields.push(buttonColumns.has('UseMessageRecording')
+                            ? 'b.UseMessageRecording'
+                            : 'NULL AS UseMessageRecording');
+                        selectFields.push(buttonColumns.has('SerializedMessageSoundMetadata')
+                            ? 'b.SerializedMessageSoundMetadata'
+                            : 'NULL AS SerializedMessageSoundMetadata');
+                    }
+                    const placementColumns = getTableColumns('ElementPlacement');
+                    const hasButtonPageLink = getTableColumns('ButtonPageLink').size > 0;
+                    selectFields.push(placementColumns.has('GridPosition') ? 'ep.GridPosition' : 'NULL AS GridPosition', placementColumns.has('PageLayoutId') ? 'ep.PageLayoutId' : 'NULL AS PageLayoutId', placementColumns.has('Visible') ? 'ep.Visible' : 'NULL AS Visible', 'er.PageId as ButtonPageId');
+                    if (hasButtonPageLink) {
+                        selectFields.push('bpl.PageUniqueId AS LinkedPageUniqueId');
+                    }
+                    else {
+                        selectFields.push('NULL AS LinkedPageUniqueId');
+                    }
+                    const hasCommandSequence = getTableColumns('CommandSequence').size > 0;
+                    if (hasCommandSequence) {
+                        selectFields.push('cs.SerializedCommands');
+                    }
+                    else {
+                        selectFields.push('NULL AS SerializedCommands');
+                    }
+                    const buttonQuery = `
+             SELECT ${selectFields.join(', ')}
+             FROM Button b
+             INNER JOIN ElementReference er ON b.ElementReferenceId = er.Id
+             LEFT JOIN ElementPlacement ep ON ep.ElementReferenceId = er.Id
+             ${hasButtonPageLink ? 'LEFT JOIN ButtonPageLink bpl ON b.Id = bpl.ButtonId' : ''}
+             ${hasCommandSequence ? 'LEFT JOIN CommandSequence cs ON b.Id = cs.ButtonId' : ''}
+             WHERE er.PageId = ? ${selectedPageLayoutId ? 'AND ep.PageLayoutId = ?' : ''}
+           `;
+                    if (selectedPageLayoutId) {
+                        buttons = db.prepare(buttonQuery).all(pageRow.Id, selectedPageLayoutId);
+                    }
+                    else {
+                        buttons = db.prepare(buttonQuery).all(pageRow.Id);
+                    }
+                }
+                catch (err) {
+                    const errorMessage = err instanceof Error ? err.message : String(err);
+                    const errorCode = err && typeof err === 'object' && 'code' in err ? err.code : undefined;
+                    if (errorCode === 'SQLITE_CORRUPT' ||
+                        errorCode === 'SQLITE_NOTADB' ||
+                        /malformed/i.test(errorMessage)) {
+                        throw new Error(`Snap database is corrupted or incomplete: ${errorMessage}`);
+                    }
+                    console.warn(`Failed to load buttons for page ${pageRow.Id}: ${errorMessage}`);
+                    // Skip this page instead of loading all buttons
+                    buttons = [];
+                }
+                const uniqueId = String(pageRow.UniqueId || pageRow.Id);
+                const page = tree.getPage(uniqueId);
+                if (!page) {
+                    continue;
+                }
+                // Initialize page grid if not exists (assume max 10x10 grid)
+                if (!pageGrids.has(uniqueId)) {
+                    const grid = [];
+                    for (let r = 0; r < 10; r++) {
+                        grid[r] = new Array(10).fill(null);
+                    }
+                    pageGrids.set(uniqueId, grid);
+                }
+                const pageGrid = pageGrids.get(uniqueId);
+                if (!pageGrid)
+                    continue;
+                buttons.forEach((btnRow) => {
+                    // Determine navigation target UniqueId, if possible
+                    let targetPageUniqueId = undefined;
+                    if (btnRow.NavigatePageId && idToUniqueId[String(btnRow.NavigatePageId)]) {
+                        targetPageUniqueId = idToUniqueId[String(btnRow.NavigatePageId)];
+                    }
+                    else if (btnRow.LinkedPageUniqueId) {
+                        targetPageUniqueId = String(btnRow.LinkedPageUniqueId);
+                    }
+                    else if (btnRow.PageUniqueId) {
+                        targetPageUniqueId = String(btnRow.PageUniqueId);
+                    }
+                    // Parse CommandSequence for navigation targets if not found yet
+                    if (btnRow.SerializedCommands) {
+                        try {
+                            const commands = JSON.parse(btnRow.SerializedCommands);
+                            const values = commands.$values || [];
+                            for (const cmd of values) {
+                                if (cmd.$type === '2' && cmd.LinkedPageId) {
+                                    // Normal Navigation
+                                    targetPageUniqueId = String(cmd.LinkedPageId);
+                                }
+                                else if (cmd.$type === '16') {
+                                    // Go to Home
+                                    targetPageUniqueId = defaultHomePageId;
+                                }
+                                else if (cmd.$type === '17') {
+                                    // Go to Keyboard
+                                    targetPageUniqueId = defaultKeyboardPageId;
+                                }
+                                else if (cmd.$type === '18') {
+                                    // Go to Dashboard
+                                    targetPageUniqueId = dashboardPageId;
+                                }
+                            }
+                        }
+                        catch (e) {
+                            // Ignore JSON parse errors in commands
+                        }
+                    }
+                    // Determine parent page association for this button
+                    const parentPageId = btnRow.ButtonPageId ? String(btnRow.ButtonPageId) : undefined;
+                    const parentUniqueId = parentPageId && idToUniqueId[parentPageId] ? idToUniqueId[parentPageId] : uniqueId;
+                    // Load audio recording if requested and available
+                    let audioRecording;
+                    if (this.loadAudio && btnRow.MessageRecordingId && btnRow.MessageRecordingId > 0) {
+                        try {
+                            const recordingData = db
+                                .prepare(`
+                SELECT Id, Identifier, Data FROM PageSetData WHERE Id = ?
+              `)
+                                .get(btnRow.MessageRecordingId);
+                            if (recordingData) {
+                                audioRecording = {
+                                    id: recordingData.Id,
+                                    data: recordingData.Data,
+                                    identifier: recordingData.Identifier,
+                                    metadata: btnRow.SerializedMessageSoundMetadata || undefined,
+                                };
+                            }
+                        }
+                        catch (e) {
+                            console.warn(`[SnapProcessor] Failed to load audio for button ${btnRow.Id}:`, e);
+                        }
+                    }
+                    // Create semantic action for Snap button
+                    let semanticAction;
+                    if (targetPageUniqueId) {
+                        semanticAction = {
+                            category: AACSemanticCategory.NAVIGATION,
+                            intent: AACSemanticIntent.NAVIGATE_TO,
+                            targetId: targetPageUniqueId,
+                            platformData: {
+                                snap: {
+                                    navigatePageId: btnRow.NavigatePageId,
+                                    elementReferenceId: btnRow.Id,
+                                },
+                            },
+                            fallback: {
+                                type: 'NAVIGATE',
+                                targetPageId: targetPageUniqueId,
+                            },
+                        };
+                    }
+                    else {
+                        semanticAction = {
+                            category: AACSemanticCategory.COMMUNICATION,
+                            intent: AACSemanticIntent.SPEAK_TEXT,
+                            text: btnRow.Message || btnRow.Label || '',
+                            platformData: {
+                                snap: {
+                                    elementReferenceId: btnRow.Id,
+                                },
+                            },
+                            fallback: {
+                                type: 'SPEAK',
+                                message: btnRow.Message || btnRow.Label || '',
+                            },
+                        };
+                    }
+                    const button = new AACButton({
+                        id: String(btnRow.Id),
+                        label: btnRow.Label || (btnRow.ContentType === 1 ? '[Prediction]' : ''),
+                        message: btnRow.Message || (btnRow.ContentType === 1 ? '[Prediction]' : btnRow.Label || ''),
+                        targetPageId: targetPageUniqueId,
+                        semanticAction: semanticAction,
+                        contentType: btnRow.ContentType === 1 ? 'AutoContent' : undefined,
+                        contentSubType: btnRow.ContentType === 1 ? 'Prediction' : undefined,
+                        audioRecording: audioRecording,
+                        visibility: mapSnapVisibility(btnRow.Visible),
+                        semantic_id: btnRow.LibrarySymbolId
+                            ? `snap_symbol_${btnRow.LibrarySymbolId}`
+                            : undefined, // Extract semantic_id from LibrarySymbolId
+                        style: {
+                            backgroundColor: btnRow.BackgroundColor
+                                ? `#${btnRow.BackgroundColor.toString(16)}`
+                                : undefined,
+                            borderColor: btnRow.BorderColor ? `#${btnRow.BorderColor.toString(16)}` : undefined,
+                            borderWidth: btnRow.BorderThickness,
+                            fontColor: btnRow.LabelColor ? `#${btnRow.LabelColor.toString(16)}` : undefined,
+                            fontSize: btnRow.FontSize,
+                            fontFamily: btnRow.FontFamily,
+                            fontStyle: btnRow.FontStyle?.toString(),
+                        },
+                    });
+                    // Add to the intended parent page
+                    const parentPage = tree.getPage(parentUniqueId);
+                    if (parentPage) {
+                        parentPage.addButton(button);
+                        // Add button to grid layout if position data is available
+                        const gridPositionStr = String(btnRow.GridPosition || '');
+                        if (gridPositionStr && gridPositionStr.includes(',')) {
+                            // Parse comma-separated coordinates "x,y"
+                            const [xStr, yStr] = gridPositionStr.split(',');
+                            const gridX = parseInt(xStr, 10);
+                            const gridY = parseInt(yStr, 10);
+                            // Set button x,y properties (critical for metrics!)
+                            if (!isNaN(gridX) && !isNaN(gridY)) {
+                                button.x = gridX;
+                                button.y = gridY;
+                                // Determine scan block from ScanGroups (TD Snap "Group Scan")
+                                // IMPORTANT: Only match against ScanGroups from the SAME PageLayout
+                                // A button can exist in multiple layouts with different positions
+                                const buttonPageLayoutId = btnRow.PageLayoutId;
+                                if (buttonPageLayoutId && scanGroupsByPageLayout.has(buttonPageLayoutId)) {
+                                    const scanGroups = scanGroupsByPageLayout.get(buttonPageLayoutId);
+                                    if (scanGroups && scanGroups.length > 0) {
+                                        // Find which ScanGroup contains this button's position
+                                        for (const scanGroup of scanGroups) {
+                                            // Skip if positions array is null or undefined
+                                            if (!scanGroup.positions || !Array.isArray(scanGroup.positions)) {
+                                                continue;
+                                            }
+                                            const foundInGroup = scanGroup.positions.some((pos) => pos.Column === gridX && pos.Row === gridY);
+                                            if (foundInGroup) {
+                                                // Use the scan block number from the ScanGroup
+                                                // ScanGroup scanBlock is already 1-based (index + 1)
+                                                button.scanBlock = scanGroup.scanBlock;
+                                                break; // Found the scan block, stop looking
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            // Place button in grid if within bounds and coordinates are valid
+                            if (!isNaN(gridX) &&
+                                !isNaN(gridY) &&
+                                gridX >= 0 &&
+                                gridY >= 0 &&
+                                gridY < 10 &&
+                                gridX < 10 &&
+                                pageGrid[gridY] &&
+                                pageGrid[gridY][gridX] === null) {
+                                // Generate clone_id for button at this position
+                                const rows = pageGrid.length;
+                                const cols = pageGrid[0] ? pageGrid[0].length : 10;
+                                button.clone_id = generateCloneId(rows, cols, gridY, gridX, button.label);
+                                pageGrid[gridY][gridX] = button;
+                            }
+                        }
+                    }
+                    // If this is a navigation button, update the target page's parentId
+                    if (targetPageUniqueId) {
+                        const targetPage = tree.getPage(targetPageUniqueId);
+                        if (targetPage) {
+                            targetPage.parentId = parentUniqueId;
+                        }
+                    }
+                });
+                // Set grid layout for the current page
+                const currentPage = tree.getPage(uniqueId);
+                if (currentPage && pageGrid) {
+                    currentPage.grid = pageGrid;
+                    // Track semantic_ids and clone_ids on the page
+                    const semanticIds = [];
+                    const cloneIds = [];
+                    pageGrid.forEach((row) => {
+                        row.forEach((btn) => {
+                            if (btn) {
+                                if (btn.semantic_id) {
+                                    semanticIds.push(btn.semantic_id);
+                                }
+                                if (btn.clone_id) {
+                                    cloneIds.push(btn.clone_id);
+                                }
+                            }
+                        });
+                    });
+                    if (semanticIds.length > 0) {
+                        currentPage.semantic_ids = semanticIds;
+                    }
+                    if (cloneIds.length > 0) {
+                        currentPage.clone_ids = cloneIds;
+                    }
+                }
+            }
+            return tree;
+        }
+        catch (error) {
+            const fileIdentifier = typeof filePathOrBuffer === 'string' ? filePathOrBuffer : '[buffer input]';
+            // Provide more specific error messages
+            if (error.code === 'SQLITE_NOTADB') {
+                throw new Error(`Invalid SQLite database file: ${typeof filePathOrBuffer === 'string' ? filePathOrBuffer : 'buffer'}`);
+            }
+            else if (error.code === 'ENOENT') {
+                throw new Error(`File not found: ${fileIdentifier}`);
+            }
+            else if (error.code === 'EACCES') {
+                throw new Error(`Permission denied accessing file: ${fileIdentifier}`);
+            }
+            else {
+                throw new Error(`Failed to load Snap file: ${error.message}`);
+            }
+        }
+        finally {
+            if (dbResult?.cleanup) {
+                dbResult.cleanup();
+            }
+            else if (dbResult?.db) {
+                dbResult.db.close();
+            }
+        }
+    }
+    async processTexts(filePathOrBuffer, translations, outputPath) {
+        if (!isNodeRuntime()) {
+            throw new Error('processTexts is only supported in Node.js environments for Snap files.');
+        }
+        // Load the tree, apply translations, and save to new file
+        const tree = await this.loadIntoTree(filePathOrBuffer);
+        // Apply translations to all text content
+        Object.values(tree.pages).forEach((page) => {
+            // Translate page names
+            if (page.name && translations.has(page.name)) {
+                const translatedName = translations.get(page.name);
+                if (translatedName !== undefined) {
+                    page.name = translatedName;
+                }
+            }
+            // Translate button labels and messages
+            page.buttons.forEach((button) => {
+                if (button.label && translations.has(button.label)) {
+                    const translatedLabel = translations.get(button.label);
+                    if (translatedLabel !== undefined) {
+                        button.label = translatedLabel;
+                    }
+                }
+                if (button.message && translations.has(button.message)) {
+                    const translatedMessage = translations.get(button.message);
+                    if (translatedMessage !== undefined) {
+                        button.message = translatedMessage;
+                    }
+                }
+            });
+        });
+        // Save the translated tree and return its content
+        await this.saveFromTree(tree, outputPath);
+        const fs = getFs();
+        return fs.readFileSync(outputPath);
+    }
+    async saveFromTree(tree, outputPath) {
+        if (!isNodeRuntime()) {
+            throw new Error('saveFromTree is only supported in Node.js environments for Snap files.');
+        }
+        await Promise.resolve();
+        const fs = getFs();
+        const path = getPath();
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        if (fs.existsSync(outputPath)) {
+            fs.unlinkSync(outputPath);
+        }
+        // Create a new SQLite database for Snap format
+        const Database = requireBetterSqlite3();
+        const db = new Database(outputPath, { readonly: false });
+        try {
+            // Create basic Snap database schema (simplified)
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS Page (
+          Id INTEGER PRIMARY KEY,
+          UniqueId TEXT UNIQUE,
+          Title TEXT,
+          Name TEXT,
+          BackgroundColor INTEGER
+        );
+
+        CREATE TABLE IF NOT EXISTS Button (
+          Id INTEGER PRIMARY KEY,
+          Label TEXT,
+          Message TEXT,
+          NavigatePageId INTEGER,
+          ElementReferenceId INTEGER,
+          LibrarySymbolId INTEGER,
+          PageSetImageId INTEGER,
+          MessageRecordingId INTEGER,
+          SerializedMessageSoundMetadata TEXT,
+          UseMessageRecording INTEGER,
+          LabelColor INTEGER,
+          BackgroundColor INTEGER,
+          BorderColor INTEGER,
+          BorderThickness REAL,
+          FontSize REAL,
+          FontFamily TEXT,
+          FontStyle INTEGER
+        );
+
+        CREATE TABLE IF NOT EXISTS ElementReference (
+          Id INTEGER PRIMARY KEY,
+          PageId INTEGER,
+          FOREIGN KEY (PageId) REFERENCES Page (Id)
+        );
+
+        CREATE TABLE IF NOT EXISTS ElementPlacement (
+          Id INTEGER PRIMARY KEY,
+          ElementReferenceId INTEGER,
+          GridPosition TEXT,
+          FOREIGN KEY (ElementReferenceId) REFERENCES ElementReference (Id)
+        );
+
+        CREATE TABLE IF NOT EXISTS PageSetData (
+          Id INTEGER PRIMARY KEY,
+          Identifier TEXT UNIQUE,
+          Data BLOB,
+          RefCount INTEGER DEFAULT 1
+        );
+
+        CREATE TABLE IF NOT EXISTS PageSetProperties (
+          Id INTEGER PRIMARY KEY,
+          Name TEXT,
+          Description TEXT,
+          Author TEXT,
+          Locale TEXT,
+          DefaultHomePageUniqueId TEXT,
+          DefaultKeyboardPageUniqueId TEXT,
+          DashboardUniqueId TEXT,
+          ToolBarUniqueId TEXT
+        );
+      `);
+            // Insert pages
+            let pageIdCounter = 1;
+            let buttonIdCounter = 1;
+            let elementRefIdCounter = 1;
+            let placementIdCounter = 1;
+            let pageSetDataIdCounter = 1;
+            const pageIdMap = new Map();
+            const pageSetDataIdentifierMap = new Map();
+            const insertPageSetData = db.prepare('INSERT INTO PageSetData (Id, Identifier, Data, RefCount) VALUES (?, ?, ?, ?)');
+            const incrementRefCount = db.prepare('UPDATE PageSetData SET RefCount = RefCount + 1 WHERE Id = ?');
+            // First pass: create all pages
+            Object.values(tree.pages).forEach((page) => {
+                const numericPageId = pageIdCounter++;
+                pageIdMap.set(page.id, numericPageId);
+                const insertPage = db.prepare('INSERT INTO Page (Id, UniqueId, Title, Name, BackgroundColor) VALUES (?, ?, ?, ?, ?)');
+                insertPage.run(numericPageId, page.id, page.name || '', page.name || '', page.style?.backgroundColor
+                    ? parseInt(page.style.backgroundColor.replace('#', ''), 16)
+                    : null);
+            });
+            // Second pass: create buttons with proper page references
+            Object.values(tree.pages).forEach((page) => {
+                const numericPageId = pageIdMap.get(page.id);
+                if (numericPageId === undefined) {
+                    return;
+                }
+                page.buttons.forEach((button, index) => {
+                    // Find button position in grid layout
+                    let gridPosition = `${index % 4},${Math.floor(index / 4)}`; // Default fallback
+                    if (page.grid && page.grid.length > 0) {
+                        // Search for button in grid layout
+                        for (let y = 0; y < page.grid.length; y++) {
+                            for (let x = 0; x < page.grid[y].length; x++) {
+                                const gridButton = page.grid[y][x];
+                                if (gridButton && gridButton.id === button.id) {
+                                    // Convert grid coordinates to comma-separated format
+                                    gridPosition = `${x},${y}`;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    const elementRefId = elementRefIdCounter++;
+                    // Insert ElementReference
+                    const insertElementRef = db.prepare('INSERT INTO ElementReference (Id, PageId) VALUES (?, ?)');
+                    insertElementRef.run(elementRefId, numericPageId);
+                    // Insert Button - handle semantic actions
+                    let navigatePageId = null;
+                    // Use semantic action if available
+                    if (button.semanticAction?.intent === AACSemanticIntent.NAVIGATE_TO) {
+                        const targetId = button.semanticAction.targetId || button.targetPageId;
+                        navigatePageId = targetId ? pageIdMap.get(targetId) || null : null;
+                    }
+                    const insertButton = db.prepare('INSERT INTO Button (Id, Label, Message, NavigatePageId, ElementReferenceId, LibrarySymbolId, PageSetImageId, MessageRecordingId, SerializedMessageSoundMetadata, UseMessageRecording, LabelColor, BackgroundColor, BorderColor, BorderThickness, FontSize, FontFamily, FontStyle) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+                    const audio = button.audioRecording;
+                    let messageRecordingId = null;
+                    let serializedMetadata = null;
+                    let useMessageRecording = 0;
+                    if (audio && Buffer.isBuffer(audio.data) && audio.data.length > 0) {
+                        const identifier = audio.identifier && audio.identifier.trim().length > 0
+                            ? audio.identifier.trim()
+                            : `audio_${buttonIdCounter}`;
+                        let audioId = pageSetDataIdentifierMap.get(identifier);
+                        if (!audioId) {
+                            audioId = pageSetDataIdCounter++;
+                            insertPageSetData.run(audioId, identifier, audio.data, 1);
+                            pageSetDataIdentifierMap.set(identifier, audioId);
+                        }
+                        else {
+                            incrementRefCount.run(audioId);
+                        }
+                        messageRecordingId = audioId;
+                        serializedMetadata = audio.metadata || null;
+                        useMessageRecording = 1;
+                    }
+                    // Retry logic for SQLite operations
+                    let retries = 3;
+                    while (retries > 0) {
+                        try {
+                            insertButton.run(buttonIdCounter++, button.label || '', button.message || button.label || '', navigatePageId, elementRefId, null, null, messageRecordingId, serializedMetadata, useMessageRecording, button.style?.fontColor
+                                ? parseInt(button.style.fontColor.replace('#', ''), 16)
+                                : null, button.style?.backgroundColor
+                                ? parseInt(button.style.backgroundColor.replace('#', ''), 16)
+                                : null, button.style?.borderColor
+                                ? parseInt(button.style.borderColor.replace('#', ''), 16)
+                                : null, button.style?.borderWidth, button.style?.fontSize, button.style?.fontFamily, button.style?.fontStyle ? parseInt(button.style.fontStyle) : null);
+                            break; // Success
+                        }
+                        catch (err) {
+                            if (err.code === 'SQLITE_IOERR' && retries > 1) {
+                                retries--;
+                                // Wait a bit before retrying
+                                const now = Date.now();
+                                while (Date.now() - now < 100) {
+                                    /* busy wait */
+                                }
+                            }
+                            else {
+                                throw err;
+                            }
+                        }
+                    }
+                    // Insert ElementPlacement
+                    const insertPlacement = db.prepare('INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition) VALUES (?, ?, ?)');
+                    insertPlacement.run(placementIdCounter++, elementRefId, gridPosition);
+                });
+            });
+            // Insert PageSetProperties metadata
+            const insertProps = db.prepare(`
+        INSERT INTO PageSetProperties (
+          Id, Name, Description, Author, Locale, 
+          DefaultHomePageUniqueId, DefaultKeyboardPageUniqueId, 
+          DashboardUniqueId, ToolBarUniqueId
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            insertProps.run(1, tree.metadata?.name || null, tree.metadata?.description || null, tree.metadata?.author || null, tree.metadata?.locale || null, tree.metadata?.defaultHomePageId || tree.rootId || null, tree.metadata?.defaultKeyboardPageId || null, tree.metadata?.dashboardId || null, tree.metadata?.hasGlobalToolbar ? tree.metadata.toolbarId || null : null);
+        }
+        finally {
+            db.close();
+        }
+    }
+    /**
+     * Add audio recording to a button in the database
+     */
+    async addAudioToButton(dbPath, buttonId, audioData, metadata) {
+        await Promise.resolve();
+        if (!isNodeRuntime()) {
+            throw new Error('addAudioToButton is only supported in Node.js environments.');
+        }
+        const Database = requireBetterSqlite3();
+        const crypto = getNodeRequire()('crypto');
+        const db = new Database(dbPath, { fileMustExist: true });
+        try {
+            // Ensure PageSetData table exists
+            db.exec(`
+            CREATE TABLE IF NOT EXISTS PageSetData (
+                Id INTEGER PRIMARY KEY,
+                Identifier TEXT UNIQUE,
+                Data BLOB
+            );
+        `);
+            // Generate SHA1 hash for the identifier
+            const sha1Hash = crypto.createHash('sha1').update(audioData).digest('hex');
+            const identifier = `SND:${sha1Hash}`;
+            // Check if audio with this identifier already exists
+            let audioId;
+            const existingAudio = db
+                .prepare('SELECT Id FROM PageSetData WHERE Identifier = ?')
+                .get(identifier);
+            if (existingAudio) {
+                audioId = existingAudio.Id;
+            }
+            else {
+                // Insert new audio data
+                const result = db
+                    .prepare('INSERT INTO PageSetData (Identifier, Data) VALUES (?, ?)')
+                    .run(identifier, audioData);
+                audioId = Number(result.lastInsertRowid);
+            }
+            // Update button to reference the audio
+            const updateButton = db.prepare('UPDATE Button SET MessageRecordingId = ?, UseMessageRecording = 1, SerializedMessageSoundMetadata = ? WHERE Id = ?');
+            const metadataJson = metadata ? JSON.stringify({ FileName: metadata }) : null;
+            updateButton.run(audioId, metadataJson, buttonId);
+            return audioId;
+        }
+        finally {
+            db.close();
+        }
+    }
+    /**
+     * Create a copy of the pageset with audio recordings added
+     */
+    async createAudioEnhancedPageset(sourceDbPath, targetDbPath, audioMappings) {
+        if (!isNodeRuntime()) {
+            throw new Error('createAudioEnhancedPageset is only supported in Node.js environments.');
+        }
+        const fs = getFs();
+        // Copy the source database to target
+        fs.copyFileSync(sourceDbPath, targetDbPath);
+        // Add audio recordings to the copy
+        for (const [buttonId, audioInfo] of audioMappings.entries()) {
+            await this.addAudioToButton(targetDbPath, buttonId, audioInfo.audioData, audioInfo.metadata);
+        }
+    }
+    /**
+     * Extract buttons from a specific page that need audio recordings
+     */
+    extractButtonsForAudio(dbPath, pageUniqueId) {
+        if (!isNodeRuntime()) {
+            throw new Error('extractButtonsForAudio is only supported in Node.js environments.');
+        }
+        const Database = requireBetterSqlite3();
+        const db = new Database(dbPath, { readonly: true });
+        try {
+            // Find the page by UniqueId
+            const page = db.prepare('SELECT * FROM Page WHERE UniqueId = ?').get(pageUniqueId);
+            if (!page) {
+                throw new Error(`Page with UniqueId ${pageUniqueId} not found`);
+            }
+            // Get buttons for this page
+            const buttons = db
+                .prepare(`
+        SELECT
+          b.Id, b.Label, b.Message, b.MessageRecordingId, b.UseMessageRecording
+        FROM Button b
+        JOIN ElementReference er ON b.ElementReferenceId = er.Id
+        WHERE er.PageId = ?
+      `)
+                .all(page.Id);
+            return buttons.map((btn) => ({
+                id: btn.Id,
+                label: btn.Label || '',
+                message: btn.Message || btn.Label || '',
+                hasAudio: !!(btn.MessageRecordingId && btn.MessageRecordingId > 0),
+            }));
+        }
+        finally {
+            db.close();
+        }
+    }
+    /**
+     * Extract strings with metadata for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    async extractStringsWithMetadata(filePath) {
+        return this.extractStringsWithMetadataGeneric(filePath);
+    }
+    /**
+     * Generate translated download for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    async generateTranslatedDownload(filePath, translatedStrings, sourceStrings) {
+        return this.generateTranslatedDownloadGeneric(filePath, translatedStrings, sourceStrings);
+    }
+    /**
+     * Validate Snap file format
+     * @param filePath - Path to the file to validate
+     * @returns Promise with validation result
+     */
+    async validate(filePath) {
+        return SnapValidator.validateFile(filePath);
+    }
+    /**
+     * Get available PageLayouts for a Snap file
+     * Useful for UI components that want to let users select layout size
+     * @param filePath - Path to the Snap file
+     * @returns Array of available PageLayouts with their dimensions
+     */
+    getAvailablePageLayouts(filePath) {
+        if (!isNodeRuntime()) {
+            throw new Error('getAvailablePageLayouts is only supported in Node.js environments.');
+        }
+        const fs = getFs();
+        const path = getPath();
+        const dbPath = typeof filePath === 'string' ? filePath : path.join(process.cwd(), 'temp.spb');
+        if (Buffer.isBuffer(filePath)) {
+            fs.writeFileSync(dbPath, filePath);
+        }
+        let db = null;
+        try {
+            const Database = requireBetterSqlite3();
+            db = new Database(dbPath, { readonly: true });
+            // Get unique PageLayouts based on PageLayoutSetting (dimensions)
+            const pageLayouts = db
+                .prepare(`
+          SELECT
+            MIN(pl.Id) as Id,
+            pl.PageLayoutSetting
+          FROM PageLayout pl
+          GROUP BY pl.PageLayoutSetting
+          ORDER BY pl.PageLayoutSetting
+        `)
+                .all();
+            // Parse the PageLayoutSetting format: "columns,rows,hasScanGroups,?"
+            const layouts = pageLayouts.map((pl) => {
+                const parts = pl.PageLayoutSetting.split(',');
+                const cols = parseInt(parts[0], 10) || 0;
+                const rows = parseInt(parts[1], 10) || 0;
+                const hasScanning = parts[2] === 'True';
+                return {
+                    id: pl.Id,
+                    cols,
+                    rows,
+                    size: cols * rows,
+                    hasScanning,
+                    label: `${cols}×${rows}${hasScanning ? ' (with scanning)' : ''}`,
+                };
+            });
+            // Sort by size (total buttons), with scanning layouts first
+            layouts.sort((a, b) => {
+                if (a.hasScanning && !b.hasScanning)
+                    return -1;
+                if (!a.hasScanning && b.hasScanning)
+                    return 1;
+                return b.size - a.size; // Larger sizes first
+            });
+            return layouts;
+        }
+        catch (error) {
+            console.error('[SnapProcessor] Failed to get available page layouts:', error);
+            return [];
+        }
+        finally {
+            if (db) {
+                db.close();
+            }
+            // Clean up temporary file if created from buffer
+            if (Buffer.isBuffer(filePath) && fs.existsSync(dbPath)) {
+                try {
+                    fs.unlinkSync(dbPath);
+                }
+                catch (e) {
+                    console.warn('Failed to clean up temporary file:', e);
+                }
+            }
+        }
+    }
+}
+export { SnapProcessor };