@willwade/aac-processors 0.0.7 → 0.0.9

package/dist/processors/gridset/helpers.js

@@ -1,4 +1,27 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9,8 +32,23 @@ exports.openImage = openImage;
 exports.generateGrid3Guid = generateGrid3Guid;
 exports.createSettingsXml = createSettingsXml;
 exports.createFileMapXml = createFileMapXml;
+exports.getCommonDocumentsPath = getCommonDocumentsPath;
+exports.findGrid3UserPaths = findGrid3UserPaths;
+exports.findGrid3HistoryDatabases = findGrid3HistoryDatabases;
+exports.findGrid3Users = findGrid3Users;
+exports.findGrid3Vocabularies = findGrid3Vocabularies;
+exports.findGrid3UserHistory = findGrid3UserHistory;
+exports.isGrid3Installed = isGrid3Installed;
+exports.readGrid3History = readGrid3History;
+exports.readGrid3HistoryForUser = readGrid3HistoryForUser;
+exports.readAllGrid3History = readAllGrid3History;
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const fast_xml_parser_1 = require("fast-xml-parser");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const dotnetTicks_1 = require("../../utils/dotnetTicks");
 function normalizeZipPath(p) {
     const unified = p.replace(/\\/g, '/');
     try {
@@ -20,6 +58,10 @@ function normalizeZipPath(p) {
         return unified;
     }
 }
+/**
+ * Build a map of button IDs to resolved image entry paths for a specific page.
+ * Helpful when rewriting zip entry names or validating images referenced in a grid.
+ */
 function getPageTokenImageMap(tree, pageId) {
     const map = new Map();
     const page = tree.getPage(pageId);
@@ -32,6 +74,10 @@ function getPageTokenImageMap(tree, pageId) {
     }
     return map;
 }
+/**
+ * Collect all image entries referenced across every page in a tree.
+ * Returns normalized zip entry paths that should be preserved when pruning images.
+ */
 function getAllowedImageEntries(tree) {
     const out = new Set();
     Object.values(tree.pages).forEach((page) => {
@@ -42,6 +88,12 @@ function getAllowedImageEntries(tree) {
     });
     return out;
 }
+/**
+ * Read an image entry from a gridset zip by path.
+ * @param gridsetBuffer Gridset archive contents
+ * @param entryPath Entry name inside the zip
+ * @returns Image data buffer or null if not found
+ */
 function openImage(gridsetBuffer, entryPath) {
     const zip = new adm_zip_1.default(gridsetBuffer);
     const want = normalizeZipPath(entryPath);
@@ -115,3 +167,253 @@ function createFileMapXml(grids) {
     };
     return builder.build(fileMapData);
 }
+/**
+ * Get the Windows Common Documents folder path from registry
+ * Falls back to default path if registry access fails
+ * @returns Path to Common Documents folder
+ */
+function getCommonDocumentsPath() {
+    // Only works on Windows
+    if (process.platform !== 'win32') {
+        return '';
+    }
+    try {
+        // Query registry for Common Documents path
+        const command = 'REG.EXE QUERY "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Shell Folders" /V "Common Documents"';
+        const output = (0, child_process_1.execSync)(command, { encoding: 'utf-8', windowsHide: true });
+        // Parse the output to extract the path
+        const match = output.match(/Common Documents\s+REG_SZ\s+(.+)/);
+        if (match && match[1]) {
+            return match[1].trim();
+        }
+    }
+    catch (error) {
+        // Registry access failed, fall back to default
+    }
+    // Default fallback path
+    return 'C:\\Users\\Public\\Documents';
+}
+/**
+ * Find all Grid3 user data paths
+ * Searches for users and language codes in the Grid3 directory structure
+ * C:\Users\Public\Documents\Smartbox\Grid 3\Users\{UserName}\{langCode}\Phrases\history.sqlite
+ * Grid set/vocabulary archives live alongside users at:
+ * C:\Users\Public\Documents\Smartbox\Grid 3\Users\{UserName}\Grid Sets\
+ * @returns Array of Grid3 user path information
+ */
+function findGrid3UserPaths() {
+    const results = [];
+    // Only works on Windows
+    if (process.platform !== 'win32') {
+        return results;
+    }
+    try {
+        const commonDocs = getCommonDocumentsPath();
+        // Use Windows path joining so tests that mock a Windows platform stay consistent even on POSIX runners
+        const grid3BasePath = path.win32.join(commonDocs, 'Smartbox', 'Grid 3', 'Users');
+        // Check if Grid3 Users directory exists
+        if (!fs.existsSync(grid3BasePath)) {
+            return results;
+        }
+        // Enumerate users
+        const users = fs.readdirSync(grid3BasePath, { withFileTypes: true });
+        for (const userDir of users) {
+            if (!userDir.isDirectory())
+                continue;
+            const userName = userDir.name;
+            const userPath = path.win32.join(grid3BasePath, userName);
+            // Enumerate language codes
+            const langDirs = fs.readdirSync(userPath, { withFileTypes: true });
+            for (const langDir of langDirs) {
+                if (!langDir.isDirectory())
+                    continue;
+                const langCode = langDir.name;
+                const basePath = path.win32.join(userPath, langCode);
+                const historyDbPath = path.win32.join(basePath, 'Phrases', 'history.sqlite');
+                // Only include if history database exists
+                if (fs.existsSync(historyDbPath)) {
+                    results.push({
+                        userName,
+                        langCode,
+                        basePath,
+                        historyDbPath,
+                    });
+                }
+            }
+        }
+    }
+    catch (error) {
+        // Silently fail if directory access fails
+    }
+    return results;
+}
+/**
+ * Find all Grid3 history database paths
+ * Convenience method that returns just the database file paths
+ * @returns Array of paths to history.sqlite files
+ */
+function findGrid3HistoryDatabases() {
+    return findGrid3UserPaths().map((userPath) => userPath.historyDbPath);
+}
+/**
+ * Get Grid 3 users (alias of findGrid3UserPaths for clarity)
+ */
+function findGrid3Users() {
+    return findGrid3UserPaths();
+}
+/**
+ * Find Grid 3 gridset/vocabulary files for each user
+ * @param userName Optional user filter; matches case-insensitively
+ * @returns Array of user/gridset path pairs
+ */
+function findGrid3Vocabularies(userName) {
+    const results = [];
+    if (process.platform !== 'win32') {
+        return results;
+    }
+    const commonDocs = getCommonDocumentsPath();
+    const grid3BasePath = path.win32.join(commonDocs, 'Smartbox', 'Grid 3', 'Users');
+    if (!fs.existsSync(grid3BasePath)) {
+        return results;
+    }
+    const normalizedUser = userName?.toLowerCase();
+    const users = fs.readdirSync(grid3BasePath, { withFileTypes: true });
+    for (const userDir of users) {
+        if (!userDir.isDirectory())
+            continue;
+        if (normalizedUser && userDir.name.toLowerCase() !== normalizedUser)
+            continue;
+        const userRoot = path.win32.join(grid3BasePath, userDir.name);
+        const gridSetsDir = path.win32.join(userRoot, 'Grid Sets');
+        if (!fs.existsSync(gridSetsDir))
+            continue;
+        const entries = fs.readdirSync(gridSetsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const ext = path.extname(entry.name).toLowerCase();
+            if (ext === '.gridset' || ext === '.grd' || ext === '.grdl') {
+                results.push({
+                    userName: userDir.name,
+                    gridsetPath: path.win32.join(gridSetsDir, entry.name),
+                });
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Find a specific user's Grid 3 history database
+ * @param userName User name to search for (case-insensitive)
+ * @param langCode Optional language code filter (case-insensitive)
+ * @returns Path to history.sqlite or null if not found
+ */
+function findGrid3UserHistory(userName, langCode) {
+    if (!userName)
+        return null;
+    const normalizedUser = userName.toLowerCase();
+    const normalizedLang = langCode?.toLowerCase();
+    const match = findGrid3UserPaths().find((u) => u.userName.toLowerCase() === normalizedUser &&
+        (!normalizedLang || u.langCode.toLowerCase() === normalizedLang));
+    return match?.historyDbPath ?? null;
+}
+/**
+ * Check whether Grid 3 appears to be installed (Windows only)
+ */
+function isGrid3Installed() {
+    if (process.platform !== 'win32')
+        return false;
+    const commonDocs = getCommonDocumentsPath();
+    if (!commonDocs)
+        return false;
+    const grid3BasePath = path.win32.join(commonDocs, 'Smartbox', 'Grid 3', 'Users');
+    return fs.existsSync(grid3BasePath);
+}
+function parseGrid3ContentXml(xmlContent) {
+    const regex = /<r>(?:<!\[CDATA\[)?(.*?)(?:\]\]>)?<\/r>/gis;
+    const parts = [];
+    let match;
+    while ((match = regex.exec(xmlContent)) !== null) {
+        parts.push(match[1]);
+    }
+    if (parts.length > 0) {
+        return parts.join('');
+    }
+    return xmlContent.replace(/<[^>]+>/g, '').trim();
+}
+/**
+ * Read history events from a Grid 3 history.sqlite database.
+ * @param historyDbPath Absolute path to the history database
+ * @returns Parsed history entries grouped by phrase
+ */
+function readGrid3History(historyDbPath) {
+    if (!fs.existsSync(historyDbPath))
+        return [];
+    const db = new better_sqlite3_1.default(historyDbPath, { readonly: true });
+    const rows = db
+        .prepare(`
+      SELECT p.Id as PhraseId,
+             p.Text as TextValue,
+             p.Content as ContentXml,
+             ph.Timestamp as TickValue,
+             ph.Latitude as Latitude,
+             ph.Longitude as Longitude
+      FROM PhraseHistory ph
+      INNER JOIN Phrases p ON p.Id = ph.PhraseId
+      WHERE ph.Timestamp <> 0
+      ORDER BY ph.Timestamp ASC
+    `)
+        .all();
+    const events = new Map();
+    for (const row of rows) {
+        const phraseId = row.PhraseId;
+        const rawContentSource = [row.ContentXml, row.TextValue].find((candidate) => {
+            if (candidate === null || candidate === undefined)
+                return false;
+            const asString = String(candidate);
+            return asString.trim().length > 0;
+        });
+        if (rawContentSource === undefined) {
+            continue; // Skip history rows with no usable text content
+        }
+        const rawContentText = String(rawContentSource);
+        const contentText = parseGrid3ContentXml(rawContentText);
+        const rawXml = typeof row.ContentXml === 'string' && row.ContentXml.trim().length > 0
+            ? row.ContentXml
+            : undefined;
+        const entry = events.get(phraseId) ??
+            {
+                id: `grid:${phraseId}`,
+                content: contentText,
+                occurrences: [],
+                rawXml,
+            };
+        entry.occurrences.push({
+            timestamp: (0, dotnetTicks_1.dotNetTicksToDate)(BigInt(row.TickValue ?? 0)),
+            latitude: row.Latitude ?? null,
+            longitude: row.Longitude ?? null,
+        });
+        events.set(phraseId, entry);
+    }
+    return Array.from(events.values());
+}
+/**
+ * Convenience wrapper to load history for a specific Grid 3 user/lang combination.
+ * @param userName Grid 3 user name (case-insensitive)
+ * @param langCode Optional language code to narrow selection (case-insensitive)
+ * @returns History entries for that user/language, or empty array if none
+ */
+function readGrid3HistoryForUser(userName, langCode) {
+    const dbPath = findGrid3UserHistory(userName, langCode);
+    if (!dbPath)
+        return [];
+    return readGrid3History(dbPath);
+}
+/**
+ * Load all available Grid 3 histories on the machine.
+ * @returns Combined history entries from every discovered history.sqlite
+ */
+function readAllGrid3History() {
+    const paths = findGrid3HistoryDatabases();
+    return paths.flatMap((p) => readGrid3History(p));
+}

package/dist/processors/index.d.ts

@@ -7,12 +7,12 @@ export { OpmlProcessor } from './opmlProcessor';
 export { SnapProcessor } from './snapProcessor';
 export { TouchChatProcessor } from './touchchatProcessor';
 export { AstericsGridProcessor } from './astericsGridProcessor';
-export { getPageTokenImageMap, getAllowedImageEntries, openImage, generateGrid3Guid, createSettingsXml, createFileMapXml, } from './gridset/helpers';
-export { getPageTokenImageMap as getGridsetPageTokenImageMap, getAllowedImageEntries as getGridsetAllowedImageEntries, openImage as openGridsetImage, generateGrid3Guid as generateGridsetGuid, createSettingsXml as createGridsetSettingsXml, createFileMapXml as createGridsetFileMapXml, } from './gridset/helpers';
+export { getPageTokenImageMap, getAllowedImageEntries, openImage, generateGrid3Guid, createSettingsXml, createFileMapXml, getCommonDocumentsPath, findGrid3UserPaths, findGrid3HistoryDatabases, findGrid3Users, findGrid3Vocabularies, findGrid3UserHistory, isGrid3Installed, readGrid3History, readGrid3HistoryForUser, readAllGrid3History, type Grid3UserPath, type Grid3VocabularyPath, type Grid3HistoryEntry, } from './gridset/helpers';
+export { getPageTokenImageMap as getGridsetPageTokenImageMap, getAllowedImageEntries as getGridsetAllowedImageEntries, openImage as openGridsetImage, generateGrid3Guid as generateGridsetGuid, createSettingsXml as createGridsetSettingsXml, createFileMapXml as createGridsetFileMapXml, getCommonDocumentsPath as getGridsetCommonDocumentsPath, findGrid3UserPaths as findGridsetUserPaths, findGrid3HistoryDatabases as findGridsetHistoryDatabases, findGrid3Users as findGridsetUsers, findGrid3Vocabularies as findGridsetVocabularies, findGrid3UserHistory as findGridsetUserHistory, isGrid3Installed as isGridsetInstalled, readGrid3History as readGridsetHistory, readGrid3HistoryForUser as readGridsetHistoryForUser, readAllGrid3History as readAllGridsetHistory, } from './gridset/helpers';
 export { resolveGrid3CellImage } from './gridset/resolver';
 export { createWordlist, extractWordlists, updateWordlist, wordlistToXml, type WordList, type WordListItem, } from './gridset/wordlistHelpers';
 export { getNamedColor, rgbaToHex, channelToHex, clampColorChannel, clampAlpha, toHexColor, darkenColor, normalizeColor, ensureAlphaChannel, } from './gridset/colorUtils';
 export { DEFAULT_GRID3_STYLES, CATEGORY_STYLES, createDefaultStylesXml, createCategoryStyle, } from './gridset/styleHelpers';
 export { ensureAlphaChannel as ensureAlphaChannelFromStyles } from './gridset/styleHelpers';
-export { getPageTokenImageMap as getSnapPageTokenImageMap, getAllowedImageEntries as getSnapAllowedImageEntries, openImage as openSnapImage, } from './snap/helpers';
+export { getPageTokenImageMap as getSnapPageTokenImageMap, getAllowedImageEntries as getSnapAllowedImageEntries, openImage as openSnapImage, findSnapPackages, findSnapPackagePath, findSnapUsers, findSnapUserVocabularies, findSnapUserHistory, isSnapInstalled, readSnapUsage, readSnapUsageForUser, type SnapPackagePath, type SnapUserInfo, type SnapUsageEntry, } from './snap/helpers';
 export { getPageTokenImageMap as getTouchChatPageTokenImageMap, getAllowedImageEntries as getTouchChatAllowedImageEntries, openImage as openTouchChatImage, } from './touchchat/helpers';

package/dist/processors/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openTouchChatImage = exports.getTouchChatAllowedImageEntries = exports.getTouchChatPageTokenImageMap = exports.openSnapImage = exports.getSnapAllowedImageEntries = exports.getSnapPageTokenImageMap = exports.ensureAlphaChannelFromStyles = exports.createCategoryStyle = exports.createDefaultStylesXml = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = exports.ensureAlphaChannel = exports.normalizeColor = exports.darkenColor = exports.toHexColor = exports.clampAlpha = exports.clampColorChannel = exports.channelToHex = exports.rgbaToHex = exports.getNamedColor = exports.wordlistToXml = exports.updateWordlist = exports.extractWordlists = exports.createWordlist = exports.resolveGrid3CellImage = exports.createGridsetFileMapXml = exports.createGridsetSettingsXml = exports.generateGridsetGuid = exports.openGridsetImage = exports.getGridsetAllowedImageEntries = exports.getGridsetPageTokenImageMap = exports.createFileMapXml = exports.createSettingsXml = exports.generateGrid3Guid = exports.openImage = exports.getAllowedImageEntries = exports.getPageTokenImageMap = exports.AstericsGridProcessor = exports.TouchChatProcessor = exports.SnapProcessor = exports.OpmlProcessor = exports.ObfProcessor = exports.GridsetProcessor = exports.ExcelProcessor = exports.DotProcessor = exports.ApplePanelsProcessor = void 0;
+exports.clampColorChannel = exports.channelToHex = exports.rgbaToHex = exports.getNamedColor = exports.wordlistToXml = exports.updateWordlist = exports.extractWordlists = exports.createWordlist = exports.resolveGrid3CellImage = exports.readAllGridsetHistory = exports.readGridsetHistoryForUser = exports.readGridsetHistory = exports.isGridsetInstalled = exports.findGridsetUserHistory = exports.findGridsetVocabularies = exports.findGridsetUsers = exports.findGridsetHistoryDatabases = exports.findGridsetUserPaths = exports.getGridsetCommonDocumentsPath = exports.createGridsetFileMapXml = exports.createGridsetSettingsXml = exports.generateGridsetGuid = exports.openGridsetImage = exports.getGridsetAllowedImageEntries = exports.getGridsetPageTokenImageMap = exports.readAllGrid3History = exports.readGrid3HistoryForUser = exports.readGrid3History = exports.isGrid3Installed = exports.findGrid3UserHistory = exports.findGrid3Vocabularies = exports.findGrid3Users = exports.findGrid3HistoryDatabases = exports.findGrid3UserPaths = exports.getCommonDocumentsPath = exports.createFileMapXml = exports.createSettingsXml = exports.generateGrid3Guid = exports.openImage = exports.getAllowedImageEntries = exports.getPageTokenImageMap = exports.AstericsGridProcessor = exports.TouchChatProcessor = exports.SnapProcessor = exports.OpmlProcessor = exports.ObfProcessor = exports.GridsetProcessor = exports.ExcelProcessor = exports.DotProcessor = exports.ApplePanelsProcessor = void 0;
+exports.openTouchChatImage = exports.getTouchChatAllowedImageEntries = exports.getTouchChatPageTokenImageMap = exports.readSnapUsageForUser = exports.readSnapUsage = exports.isSnapInstalled = exports.findSnapUserHistory = exports.findSnapUserVocabularies = exports.findSnapUsers = exports.findSnapPackagePath = exports.findSnapPackages = exports.openSnapImage = exports.getSnapAllowedImageEntries = exports.getSnapPageTokenImageMap = exports.ensureAlphaChannelFromStyles = exports.createCategoryStyle = exports.createDefaultStylesXml = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = exports.ensureAlphaChannel = exports.normalizeColor = exports.darkenColor = exports.toHexColor = exports.clampAlpha = void 0;
 var applePanelsProcessor_1 = require("./applePanelsProcessor");
 Object.defineProperty(exports, "ApplePanelsProcessor", { enumerable: true, get: function () { return applePanelsProcessor_1.ApplePanelsProcessor; } });
 var dotProcessor_1 = require("./dotProcessor");
@@ -27,6 +28,16 @@ Object.defineProperty(exports, "openImage", { enumerable: true, get: function ()
 Object.defineProperty(exports, "generateGrid3Guid", { enumerable: true, get: function () { return helpers_1.generateGrid3Guid; } });
 Object.defineProperty(exports, "createSettingsXml", { enumerable: true, get: function () { return helpers_1.createSettingsXml; } });
 Object.defineProperty(exports, "createFileMapXml", { enumerable: true, get: function () { return helpers_1.createFileMapXml; } });
+Object.defineProperty(exports, "getCommonDocumentsPath", { enumerable: true, get: function () { return helpers_1.getCommonDocumentsPath; } });
+Object.defineProperty(exports, "findGrid3UserPaths", { enumerable: true, get: function () { return helpers_1.findGrid3UserPaths; } });
+Object.defineProperty(exports, "findGrid3HistoryDatabases", { enumerable: true, get: function () { return helpers_1.findGrid3HistoryDatabases; } });
+Object.defineProperty(exports, "findGrid3Users", { enumerable: true, get: function () { return helpers_1.findGrid3Users; } });
+Object.defineProperty(exports, "findGrid3Vocabularies", { enumerable: true, get: function () { return helpers_1.findGrid3Vocabularies; } });
+Object.defineProperty(exports, "findGrid3UserHistory", { enumerable: true, get: function () { return helpers_1.findGrid3UserHistory; } });
+Object.defineProperty(exports, "isGrid3Installed", { enumerable: true, get: function () { return helpers_1.isGrid3Installed; } });
+Object.defineProperty(exports, "readGrid3History", { enumerable: true, get: function () { return helpers_1.readGrid3History; } });
+Object.defineProperty(exports, "readGrid3HistoryForUser", { enumerable: true, get: function () { return helpers_1.readGrid3HistoryForUser; } });
+Object.defineProperty(exports, "readAllGrid3History", { enumerable: true, get: function () { return helpers_1.readAllGrid3History; } });
 var helpers_2 = require("./gridset/helpers");
 Object.defineProperty(exports, "getGridsetPageTokenImageMap", { enumerable: true, get: function () { return helpers_2.getPageTokenImageMap; } });
 Object.defineProperty(exports, "getGridsetAllowedImageEntries", { enumerable: true, get: function () { return helpers_2.getAllowedImageEntries; } });
@@ -34,6 +45,16 @@ Object.defineProperty(exports, "openGridsetImage", { enumerable: true, get: func
 Object.defineProperty(exports, "generateGridsetGuid", { enumerable: true, get: function () { return helpers_2.generateGrid3Guid; } });
 Object.defineProperty(exports, "createGridsetSettingsXml", { enumerable: true, get: function () { return helpers_2.createSettingsXml; } });
 Object.defineProperty(exports, "createGridsetFileMapXml", { enumerable: true, get: function () { return helpers_2.createFileMapXml; } });
+Object.defineProperty(exports, "getGridsetCommonDocumentsPath", { enumerable: true, get: function () { return helpers_2.getCommonDocumentsPath; } });
+Object.defineProperty(exports, "findGridsetUserPaths", { enumerable: true, get: function () { return helpers_2.findGrid3UserPaths; } });
+Object.defineProperty(exports, "findGridsetHistoryDatabases", { enumerable: true, get: function () { return helpers_2.findGrid3HistoryDatabases; } });
+Object.defineProperty(exports, "findGridsetUsers", { enumerable: true, get: function () { return helpers_2.findGrid3Users; } });
+Object.defineProperty(exports, "findGridsetVocabularies", { enumerable: true, get: function () { return helpers_2.findGrid3Vocabularies; } });
+Object.defineProperty(exports, "findGridsetUserHistory", { enumerable: true, get: function () { return helpers_2.findGrid3UserHistory; } });
+Object.defineProperty(exports, "isGridsetInstalled", { enumerable: true, get: function () { return helpers_2.isGrid3Installed; } });
+Object.defineProperty(exports, "readGridsetHistory", { enumerable: true, get: function () { return helpers_2.readGrid3History; } });
+Object.defineProperty(exports, "readGridsetHistoryForUser", { enumerable: true, get: function () { return helpers_2.readGrid3HistoryForUser; } });
+Object.defineProperty(exports, "readAllGridsetHistory", { enumerable: true, get: function () { return helpers_2.readAllGrid3History; } });
 var resolver_1 = require("./gridset/resolver");
 Object.defineProperty(exports, "resolveGrid3CellImage", { enumerable: true, get: function () { return resolver_1.resolveGrid3CellImage; } });
 // Gridset (Grid 3) wordlist helpers
@@ -62,11 +83,19 @@ Object.defineProperty(exports, "createCategoryStyle", { enumerable: true, get: f
 // Re-export ensureAlphaChannel from styleHelpers for backward compatibility
 var styleHelpers_2 = require("./gridset/styleHelpers");
 Object.defineProperty(exports, "ensureAlphaChannelFromStyles", { enumerable: true, get: function () { return styleHelpers_2.ensureAlphaChannel; } });
-// Snap helpers (stubs)
+// Snap helpers
 var helpers_3 = require("./snap/helpers");
 Object.defineProperty(exports, "getSnapPageTokenImageMap", { enumerable: true, get: function () { return helpers_3.getPageTokenImageMap; } });
 Object.defineProperty(exports, "getSnapAllowedImageEntries", { enumerable: true, get: function () { return helpers_3.getAllowedImageEntries; } });
 Object.defineProperty(exports, "openSnapImage", { enumerable: true, get: function () { return helpers_3.openImage; } });
+Object.defineProperty(exports, "findSnapPackages", { enumerable: true, get: function () { return helpers_3.findSnapPackages; } });
+Object.defineProperty(exports, "findSnapPackagePath", { enumerable: true, get: function () { return helpers_3.findSnapPackagePath; } });
+Object.defineProperty(exports, "findSnapUsers", { enumerable: true, get: function () { return helpers_3.findSnapUsers; } });
+Object.defineProperty(exports, "findSnapUserVocabularies", { enumerable: true, get: function () { return helpers_3.findSnapUserVocabularies; } });
+Object.defineProperty(exports, "findSnapUserHistory", { enumerable: true, get: function () { return helpers_3.findSnapUserHistory; } });
+Object.defineProperty(exports, "isSnapInstalled", { enumerable: true, get: function () { return helpers_3.isSnapInstalled; } });
+Object.defineProperty(exports, "readSnapUsage", { enumerable: true, get: function () { return helpers_3.readSnapUsage; } });
+Object.defineProperty(exports, "readSnapUsageForUser", { enumerable: true, get: function () { return helpers_3.readSnapUsageForUser; } });
 // TouchChat helpers (stubs)
 var helpers_4 = require("./touchchat/helpers");
 Object.defineProperty(exports, "getTouchChatPageTokenImageMap", { enumerable: true, get: function () { return helpers_4.getPageTokenImageMap; } });

package/dist/processors/obfProcessor.js

@@ -235,7 +235,12 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 buttonPositions.set(id, index);
                 return id;
             });
-            return { rows: 1, columns: fallbackRow.length, order: [fallbackRow], buttonPositions };
+            return {
+                rows: 1,
+                columns: fallbackRow.length,
+                order: [fallbackRow],
+                buttonPositions,
+            };
         }
         const order = [];
         for (let rowIndex = 0; rowIndex < totalRows; rowIndex++) {

package/dist/processors/snap/helpers.d.ts

@@ -1,4 +1,91 @@
 import { AACTree } from '../../core/treeStructure';
+/**
+ * Build a map of button IDs to resolved image entries for a specific page.
+ * Mirrors the Grid helper for consumers that expect image reference data.
+ */
 export declare function getPageTokenImageMap(tree: AACTree, pageId: string): Map<string, string>;
+/**
+ * Collect all image entry paths referenced in a Snap tree.
+ * Currently empty until resolvedImageEntry is populated by the processor.
+ */
 export declare function getAllowedImageEntries(_tree: AACTree): Set<string>;
+/**
+ * Read a binary asset from a Snap pageset.
+ * Not implemented yet; provided for API symmetry with other processors.
+ */
 export declare function openImage(_dbOrFile: string | Buffer, _entryPath: string): Buffer | null;
+/**
+ * Snap package path information
+ */
+export interface SnapPackagePath {
+    packageName: string;
+    packagePath: string;
+}
+export interface SnapUserInfo {
+    userId: string;
+    userPath: string;
+    vocabPaths: string[];
+}
+export interface SnapUsageEntry {
+    id: string;
+    content: string;
+    occurrences: Array<{
+        timestamp: Date;
+        modeling?: boolean;
+        accessMethod?: number | null;
+    }>;
+    platform?: {
+        label?: string;
+        message?: string;
+        buttonId?: string;
+    };
+}
+/**
+ * Find Tobii Communicator Snap package paths
+ * Searches in %LOCALAPPDATA%\Packages for Snap-related packages
+ * @param packageNamePattern Optional pattern to filter package names (default: 'TobiiDynavox')
+ * @returns Array of Snap package path information
+ */
+export declare function findSnapPackages(packageNamePattern?: string): SnapPackagePath[];
+/**
+ * Find the first Snap package path matching the pattern
+ * Convenience method for when you expect only one Snap installation
+ * @param packageNamePattern Optional pattern to filter package names (default: 'TobiiDynavox')
+ * @returns Path to the first matching Snap package, or null if not found
+ */
+export declare function findSnapPackagePath(packageNamePattern?: string): string | null;
+/**
+ * Find Snap user directories and their vocab files (.sps/.spb)
+ * Typical path:
+ * C:\Users\{username}\AppData\Roaming\Tobii Dynavox\Snap Scene\Users\{userId}\
+ * @param packageNamePattern Optional package filter (default TobiiDynavox)
+ * @returns Array of user info with vocab paths
+ */
+export declare function findSnapUsers(packageNamePattern?: string): SnapUserInfo[];
+/**
+ * Find vocab files for a specific Snap user (or all users)
+ * @param userId Optional user identifier filter (case-sensitive directory name)
+ * @param packageNamePattern Optional package filter
+ * @returns Array of vocab file paths
+ */
+export declare function findSnapUserVocabularies(userId?: string, packageNamePattern?: string): string[];
+/**
+ * Attempt to find history/analytics files for a Snap user by name
+ * Currently searches for files containing "history" under the user directory
+ * @param userId User identifier (directory name)
+ * @param packageNamePattern Optional package filter
+ * @returns Array of history file paths (may be empty if not found)
+ */
+export declare function findSnapUserHistory(userId: string, packageNamePattern?: string): string[];
+/**
+ * Check whether TD Snap appears to be installed (Windows only)
+ */
+export declare function isSnapInstalled(packageNamePattern?: string): boolean;
+/**
+ * Read Snap usage history from a pageset file (.sps/.spb)
+ */
+export declare function readSnapUsage(pagesetPath: string): SnapUsageEntry[];
+/**
+ * Read Snap usage history for a user (all pagesets)
+ */
+export declare function readSnapUsageForUser(userId?: string, packageNamePattern?: string): SnapUsageEntry[];