@willwade/aac-processors 0.0.18 → 0.0.20

package/dist/core/baseProcessor.d.ts

@@ -61,7 +61,7 @@ export interface VocabPlacementMetadata {
 }
 export interface VocabLocation {
     table: string;
-    id: number;
+    id: string | number;
     column: string;
     casing: StringCasing;
 }

package/dist/core/baseProcessor.js

@@ -130,7 +130,7 @@ class BaseProcessor {
                     const key = page.name.trim().toLowerCase();
                     const vocabLocation = {
                         table: 'pages',
-                        id: parseInt(page.id) || 0,
+                        id: page.id,
                         column: 'NAME',
                         casing: (0, stringCasing_1.detectCasing)(page.name),
                     };
@@ -142,7 +142,7 @@ class BaseProcessor {
                         const key = button.label.trim().toLowerCase();
                         const vocabLocation = {
                             table: 'buttons',
-                            id: parseInt(button.id) || 0,
+                            id: button.id,
                             column: 'LABEL',
                             casing: (0, stringCasing_1.detectCasing)(button.label),
                         };
@@ -156,7 +156,7 @@ class BaseProcessor {
                         const key = button.message.trim().toLowerCase();
                         const vocabLocation = {
                             table: 'buttons',
-                            id: parseInt(button.id) || 0,
+                            id: button.id,
                             column: 'MESSAGE',
                             casing: (0, stringCasing_1.detectCasing)(button.message),
                         };

package/dist/core/treeStructure.d.ts

@@ -1,4 +1,5 @@
-import { AACButton as IAACButton, AACPage as IAACPage, AACTree as IAACTree, AACStyle } from '../types/aac';
+import { AACButton as IAACButton, AACPage as IAACPage, AACTree as IAACTree, AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata, AACStyle } from '../types/aac';
+export { AACTreeMetadata, SnapMetadata, GridSetMetadata, AstericsGridMetadata, TouchChatMetadata };
 export declare enum AACSemanticCategory {
     COMMUNICATION = "communication",// Speech, text output
     NAVIGATION = "navigation",// Page/grid navigation
@@ -234,9 +235,13 @@ export declare class AACTree implements IAACTree {
     pages: {
         [key: string]: AACPage;
     };
-    private _rootId;
+    metadata: AACTreeMetadata;
     get rootId(): string | null;
     set rootId(id: string | null);
+    get toolbarId(): string | null;
+    set toolbarId(id: string | null);
+    get dashboardId(): string | null;
+    set dashboardId(id: string | null);
     constructor();
     addPage(page: AACPage): void;
     getPage(id: string): AACPage | undefined;

package/dist/core/treeStructure.js

@@ -202,19 +202,31 @@ class AACPage {
 exports.AACPage = AACPage;
 class AACTree {
     get rootId() {
-        return this._rootId;
+        return this.metadata.defaultHomePageId || null;
     }
     set rootId(id) {
-        this._rootId = id;
+        this.metadata.defaultHomePageId = id || undefined;
+    }
+    get toolbarId() {
+        return this.metadata.toolbarId || null;
+    }
+    set toolbarId(id) {
+        this.metadata.toolbarId = id || undefined;
+    }
+    get dashboardId() {
+        return this.metadata.dashboardId || null;
+    }
+    set dashboardId(id) {
+        this.metadata.dashboardId = id || undefined;
     }
     constructor() {
         this.pages = {};
-        this._rootId = null;
+        this.metadata = {};
     }
     addPage(page) {
         this.pages[page.id] = page;
-        if (!this._rootId)
-            this._rootId = page.id;
+        if (!this.rootId)
+            this.rootId = page.id;
     }
     getPage(id) {
         return this.pages[id];

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './core/baseProcessor';
 export * from './core/stringCasing';
 export * from './processors';
 export * as Analytics from './utilities/analytics';
+export * from './utilities/analytics';
 export * as Validation from './validation';
 export * as Gridset from './gridset';
 export * as Snap from './snap';

package/dist/index.js

@@ -52,6 +52,8 @@ __exportStar(require("./processors"), exports);
 // ===================================================================
 // Analytics namespace
 exports.Analytics = __importStar(require("./utilities/analytics"));
+// Also export analytics classes directly for convenience
+__exportStar(require("./utilities/analytics"), exports);
 // Validation namespace
 exports.Validation = __importStar(require("./validation"));
 // Processor namespaces (platform-specific utilities)

package/dist/processors/applePanelsProcessor.js

@@ -139,6 +139,7 @@ class ApplePanelsProcessor extends baseProcessor_1.BaseProcessor {
         }
         const data = { panels: panelsData };
         const tree = new treeStructure_1.AACTree();
+        tree.metadata.format = 'applepanels';
         data.panels.forEach((panel) => {
             const page = new treeStructure_1.AACPage({
                 id: panel.id,
@@ -309,16 +310,17 @@ class ApplePanelsProcessor extends baseProcessor_1.BaseProcessor {
                 fs_1.default.mkdirSync(resourcesPath, { recursive: true });
             // Create Info.plist (bundle mode only)
             const infoPlist = {
-                ASCConfigurationDisplayName: 'AAC Processors Export',
+                ASCConfigurationDisplayName: tree.metadata?.name || 'AAC Processors Export',
                 ASCConfigurationIdentifier: `com.aacprocessors.${Date.now()}`,
                 ASCConfigurationProductSupportType: 'VirtualKeyboard',
-                ASCConfigurationVersion: '7.1',
-                CFBundleDevelopmentRegion: 'en',
+                ASCConfigurationVersion: tree.metadata?.version || '7.1',
+                CFBundleDevelopmentRegion: tree.metadata?.locale || 'en',
                 CFBundleIdentifier: 'com.aacprocessors.panel.export',
-                CFBundleName: 'AAC Processors Panels',
-                CFBundleShortVersionString: '1.0',
+                CFBundleName: tree.metadata?.name || 'AAC Processors Panels',
+                CFBundleShortVersionString: tree.metadata?.version || '1.0',
                 CFBundleVersion: '1',
-                NSHumanReadableCopyright: 'Generated by AAC Processors',
+                NSHumanReadableCopyright: tree.metadata?.copyright ||
+                    `Generated by AAC Processors${tree.metadata?.author ? ` - Author: ${tree.metadata.author}` : ''}`,
             };
             const infoPlistContent = plist_1.default.build(infoPlist);
             fs_1.default.writeFileSync(path_1.default.join(contentsPath, 'Info.plist'), infoPlistContent);

package/dist/processors/astericsGridProcessor.js

@@ -740,6 +740,41 @@ class AstericsGridProcessor extends baseProcessor_1.BaseProcessor {
             // Set the page's grid layout
             page.grid = gridLayout;
         });
+        // Set metadata for Asterics Grid files
+        const astericsMetadata = {
+            format: 'asterics',
+            hasGlobalGrid: false, // Can be extended in the future
+        };
+        if (grdFile.grids && grdFile.grids.length > 0) {
+            astericsMetadata.name = this.getLocalizedLabel(grdFile.grids[0].label);
+            // Extract all unique languages from all grids and elements
+            const languages = new Set();
+            grdFile.grids.forEach((grid) => {
+                if (grid.label) {
+                    Object.keys(grid.label).forEach((lang) => languages.add(lang));
+                }
+                grid.gridElements?.forEach((element) => {
+                    if (element.label) {
+                        Object.keys(element.label).forEach((lang) => languages.add(lang));
+                    }
+                    // Also check word forms for languages
+                    element.wordForms?.forEach((wf) => {
+                        if (wf.lang)
+                            languages.add(wf.lang);
+                    });
+                });
+            });
+            if (languages.size > 0) {
+                astericsMetadata.languages = Array.from(languages).sort();
+                // Set primary locale to English if available, otherwise the first language found
+                astericsMetadata.locale = languages.has('en')
+                    ? 'en'
+                    : languages.has('de')
+                        ? 'de'
+                        : astericsMetadata.languages[0];
+            }
+        }
+        tree.metadata = astericsMetadata;
         // Set the home page from metadata.homeGridId
         if (grdFile.metadata && grdFile.metadata.homeGridId) {
             tree.rootId = grdFile.metadata.homeGridId;
@@ -1276,6 +1311,7 @@ class AstericsGridProcessor extends baseProcessor_1.BaseProcessor {
                         filename: button.audioRecording.identifier || `audio-${button.id}`,
                     });
                 }
+                const locale = tree.metadata?.locale || 'en';
                 return {
                     id: button.id,
                     modelName: 'GridElement',
@@ -1284,7 +1320,7 @@ class AstericsGridProcessor extends baseProcessor_1.BaseProcessor {
                     height: 1,
                     x: calculatedX,
                     y: calculatedY,
-                    label: { en: button.label },
+                    label: { [locale]: button.label },
                     wordForms: [],
                     image: {
                         data: null,
@@ -1308,7 +1344,7 @@ class AstericsGridProcessor extends baseProcessor_1.BaseProcessor {
                 id: page.id,
                 modelName: 'GridData',
                 modelVersion: '{"major": 5, "minor": 0, "patch": 0}',
-                label: { en: page.name },
+                label: { [tree.metadata?.locale || 'en']: page.name },
                 rowCount: calculatedRows,
                 minColumnCount: calculatedCols,
                 gridElements: gridElements,

package/dist/processors/dotProcessor.js

@@ -107,6 +107,7 @@ class DotProcessor extends baseProcessor_1.BaseProcessor {
         }
         const { nodes, edges } = this.parseDotFile(content);
         const tree = new treeStructure_1.AACTree();
+        tree.metadata.format = 'dot';
         // Create pages for each node and add a self button representing the node label
         for (const node of nodes) {
             const page = new treeStructure_1.AACPage({
@@ -164,11 +165,14 @@ class DotProcessor extends baseProcessor_1.BaseProcessor {
         return resultBuffer;
     }
     saveFromTree(tree, _outputPath) {
-        let dotContent = 'digraph AACBoard {\n';
+        let dotContent = `digraph "${tree.metadata?.name || 'AACBoard'}" {\n`;
         // Helper to escape DOT string
         const escapeDotString = (str) => {
             return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
         };
+        if (tree.metadata?.name) {
+            dotContent += `  label="${escapeDotString(tree.metadata.name)}";\n`;
+        }
         // Add nodes
         for (const pageId in tree.pages) {
             const page = tree.pages[pageId];

package/dist/processors/excelProcessor.js

@@ -54,7 +54,9 @@ class ExcelProcessor extends baseProcessor_1.BaseProcessor {
      */
     loadIntoTree(_filePathOrBuffer) {
         console.warn('ExcelProcessor.loadIntoTree is not implemented yet.');
-        return new treeStructure_1.AACTree();
+        const tree = new treeStructure_1.AACTree();
+        tree.metadata.format = 'excel';
+        return tree;
     }
     /**
      * Process texts in Excel file (apply translations)
@@ -486,11 +488,14 @@ class ExcelProcessor extends baseProcessor_1.BaseProcessor {
      */
     async saveFromTreeAsync(tree, outputPath) {
         const workbook = new ExcelJS.Workbook();
-        // Set workbook properties
-        workbook.creator = 'AACProcessors';
+        const metadata = tree.metadata;
+        // Set workbook properties from tree metadata
+        workbook.creator = metadata?.author || 'AACProcessors';
         workbook.lastModifiedBy = 'AACProcessors';
         workbook.created = new Date();
         workbook.modified = new Date();
+        workbook.title = metadata?.name || '';
+        workbook.subject = metadata?.description || '';
         // If no pages, create a default empty worksheet
         if (Object.keys(tree.pages).length === 0) {
             const worksheet = workbook.addWorksheet('Empty');

package/dist/processors/gridsetProcessor.js

@@ -380,6 +380,12 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         const parser = new fast_xml_parser_1.XMLParser({ ignoreAttributes: false });
         const isEncryptedArchive = typeof filePathOrBuffer === 'string' && filePathOrBuffer.toLowerCase().endsWith('.gridsetx');
         const encryptedContentPassword = this.getGridsetPassword(filePathOrBuffer);
+        // Initialize metadata
+        const metadata = {
+            format: 'gridset',
+            isSmartBox: isEncryptedArchive, // SmartBox files are .gridsetx encrypted archives
+            passwordProtected: !!password,
+        };
         const readEntryBuffer = (entry) => {
             const raw = entry.getData();
             if (!isEncryptedArchive)
@@ -1321,6 +1327,71 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
             if (settingsEntry) {
                 const settingsXml = readEntryBuffer(settingsEntry).toString('utf8');
                 const settingsData = parser.parse(settingsXml);
+                const gsName = settingsData?.GridSetSettings?.Name ||
+                    settingsData?.gridSetSettings?.name ||
+                    settingsData?.GridsetSettings?.Name;
+                if (gsName)
+                    metadata.name = gsName;
+                const gsDesc = settingsData?.GridSetSettings?.Description ||
+                    settingsData?.gridSetSettings?.description ||
+                    settingsData?.GridsetSettings?.Description;
+                if (gsDesc)
+                    metadata.description = gsDesc;
+                const gsLang = settingsData?.GridSetSettings?.PrimaryLanguage ||
+                    settingsData?.gridSetSettings?.primaryLanguage ||
+                    settingsData?.GridsetSettings?.PrimaryLanguage;
+                if (gsLang && typeof gsLang === 'string') {
+                    metadata.locale = gsLang;
+                    metadata.languages = [gsLang];
+                }
+                const gsAuthor = settingsData?.GridSetSettings?.Author ||
+                    settingsData?.gridSetSettings?.author ||
+                    settingsData?.GridsetSettings?.Author;
+                if (gsAuthor)
+                    metadata.author = gsAuthor;
+                const docUrl = settingsData?.GridSetSettings?.DocumentationUrl ||
+                    settingsData?.gridSetSettings?.documentationUrl ||
+                    settingsData?.GridsetSettings?.DocumentationUrl;
+                if (docUrl) {
+                    metadata.homepageUrl = docUrl;
+                    metadata.documentationUrl = docUrl;
+                }
+                const docSlug = settingsData?.GridSetSettings?.DocumentationSlug ||
+                    settingsData?.gridSetSettings?.documentationSlug ||
+                    settingsData?.GridsetSettings?.DocumentationSlug;
+                if (docSlug)
+                    metadata.documentationSlug = docSlug;
+                const thumbnail = settingsData?.GridSetSettings?.Thumbnail ||
+                    settingsData?.gridSetSettings?.thumbnail ||
+                    settingsData?.GridsetSettings?.Thumbnail;
+                if (thumbnail)
+                    metadata.thumbnail = thumbnail;
+                const thumbBg = settingsData?.GridSetSettings?.ThumbnailBackground ||
+                    settingsData?.gridSetSettings?.thumbnailBackground ||
+                    settingsData?.GridsetSettings?.ThumbnailBackground;
+                if (thumbBg)
+                    metadata.thumbnailBackground = thumbBg;
+                const picSearchKeys = settingsData?.GridSetSettings?.PictureSearch?.PictureSearchKeys?.PictureSearchKey ||
+                    settingsData?.gridSetSettings?.pictureSearch?.pictureSearchKeys?.pictureSearchKey ||
+                    settingsData?.GridsetSettings?.PictureSearch?.PictureSearchKeys?.PictureSearchKey;
+                if (picSearchKeys) {
+                    metadata.pictureSearchKeys = Array.isArray(picSearchKeys)
+                        ? picSearchKeys
+                        : [picSearchKeys];
+                }
+                const appearance = settingsData?.GridSetSettings?.Appearance ||
+                    settingsData?.gridSetSettings?.appearance ||
+                    settingsData?.GridsetSettings?.Appearance;
+                if (appearance) {
+                    metadata.appearance = {
+                        textAtTop: appearance.TextAtTop === '1' ||
+                            appearance.textAtTop === '1' ||
+                            appearance.TextAtTop === 1,
+                        computerControlCellSize: appearance.ComputerControlCellSize
+                            ? parseFloat(String(appearance.ComputerControlCellSize))
+                            : undefined,
+                    };
+                }
                 const startGridName = settingsData?.GridSetSettings?.StartGrid ||
                     settingsData?.gridSetSettings?.startGrid ||
                     settingsData?.GridsetSettings?.StartGrid;
@@ -1328,19 +1399,22 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                     // Resolve the grid name to grid ID
                     const homeGridId = gridNameToIdMap.get(startGridName);
                     if (homeGridId) {
-                        tree.rootId = homeGridId;
+                        metadata.defaultHomePageId = homeGridId;
                     }
                 }
                 const keyboardGridName = settingsData?.GridSetSettings?.KeyboardGrid ||
-                    settingsData?.gridSetSettings?.keyboardGrid;
+                    settingsData?.gridSetSettings?.keyboardGrid ||
+                    settingsData?.GridsetSettings?.KeyboardGrid;
                 if (keyboardGridName && typeof keyboardGridName === 'string') {
-                    tree.keyboardGridName = keyboardGridName;
+                    metadata.defaultKeyboardPageId = gridNameToIdMap.get(keyboardGridName);
                 }
             }
         }
         catch (e) {
             // If settings.xml parsing fails, tree.rootId will default to first page
         }
+        // Set metadata on tree
+        tree.metadata = metadata;
         return tree;
     }
     processTexts(filePathOrBuffer, translations, outputPath) {

package/dist/processors/obfProcessor.js

@@ -202,6 +202,17 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                     console.log('[OBF] Detected .obf file, parsed as JSON');
                     const page = this.processBoard(boardData, filePathOrBuffer);
                     tree.addPage(page);
+                    // Set metadata from root board
+                    tree.metadata.format = 'obf';
+                    tree.metadata.name = boardData.name;
+                    tree.metadata.description = boardData.description_html;
+                    tree.metadata.locale = boardData.locale;
+                    tree.metadata.id = boardData.id;
+                    if (boardData.url)
+                        tree.metadata.url = boardData.url;
+                    if (boardData.locale)
+                        tree.metadata.languages = [boardData.locale];
+                    tree.rootId = page.id;
                     return tree;
                 }
                 else {
@@ -219,6 +230,18 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
             console.log('[OBF] Detected buffer/string as OBF JSON');
             const page = this.processBoard(asJson, '[bufferOrString]');
             tree.addPage(page);
+            // Set metadata from root board
+            tree.metadata.format = 'obf';
+            tree.metadata.name = asJson.name;
+            tree.metadata.description = asJson.description_html;
+            tree.metadata.locale = asJson.locale;
+            tree.metadata.id = asJson.id;
+            if (asJson.url)
+                tree.metadata.url = asJson.url;
+            if (asJson.locale) {
+                tree.metadata.languages = [asJson.locale];
+            }
+            tree.rootId = page.id;
             return tree;
         }
         // Otherwise, try as ZIP (.obz). Detect likely zip signature first; throw if neither JSON nor ZIP
@@ -249,6 +272,19 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 if (boardData) {
                     const page = this.processBoard(boardData, entry.entryName);
                     tree.addPage(page);
+                    // Set metadata if not already set (use first board as reference)
+                    if (!tree.metadata.format) {
+                        tree.metadata.format = 'obf';
+                        tree.metadata.name = boardData.name;
+                        tree.metadata.description = boardData.description_html;
+                        tree.metadata.locale = boardData.locale;
+                        tree.metadata.id = boardData.id;
+                        if (boardData.url)
+                            tree.metadata.url = boardData.url;
+                        if (boardData.locale)
+                            tree.metadata.languages = [boardData.locale];
+                        tree.rootId = page.id;
+                    }
                 }
                 else {
                     console.warn('[OBF] Skipped entry (not valid OBF JSON):', entry.entryName);
@@ -298,15 +334,20 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
         }
         return { rows: totalRows, columns: totalColumns, order, buttonPositions };
     }
-    createObfBoardFromPage(page, fallbackName) {
+    createObfBoardFromPage(page, fallbackName, metadata) {
         const { rows, columns, order, buttonPositions } = this.buildGridMetadata(page);
-        const boardName = page.name || fallbackName;
+        const boardName = metadata?.name && page.id === metadata?.defaultHomePageId
+            ? metadata.name
+            : page.name || fallbackName;
         return {
             format: OBF_FORMAT_VERSION,
             id: page.id,
-            locale: page.locale || 'en',
+            url: metadata?.url,
+            locale: metadata?.locale || page.locale || 'en',
             name: boardName,
-            description_html: page.descriptionHtml || boardName,
+            description_html: metadata?.description && page.id === metadata?.defaultHomePageId
+                ? metadata.description
+                : page.descriptionHtml || boardName,
             grid: {
                 rows,
                 columns,
@@ -368,14 +409,14 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
             if (!rootPage) {
                 throw new Error('No pages to save');
             }
-            const obfBoard = this.createObfBoardFromPage(rootPage, 'Exported Board');
+            const obfBoard = this.createObfBoardFromPage(rootPage, 'Exported Board', tree.metadata);
             fs_1.default.writeFileSync(outputPath, JSON.stringify(obfBoard, null, 2));
         }
         else {
             // Save as OBZ (zip with multiple OBF files)
             const zip = new adm_zip_1.default();
             Object.values(tree.pages).forEach((page) => {
-                const obfBoard = this.createObfBoardFromPage(page, 'Board');
+                const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
                 const obfContent = JSON.stringify(obfBoard, null, 2);
                 zip.addFile(`${page.id}.obf`, Buffer.from(obfContent, 'utf8'));
             });

package/dist/processors/obfsetProcessor.js

@@ -37,6 +37,7 @@ class ObfsetProcessor extends baseProcessor_1.BaseProcessor {
      */
     loadIntoTree(filePathOrBuffer) {
         const tree = new treeStructure_1.AACTree();
+        tree.metadata.format = 'obfset';
         let content;
         if (Buffer.isBuffer(filePathOrBuffer)) {
             content = filePathOrBuffer.toString('utf-8');

package/dist/processors/opmlProcessor.js

@@ -109,6 +109,7 @@ class OpmlProcessor extends baseProcessor_1.BaseProcessor {
             throw new Error(`Invalid OPML XML: ${e?.message || String(e)}`);
         }
         const tree = new treeStructure_1.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) {

package/dist/processors/snapProcessor.d.ts

@@ -49,5 +49,23 @@ declare class SnapProcessor extends BaseProcessor {
      * @returns Promise with validation result
      */
     validate(filePath: string): Promise<ValidationResult>;
+    /**
+     * 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: string): PageLayoutInfo[];
+}
+/**
+ * Interface for PageLayout information returned by getAvailablePageLayouts
+ */
+export interface PageLayoutInfo {
+    id: number;
+    cols: number;
+    rows: number;
+    size: number;
+    hasScanning: boolean;
+    label: string;
 }
 export { SnapProcessor };

package/dist/processors/snapProcessor.js

@@ -78,16 +78,33 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
             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;
-                    const toolbarId = properties.ToolBarUniqueId;
+                    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.rootId = toolbarId;
+                        tree.toolbarId = toolbarId || null;
+                        tree.rootId = toolbarId || defaultHomePageId || null;
                     }
                     else if (defaultHomePageId) {
                         tree.rootId = defaultHomePageId;
@@ -896,5 +913,74 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
     async validate(filePath) {
         return snapValidator_1.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) {
+        const dbPath = typeof filePath === 'string' ? filePath : path_1.default.join(process.cwd(), 'temp.spb');
+        if (Buffer.isBuffer(filePath)) {
+            fs_1.default.writeFileSync(dbPath, filePath);
+        }
+        let db = null;
+        try {
+            db = new better_sqlite3_1.default(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_1.default.existsSync(dbPath)) {
+                try {
+                    fs_1.default.unlinkSync(dbPath);
+                }
+                catch (e) {
+                    console.warn('Failed to clean up temporary file:', e);
+                }
+            }
+        }
+    }
 }
 exports.SnapProcessor = SnapProcessor;

package/dist/processors/touchchatProcessor.js

@@ -429,6 +429,8 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                     tree.rootId = rootPageId;
                 }
             }
+            // Set metadata for TouchChat files
+            tree.metadata.format = 'touchchat';
             return tree;
         }
         finally {

package/dist/types/aac.d.ts

@@ -132,14 +132,78 @@ export interface AACPage {
     scanningConfig?: ScanningConfig;
     scanBlocksConfig?: any[];
 }
+/**
+ * Generic metadata interface for AAC files
+ * All processors can extend this with their specific properties
+ */
+export interface AACTreeMetadata {
+    format?: string;
+    version?: string;
+    locale?: string;
+    languages?: string[];
+    name?: string;
+    description?: string;
+    author?: string;
+    copyright?: string;
+    homepageUrl?: string;
+    url?: string;
+    id?: string;
+    defaultHomePageId?: string;
+    defaultKeyboardPageId?: string;
+    hasGlobalToolbar?: boolean;
+    toolbarId?: string;
+    dashboardId?: string;
+    [key: string]: any;
+}
+/**
+ * Snap-specific metadata
+ */
+export interface SnapMetadata extends AACTreeMetadata {
+    format: 'snap';
+    dashboardId?: string;
+}
+/**
+ * GridSet-specific metadata
+ */
+export interface GridSetMetadata extends AACTreeMetadata {
+    format: 'gridset';
+    isSmartBox?: boolean;
+    passwordProtected?: boolean;
+    pictureSearchKeys?: string[];
+    thumbnail?: string;
+    thumbnailBackground?: string;
+    documentationUrl?: string;
+    documentationSlug?: string;
+    appearance?: {
+        textAtTop?: boolean;
+        computerControlCellSize?: number;
+    };
+}
+/**
+ * Asterics-specific metadata
+ */
+export interface AstericsGridMetadata extends AACTreeMetadata {
+    format: 'asterics';
+    hasGlobalGrid?: boolean;
+    globalGridId?: string;
+}
+/**
+ * TouchChat-specific metadata
+ */
+export interface TouchChatMetadata extends AACTreeMetadata {
+    format: 'touchchat';
+}
 export interface AACTree {
     pages: {
         [key: string]: AACPage;
     };
+    metadata: AACTreeMetadata;
+    rootId: string | null;
+    toolbarId: string | null;
     addPage(page: AACPage): void;
     getPage(id: string): AACPage | undefined;
 }
 export interface AACProcessor {
-    extractTexts(filePath: string): string[];
-    loadIntoTree(filePath: string): AACTree;
+    extractTexts(filePath: string | Buffer): string[];
+    loadIntoTree(filePath: string | Buffer): AACTree;
 }

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

@@ -35,7 +35,7 @@ class MetricsCalculator {
         if (!rootBoard) {
             throw new Error('No root board found in tree');
         }
-        this.locale = rootBoard.locale || 'en';
+        this.locale = tree.metadata?.locale || rootBoard.locale || 'en';
         // Step 1: Build semantic/clone reference maps
         const { setRefs, setPcts } = this.buildReferenceMaps(tree);
         // Step 2: BFS traversal from root board
@@ -128,6 +128,9 @@ class MetricsCalculator {
         if (options.spellingPageId) {
             spellingPage = tree.getPage(options.spellingPageId) || null;
         }
+        if (!spellingPage && tree.metadata?.defaultKeyboardPageId) {
+            spellingPage = tree.getPage(tree.metadata.defaultKeyboardPageId) || null;
+        }
         if (!spellingPage) {
             // Look for pages with keyboard-like names or content
             spellingPage =

package/dist/validation/gridsetValidator.d.ts

@@ -17,6 +17,18 @@ export declare class GridsetValidator extends BaseValidator {
      * Main validation method
      */
     validate(content: Buffer | Uint8Array, filename: string, filesize: number): Promise<ValidationResult>;
+    /**
+     * Check if the buffer is a zip archive
+     */
+    private isZip;
+    /**
+     * Validate a single XML file (legacy or exploded format)
+     */
+    private validateSingleXml;
+    /**
+     * Validate a ZIP archive (.gridset)
+     */
+    private validateZipArchive;
     /**
      * Validate Gridset structure
      */

package/dist/validation/gridsetValidator.js

@@ -22,6 +22,9 @@ var __importStar = (this && this.__importStar) || function (mod) {
     __setModuleDefault(result, mod);
     return result;
 };
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GridsetValidator = void 0;
 /* eslint-disable @typescript-eslint/require-await */
@@ -30,6 +33,7 @@ exports.GridsetValidator = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const xml2js = __importStar(require("xml2js"));
+const adm_zip_1 = __importDefault(require("adm-zip"));
 const baseValidator_1 = require("./baseValidator");
 /**
  * Validator for Grid3/Smartbox Gridset files (.gridset, .gridsetx)
@@ -86,6 +90,27 @@ class GridsetValidator extends baseValidator_1.BaseValidator {
             });
             return this.buildResult(filename, filesize, 'gridset');
         }
+        const isZip = this.isZip(content);
+        if (isZip) {
+            await this.validateZipArchive(content, filename, filesize);
+        }
+        else {
+            await this.validateSingleXml(content, filename, filesize);
+        }
+        return this.buildResult(filename, filesize, 'gridset');
+    }
+    /**
+     * Check if the buffer is a zip archive
+     */
+    isZip(content) {
+        if (content.length < 4)
+            return false;
+        return content[0] === 0x50 && content[1] === 0x4b && content[2] === 0x03 && content[3] === 0x04;
+    }
+    /**
+     * Validate a single XML file (legacy or exploded format)
+     */
+    async validateSingleXml(content, filename, _filesize) {
         let xmlObj = null;
         await this.add_check('xml_parse', 'valid XML', async () => {
             try {
@@ -97,10 +122,8 @@ class GridsetValidator extends baseValidator_1.BaseValidator {
                 this.err(`Failed to parse XML: ${e.message}`, true);
             }
         });
-        if (!xmlObj) {
-            return this.buildResult(filename, filesize, 'gridset');
-        }
-        // eslint-disable-next-line @typescript-eslint/require-await
+        if (!xmlObj)
+            return;
         await this.add_check('xml_structure', 'gridset root element', async () => {
             if (!xmlObj.gridset && !xmlObj.Gridset) {
                 this.err('missing root gridset element', true);
@@ -110,7 +133,71 @@ class GridsetValidator extends baseValidator_1.BaseValidator {
         if (gridset) {
             await this.validateGridsetStructure(gridset, filename, content);
         }
-        return this.buildResult(filename, filesize, 'gridset');
+    }
+    /**
+     * Validate a ZIP archive (.gridset)
+     */
+    async validateZipArchive(content, filename, _filesize) {
+        let zip;
+        try {
+            zip = new adm_zip_1.default(Buffer.from(content));
+        }
+        catch (e) {
+            this.err(`Failed to open ZIP archive: ${e.message}`, true);
+            return;
+        }
+        const entries = zip.getEntries();
+        // Check for gridset.xml (required)
+        await this.add_check('gridset_xml_presence', 'gridset.xml presence', async () => {
+            const gridsetEntry = entries.find((e) => e.entryName.toLowerCase() === 'gridset.xml');
+            if (!gridsetEntry) {
+                this.err('Missing gridset.xml in archive', true);
+            }
+            else {
+                try {
+                    const gridsetXml = gridsetEntry.getData().toString('utf-8');
+                    const parser = new xml2js.Parser();
+                    const xmlObj = await parser.parseStringPromise(gridsetXml);
+                    const gridset = xmlObj.gridset || xmlObj.Gridset;
+                    if (!gridset) {
+                        this.err('Invalid gridset.xml structure', true);
+                    }
+                    else {
+                        await this.validateGridsetStructure(gridset, filename, Buffer.from(gridsetXml));
+                    }
+                }
+                catch (e) {
+                    this.err(`Failed to parse gridset.xml: ${e.message}`, true);
+                }
+            }
+        });
+        // Check for settings.xml (highly recommended/required for metadata)
+        await this.add_check('settings_xml_presence', 'settings.xml presence', async () => {
+            const settingsEntry = entries.find((e) => e.entryName.toLowerCase() === 'settings.xml');
+            if (!settingsEntry) {
+                this.warn('Missing settings.xml in archive (required for full metadata)');
+            }
+            else {
+                try {
+                    const settingsXml = settingsEntry.getData().toString('utf-8');
+                    const parser = new xml2js.Parser();
+                    const xmlObj = await parser.parseStringPromise(settingsXml);
+                    const settings = xmlObj.GridSetSettings || xmlObj.gridSetSettings || xmlObj.GridsetSettings;
+                    if (!settings) {
+                        this.warn('Invalid settings.xml structure');
+                    }
+                    else {
+                        // Basic validation of settings.xml
+                        if (!settings.StartGrid && !settings.startGrid) {
+                            this.warn('settings.xml missing StartGrid element');
+                        }
+                    }
+                }
+                catch (e) {
+                    this.warn(`Failed to parse settings.xml: ${e.message}`);
+                }
+            }
+        });
     }
     /**
      * Validate Gridset structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",