fixing bugs

Author: willwade

README.md

@@ -58,6 +58,37 @@ npm run build
 
 ---
 
+## Using with Electron
+
+`better-sqlite3` is a native module and must be rebuilt against Electron's Node.js runtime. If you see a `NODE_MODULE_VERSION` mismatch error, rebuild after installing dependencies:
+
+```bash
+npm install
+npx electron-rebuild
+```
+
+Or add a postinstall hook so the rebuild happens automatically:
+
+```json
+{
+  "scripts": {
+    "postinstall": "electron-builder install-app-deps"
+  }
+}
+```
+
+This step is only required for Electron apps; regular Node.js consumers do not need it.
+
+---
+
+## Windows Data Paths
+
+- **Grid 3 history**: `C:\Users\Public\Documents\Smartbox\Grid 3\Users\{username}\{langCode}\Phrases\history.sqlite`
+- **Grid 3 vocabularies**: `C:\Users\Public\Documents\Smartbox\Grid 3\Users\{username}\Grid Sets\`
+- **Snap vocabularies**: `C:\Users\{username}\AppData\Roaming\Tobii Dynavox\Snap Scene\Users\{userId}\` (`.sps`/`.spb`)
+
+---
+
 ## 🔧 Quick Start
 
 ### Basic Usage (TypeScript/ES6)

src/processors/gridset/helpers.ts

@@ -205,6 +205,8 @@ export function getCommonDocumentsPath(): string {
  * 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
  */
 export function findGrid3UserPaths(): Grid3UserPath[] {
@@ -331,6 +333,8 @@ export function findGrid3Vocabularies(userName?: string): Grid3VocabularyPath[]
  * @returns Path to history.sqlite or null if not found
  */
 export function findGrid3UserHistory(userName: string, langCode?: string): string | null {
+  if (!userName) return null;
+
   const normalizedUser = userName.toLowerCase();
   const normalizedLang = langCode?.toLowerCase();
 
@@ -404,14 +408,28 @@ export function readGrid3History(historyDbPath: string): Grid3HistoryEntry[] {
 
   for (const row of rows) {
     const phraseId: number = row.PhraseId;
-    const contentText = parseGrid3ContentXml(String(row.ContentXml ?? row.TextValue ?? ''));
+    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: row.ContentXml,
+        rawXml,
       } as Grid3HistoryEntry);
 
     entry.occurrences.push({

src/processors/snap/helpers.ts

@@ -163,6 +163,8 @@ export function findSnapPackagePath(packageNamePattern = 'TobiiDynavox'): string
 
 /**
  * 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
  */

test/history.test.ts

@@ -71,6 +71,44 @@ describe('History analytics', () => {
     expect(entry.occurrences[0].longitude).toBeCloseTo(-1.2);
   });
 
+  it('skips Grid 3 history rows without text and falls back to plain text when XML is missing', () => {
+    const dbPath = path.join(tempDir, 'grid3-history-missing.sqlite');
+    const db = new Database(dbPath);
+    db.exec(`
+      CREATE TABLE Phrases (Id INTEGER PRIMARY KEY AUTOINCREMENT, Text TEXT, Content TEXT);
+      CREATE TABLE PhraseHistory (
+        Id INTEGER PRIMARY KEY AUTOINCREMENT,
+        PhraseId INTEGER NOT NULL,
+        Timestamp BIGINT NOT NULL,
+        Latitude REAL,
+        Longitude REAL,
+        FOREIGN KEY(PhraseId) REFERENCES Phrases(Id)
+      );
+    `);
+
+    const missingId = db
+      .prepare('INSERT INTO Phrases (Text, Content) VALUES (?, ?)')
+      .run(null, null).lastInsertRowid as number;
+    const fallbackId = db
+      .prepare('INSERT INTO Phrases (Text, Content) VALUES (?, ?)')
+      .run('plain text only', '').lastInsertRowid as number;
+
+    const ts1 = dateToTicks(new Date('2024-04-04T00:00:00Z'));
+    const ts2 = dateToTicks(new Date('2024-04-04T00:01:00Z'));
+
+    db.prepare(
+      'INSERT INTO PhraseHistory (PhraseId, Timestamp, Latitude, Longitude) VALUES (?, ?, ?, ?)'
+    ).run(missingId, ts1, null, null);
+    db.prepare(
+      'INSERT INTO PhraseHistory (PhraseId, Timestamp, Latitude, Longitude) VALUES (?, ?, ?, ?)'
+    ).run(fallbackId, ts2, null, null);
+
+    const history = readGrid3History(dbPath);
+    expect(history).toHaveLength(1);
+    expect(history[0].content).toBe('plain text only');
+    expect(history[0].occurrences).toHaveLength(1);
+  });
+
   it('reads Snap usage from pageset sqlite', () => {
     const pagesetPath = path.join(tempDir, 'snap.sps');
     const db = new Database(pagesetPath);