@willwade/aac-processors 0.0.8 → 0.0.10

package/README.md

@@ -27,6 +27,7 @@ A comprehensive **TypeScript library** for processing AAC (Augmentative and Alte
 - 🌍 **Translation workflows** - Built-in i18n support with `processTexts()`
 - 🎨 **Comprehensive styling support** - Preserve visual appearance across formats
 - 🧪 **Property-based testing** - Robust validation with 140+ tests
+- ✅ **Format validation** - Spec-based validation for all supported formats
 - ⚡ **Performance optimized** - Memory-efficient processing of large files
 - 🛡️ **Error recovery** - Graceful handling of corrupted data
 - 🔒 **Thread-safe** - Concurrent processing support
@@ -58,6 +59,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)
@@ -160,6 +192,78 @@ const translatedBuffer = processor.processTexts(
 console.log("Translation complete!");
 ```
 
+### Format Validation
+
+Validate AAC files against format specifications to ensure data integrity:
+
+```typescript
+import { ObfProcessor, GridsetProcessor } from "aac-processors";
+
+// Validate OBF/OBZ files
+const obfProcessor = new ObfProcessor();
+const result = await obfProcessor.validate("board.obf");
+
+console.log(`Valid: ${result.valid}`);
+console.log(`Errors: ${result.errors}`);
+console.log(`Warnings: ${result.warnings}`);
+
+// Detailed validation results
+if (!result.valid) {
+  result.results
+    .filter((check) => !check.valid)
+    .forEach((check) => {
+      console.log(`✗ ${check.description}: ${check.error}`);
+    });
+}
+
+// Validate Gridset files (with optional password for encrypted files)
+const gridsetProcessor = new GridsetProcessor({
+  gridsetPassword: "optional-password",
+});
+const gridsetResult = await gridsetProcessor.validate("vocab.gridsetx");
+```
+
+#### Using the CLI
+
+```bash
+# Validate a file
+aacprocessors validate board.obf
+
+# JSON output
+aacprocessors validate board.obf --json
+
+# Quiet mode (just valid/invalid)
+aacprocessors validate board.gridset --quiet
+
+# Validate encrypted Gridset file
+aacprocessors validate board.gridsetx --gridset-password <password>
+```
+
+#### What Gets Validated?
+
+- **OBF/OBZ**: Spec compliance (Open Board Format)
+  - Required fields (format, id, locale, buttons, grid, images, sounds)
+  - Grid structure (rows, columns, order)
+  - Button references (image_id, sound_id, load_board paths)
+  - Color formats (RGB/RGBA)
+  - Cross-reference validation
+
+- **Gridset**: XML structure
+  - Required elements (gridset, pages, cells)
+  - FixedCellSize configuration
+  - Page and cell attributes
+  - Image references
+
+- **Snap**: Package structure
+  - ZIP package validity
+  - Settings file format
+  - Page/button configurations
+
+- **TouchChat**: XML structure
+  - PageSet hierarchy
+  - Button definitions
+  - Navigation links
+
 ### Cross-Format Conversion
 
 Convert between any supported AAC formats:
@@ -475,6 +579,7 @@ npx aac-processors analyze examples/example.gridset --pretty
 - `--pretty` - Human-readable output (analyze command)
 - `--verbose` - Detailed output (extract command)
 - `--quiet` - Minimal output (extract command)
+- `--gridset-password <password>` - Password for encrypted Grid 3 archives (`.gridsetx`)
 
 **Button Filtering Options:**
 
@@ -563,17 +668,17 @@ interface AACButton {
 
 ### Supported Processors
 
-| Processor               | File Extensions | Description                   |
-| ----------------------- | --------------- | ----------------------------- |
-| `DotProcessor`          | `.dot`          | Graphviz DOT format           |
-| `OpmlProcessor`         | `.opml`         | OPML hierarchical format      |
-| `ObfProcessor`          | `.obf`, `.obz`  | Open Board Format (JSON/ZIP)  |
-| `SnapProcessor`         | `.sps`, `.spb`  | Tobii Dynavox Snap format     |
-| `GridsetProcessor`      | `.gridset`      | Smartbox Grid 3 format        |
-| `TouchChatProcessor`    | `.ce`           | PRC-Saltillo TouchChat format |
-| `ApplePanelsProcessor`  | `.plist`        | iOS Apple Panels format       |
-| `AstericsGridProcessor` | `.grd`          | Asterics Grid native format   |
-| `ExcelProcessor`        | `.xlsx`         | Microsoft Excel format        |
+| Processor               | File Extensions         | Description                   |
+| ----------------------- | ----------------------- | ----------------------------- |
+| `DotProcessor`          | `.dot`                  | Graphviz DOT format           |
+| `OpmlProcessor`         | `.opml`                 | OPML hierarchical format      |
+| `ObfProcessor`          | `.obf`, `.obz`          | Open Board Format (JSON/ZIP)  |
+| `SnapProcessor`         | `.sps`, `.spb`          | Tobii Dynavox Snap format     |
+| `GridsetProcessor`      | `.gridset`, `.gridsetx` | Smartbox Grid 3 format        |
+| `TouchChatProcessor`    | `.ce`                   | PRC-Saltillo TouchChat format |
+| `ApplePanelsProcessor`  | `.plist`                | iOS Apple Panels format       |
+| `AstericsGridProcessor` | `.grd`                  | Asterics Grid native format   |
+| `ExcelProcessor`        | `.xlsx`                 | Microsoft Excel format        |
 
 ---
 

package/dist/cli/index.js

@@ -23,6 +23,9 @@ function detectFormat(filePath) {
 // Helper function to parse filtering options from CLI arguments
 function parseFilteringOptions(options) {
     const processorOptions = {};
+    if (options.gridsetPassword) {
+        processorOptions.gridsetPassword = options.gridsetPassword;
+    }
     // Handle preserve all buttons flag
     if (options.preserveAllButtons) {
         processorOptions.preserveAllButtons = true;
@@ -63,6 +66,7 @@ commander_1.program
     .option('--no-exclude-navigation', "Don't exclude navigation buttons (Home, Back)")
     .option('--no-exclude-system', "Don't exclude system buttons (Delete, Clear, etc.)")
     .option('--exclude-buttons <list>', 'Comma-separated list of button labels/terms to exclude')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
     .action((file, options) => {
     try {
         // Parse filtering options
@@ -97,6 +101,7 @@ commander_1.program
     .option('--no-exclude-navigation', "Don't exclude navigation buttons (Home, Back)")
     .option('--no-exclude-system', "Don't exclude system buttons (Delete, Clear, etc.)")
     .option('--exclude-buttons <list>', 'Comma-separated list of button labels/terms to exclude')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
     .action((file, options) => {
     try {
         // Parse filtering options
@@ -142,6 +147,7 @@ commander_1.program
     .option('--no-exclude-navigation', "Don't exclude navigation buttons (Home, Back)")
     .option('--no-exclude-system', "Don't exclude system buttons (Delete, Clear, etc.)")
     .option('--exclude-buttons <list>', 'Comma-separated list of button labels/terms to exclude')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
     .action(async (input, output, options) => {
     try {
         if (!options.format) {
@@ -182,6 +188,87 @@ commander_1.program
         process.exit(1);
     }
 });
+commander_1.program
+    .command('validate <file>')
+    .description('Validate an AAC file format')
+    .option('--format <format>', 'Format type (auto-detected if not specified)')
+    .option('--json', 'Output results as JSON')
+    .option('--quiet', 'Only output validation result (valid/invalid)')
+    .option('--gridset-password <password>', 'Password for encrypted Grid3 archives (.gridsetx)')
+    .action(async (file, options) => {
+    try {
+        // Auto-detect format if not specified
+        const format = options.format || detectFormat(file);
+        // Get processor with gridset password if provided
+        const processorOptions = {};
+        if (options.gridsetPassword) {
+            processorOptions.gridsetPassword = options.gridsetPassword;
+        }
+        const processor = (0, analyze_1.getProcessor)(format, processorOptions);
+        // Check if processor supports validation
+        if (!processor.validate) {
+            console.error(`Error: Validation not supported for format '${format}'`);
+            process.exit(1);
+        }
+        // Run validation
+        const result = await processor.validate(file);
+        // Output results
+        if (options.quiet) {
+            console.log(result.valid ? 'valid' : 'invalid');
+        }
+        else if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            // Pretty print validation results
+            console.log(`\nValidation Results for: ${result.filename}`);
+            console.log(`Format: ${result.format}`);
+            console.log(`File size: ${result.filesize} bytes`);
+            console.log(`Status: ${result.valid ? '✓ VALID' : '✗ INVALID'}`);
+            console.log(`Errors: ${result.errors}`);
+            console.log(`Warnings: ${result.warnings}\n`);
+            if (result.errors > 0 || result.warnings > 0) {
+                if (result.errors > 0) {
+                    console.log('Errors:');
+                    result.results
+                        .filter((r) => !r.valid)
+                        .forEach((check) => {
+                        console.log(`  ✗ ${check.description}`);
+                        if (check.error) {
+                            console.log(`    ${check.error}`);
+                        }
+                    });
+                }
+                if (result.warnings > 0) {
+                    console.log('\nWarnings:');
+                    result.results.forEach((check) => {
+                        if (check.warnings && check.warnings.length > 0) {
+                            console.log(`  ⚠ ${check.description}`);
+                            check.warnings.forEach((warning) => {
+                                console.log(`    ${warning}`);
+                            });
+                        }
+                    });
+                }
+            }
+            // Show sub-results if available
+            if (result.sub_results && result.sub_results.length > 0) {
+                console.log('\nSub-results:');
+                result.sub_results.forEach((sub, idx) => {
+                    console.log(`  [${idx + 1}] ${sub.filename}`);
+                    console.log(`      Status: ${sub.valid ? '✓' : '✗'} (${sub.errors} errors, ${sub.warnings} warnings)`);
+                });
+            }
+            console.log('');
+        }
+        // Exit with appropriate code
+        process.exit(result.valid ? 0 : 1);
+    }
+    catch (error) {
+        console.error('Error validating file:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
 // Show help if no command provided
 if (process.argv.length <= 2) {
     commander_1.program.help();

package/dist/core/analyze.js

@@ -27,6 +27,7 @@ function getProcessor(format, options) {
         case 'ce': // TouchChat file extension
             return new touchchatProcessor_1.TouchChatProcessor(options);
         case 'gridset':
+        case 'gridsetx':
             return new gridsetProcessor_1.GridsetProcessor(options); // Grid3 format
         case 'grd': // Asterics Grid file extension
             return new astericsGridProcessor_1.AstericsGridProcessor(options);

package/dist/core/baseProcessor.d.ts

@@ -1,8 +1,10 @@
 import { AACTree, AACButton } from './treeStructure';
 import { StringCasing } from './stringCasing';
+import { ValidationResult } from '../validation/validationTypes';
 export interface ProcessorOptions {
     excludeNavigationButtons?: boolean;
     excludeSystemButtons?: boolean;
+    gridsetPassword?: string;
     customButtonFilter?: (button: AACButton) => boolean;
     preserveAllButtons?: boolean;
 }
@@ -44,6 +46,7 @@ declare abstract class BaseProcessor {
     abstract loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;
     abstract processTexts(filePathOrBuffer: string | Buffer, translations: Map<string, string>, outputPath: string): Buffer;
     abstract saveFromTree(tree: AACTree, outputPath: string): void | Promise<void>;
+    validate?(filePath: string): Promise<ValidationResult>;
     /**
      * Extract strings with metadata for external platform integration
      * @param filePath - Path to the AAC file

package/dist/core/fileProcessor.js

@@ -20,6 +20,7 @@ class FileProcessor {
             const ext = path_1.default.extname(filePathOrBuffer).toLowerCase();
             switch (ext) {
                 case '.gridset':
+                case '.gridsetx':
                     return 'gridset';
                 case '.obf':
                 case '.obz':

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './core/baseProcessor';
 export * from './core/stringCasing';
 export * from './processors';
 export { collectUnifiedHistory, listGrid3Users as listHistoryGrid3Users, listSnapUsers as listHistorySnapUsers, } from './analytics/history';
+export * from './validation';
 import { BaseProcessor } from './core/baseProcessor';
 /**
  * Factory function to get the appropriate processor for a file extension

package/dist/index.js

@@ -27,6 +27,7 @@ var history_1 = require("./analytics/history");
 Object.defineProperty(exports, "collectUnifiedHistory", { enumerable: true, get: function () { return history_1.collectUnifiedHistory; } });
 Object.defineProperty(exports, "listHistoryGrid3Users", { enumerable: true, get: function () { return history_1.listGrid3Users; } });
 Object.defineProperty(exports, "listHistorySnapUsers", { enumerable: true, get: function () { return history_1.listSnapUsers; } });
+__exportStar(require("./validation"), exports);
 const dotProcessor_1 = require("./processors/dotProcessor");
 const excelProcessor_1 = require("./processors/excelProcessor");
 const opmlProcessor_1 = require("./processors/opmlProcessor");
@@ -58,6 +59,7 @@ function getProcessor(filePathOrExtension) {
         case '.obz':
             return new obfProcessor_1.ObfProcessor();
         case '.gridset':
+        case '.gridsetx':
             return new gridsetProcessor_1.GridsetProcessor();
         case '.spb':
         case '.sps':
@@ -84,6 +86,7 @@ function getSupportedExtensions() {
         '.obf',
         '.obz',
         '.gridset',
+        '.gridsetx',
         '.spb',
         '.sps',
         '.ce',

package/dist/optional/symbolTools.js

@@ -7,6 +7,7 @@ exports.TouchChatSymbolResolver = exports.TouchChatSymbolExtractor = exports.Gri
 exports.resolveSymbol = resolveSymbol;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
+const password_1 = require("../processors/gridset/password");
 // --- Base Classes ---
 class SymbolExtractor {
 }
@@ -76,8 +77,9 @@ class Grid3SymbolExtractor extends SymbolExtractor {
         const zip = new AdmZip(filePath);
         const parser = new XMLParser();
         const refs = new Set();
-        zip.getEntries().forEach((entry) => {
-            if (entry.entryName.endsWith('.gridset')) {
+        const entries = (0, password_1.getZipEntriesWithPassword)(zip, (0, password_1.resolveGridsetPasswordFromEnv)());
+        entries.forEach((entry) => {
+            if (entry.entryName.endsWith('.gridset') || entry.entryName.endsWith('.gridsetx')) {
                 const xmlBuffer = entry.getData();
                 // Parse to validate XML structure (future: extract refs)
                 parser.parse(xmlBuffer.toString('utf8'));

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

@@ -15,7 +15,7 @@ export declare function getAllowedImageEntries(tree: AACTree): Set<string>;
  * @param entryPath Entry name inside the zip
  * @returns Image data buffer or null if not found
  */
-export declare function openImage(gridsetBuffer: Buffer, entryPath: string): Buffer | null;
+export declare function openImage(gridsetBuffer: Buffer, entryPath: string, password?: string | undefined): Buffer | null;
 /**
  * Generate a random GUID for Grid3 elements
  * Grid3 uses GUIDs for grid identification
@@ -79,6 +79,8 @@ export declare 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 declare function findGrid3UserPaths(): Grid3UserPath[];

package/dist/processors/gridset/helpers.js

@@ -49,6 +49,7 @@ 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");
+const password_1 = require("./password");
 function normalizeZipPath(p) {
     const unified = p.replace(/\\/g, '/');
     try {
@@ -94,10 +95,11 @@ function getAllowedImageEntries(tree) {
  * @param entryPath Entry name inside the zip
  * @returns Image data buffer or null if not found
  */
-function openImage(gridsetBuffer, entryPath) {
+function openImage(gridsetBuffer, entryPath, password = (0, password_1.resolveGridsetPasswordFromEnv)()) {
     const zip = new adm_zip_1.default(gridsetBuffer);
+    const entries = (0, password_1.getZipEntriesWithPassword)(zip, password);
     const want = normalizeZipPath(entryPath);
-    const entry = zip.getEntries().find((e) => normalizeZipPath(e.entryName) === want);
+    const entry = entries.find((e) => normalizeZipPath(e.entryName) === want);
     if (!entry)
         return null;
     return entry.getData();
@@ -197,6 +199,8 @@ function getCommonDocumentsPath() {
  * 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() {
@@ -290,7 +294,7 @@ function findGrid3Vocabularies(userName) {
             if (!entry.isFile())
                 continue;
             const ext = path.extname(entry.name).toLowerCase();
-            if (ext === '.gridset' || ext === '.grd' || ext === '.grdl') {
+            if (ext === '.gridset' || ext === '.gridsetx' || ext === '.grd' || ext === '.grdl') {
                 results.push({
                     userName: userDir.name,
                     gridsetPath: path.win32.join(gridSetsDir, entry.name),
@@ -307,6 +311,8 @@ function findGrid3Vocabularies(userName) {
  * @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 &&
@@ -363,13 +369,26 @@ function readGrid3History(historyDbPath) {
     const events = new Map();
     for (const row of rows) {
         const phraseId = 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,
             };
         entry.occurrences.push({
             timestamp: (0, dotnetTicks_1.dotNetTicksToDate)(BigInt(row.TickValue ?? 0)),

package/dist/processors/gridset/password.d.ts

@@ -0,0 +1,11 @@
+import { ProcessorOptions } from '../../core/baseProcessor';
+import AdmZip from 'adm-zip';
+/**
+ * Resolve the password to use for Grid3 archives.
+ * Preference order:
+ * 1. Explicit processor option
+ * 2. GRIDSET_PASSWORD env var
+ */
+export declare function resolveGridsetPassword(options?: ProcessorOptions, source?: string | Buffer): string | undefined;
+export declare function resolveGridsetPasswordFromEnv(): string | undefined;
+export declare function getZipEntriesWithPassword(zip: AdmZip, password?: string): AdmZip.IZipEntry[];

package/dist/processors/gridset/password.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveGridsetPassword = resolveGridsetPassword;
+exports.resolveGridsetPasswordFromEnv = resolveGridsetPasswordFromEnv;
+exports.getZipEntriesWithPassword = getZipEntriesWithPassword;
+const path_1 = __importDefault(require("path"));
+/**
+ * Resolve the password to use for Grid3 archives.
+ * Preference order:
+ * 1. Explicit processor option
+ * 2. GRIDSET_PASSWORD env var
+ */
+function resolveGridsetPassword(options, source) {
+    if (options?.gridsetPassword)
+        return options.gridsetPassword;
+    if (process.env.GRIDSET_PASSWORD)
+        return process.env.GRIDSET_PASSWORD;
+    if (typeof source === 'string') {
+        const ext = path_1.default.extname(source).toLowerCase();
+        if (ext === '.gridsetx')
+            return process.env.GRIDSET_PASSWORD;
+    }
+    return undefined;
+}
+function resolveGridsetPasswordFromEnv() {
+    return process.env.GRIDSET_PASSWORD;
+}
+// Wrapper to set the password before reading entries (typed getEntries lacks the optional arg)
+function getZipEntriesWithPassword(zip, password) {
+    if (password) {
+        return zip.getEntries(password);
+    }
+    return zip.getEntries();
+}

package/dist/processors/gridset/resolver.d.ts

@@ -5,4 +5,4 @@ export declare function resolveGrid3CellImage(zip: any, args: {
     y?: number;
     dynamicFiles?: string[];
     builtinHandler?: (name: string) => string | null;
-}): string | null;
+}, zipEntries?: any[]): string | null;

package/dist/processors/gridset/resolver.js

@@ -10,9 +10,13 @@ function normalizeZipPathLocal(p) {
         return unified;
     }
 }
-function listZipEntries(zip) {
+function listZipEntries(zip, zipEntries) {
     try {
-        const raw = typeof zip?.getEntries === 'function' ? zip.getEntries() : [];
+        const raw = Array.isArray(zipEntries) && zipEntries.length > 0
+            ? zipEntries
+            : typeof zip?.getEntries === 'function'
+                ? zip.getEntries()
+                : [];
         let entries = [];
         if (Array.isArray(raw))
             entries = raw;
@@ -33,12 +37,12 @@ function joinBaseDir(baseDir, leaf) {
     const base = normalizeZipPathLocal(baseDir).replace(/\/?$/, '/');
     return normalizeZipPathLocal(base + leaf.replace(/^\//, ''));
 }
-function resolveGrid3CellImage(zip, args) {
+function resolveGrid3CellImage(zip, args, zipEntries) {
     const { baseDir, dynamicFiles } = args;
     const imageName = args.imageName?.trim();
     const x = args.x;
     const y = args.y;
-    const entries = new Set(listZipEntries(zip));
+    const entries = new Set(listZipEntries(zip, zipEntries));
     const has = (p) => entries.has(normalizeZipPathLocal(p));
     // Built-in resource like [grid3x]...
     if (imageName && imageName.startsWith('[')) {

package/dist/processors/gridset/wordlistHelpers.d.ts

@@ -64,7 +64,7 @@ export declare function wordlistToXml(wordlist: WordList): string;
  *   console.log(`Grid "${gridName}" has ${wordlist.items.length} items`);
  * });
  */
-export declare function extractWordlists(gridsetBuffer: Buffer): Map<string, WordList>;
+export declare function extractWordlists(gridsetBuffer: Buffer, password?: string | undefined): Map<string, WordList>;
 /**
  * Updates or adds a wordlist to a specific grid in a gridset
  *
@@ -79,4 +79,4 @@ export declare function extractWordlists(gridsetBuffer: Buffer): Map<string, Wor
  * const updatedGridset = updateWordlist(gridsetBuffer, 'Greetings', newWordlist);
  * fs.writeFileSync('updated-gridset.gridset', updatedGridset);
  */
-export declare function updateWordlist(gridsetBuffer: Buffer, gridName: string, wordlist: WordList): Buffer;
+export declare function updateWordlist(gridsetBuffer: Buffer, gridName: string, wordlist: WordList, password?: string | undefined): Buffer;

package/dist/processors/gridset/wordlistHelpers.js

@@ -19,6 +19,7 @@ exports.extractWordlists = extractWordlists;
 exports.updateWordlist = updateWordlist;
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const fast_xml_parser_1 = require("fast-xml-parser");
+const password_1 = require("./password");
 /**
  * Creates a WordList object from an array of words/phrases or a dictionary
  *
@@ -104,7 +105,7 @@ function wordlistToXml(wordlist) {
  *   console.log(`Grid "${gridName}" has ${wordlist.items.length} items`);
  * });
  */
-function extractWordlists(gridsetBuffer) {
+function extractWordlists(gridsetBuffer, password = (0, password_1.resolveGridsetPasswordFromEnv)()) {
     const wordlists = new Map();
     const parser = new fast_xml_parser_1.XMLParser();
     let zip;
@@ -114,8 +115,9 @@ function extractWordlists(gridsetBuffer) {
     catch (error) {
         throw new Error(`Invalid gridset buffer: ${error.message}`);
     }
+    const entries = (0, password_1.getZipEntriesWithPassword)(zip, password);
     // Process each grid file
-    zip.getEntries().forEach((entry) => {
+    entries.forEach((entry) => {
         if (entry.entryName.startsWith('Grids/') && entry.entryName.endsWith('grid.xml')) {
             try {
                 const xmlContent = entry.getData().toString('utf8');
@@ -169,7 +171,7 @@ function extractWordlists(gridsetBuffer) {
  * const updatedGridset = updateWordlist(gridsetBuffer, 'Greetings', newWordlist);
  * fs.writeFileSync('updated-gridset.gridset', updatedGridset);
  */
-function updateWordlist(gridsetBuffer, gridName, wordlist) {
+function updateWordlist(gridsetBuffer, gridName, wordlist, password = (0, password_1.resolveGridsetPasswordFromEnv)()) {
     const parser = new fast_xml_parser_1.XMLParser();
     const builder = new fast_xml_parser_1.XMLBuilder({
         ignoreAttributes: false,
@@ -184,9 +186,10 @@ function updateWordlist(gridsetBuffer, gridName, wordlist) {
     catch (error) {
         throw new Error(`Invalid gridset buffer: ${error.message}`);
     }
+    const entries = (0, password_1.getZipEntriesWithPassword)(zip, password);
     let found = false;
     // Find and update the grid
-    zip.getEntries().forEach((entry) => {
+    entries.forEach((entry) => {
         if (entry.entryName.startsWith('Grids/') && entry.entryName.endsWith('grid.xml')) {
             const match = entry.entryName.match(/^Grids\/([^/]+)\//);
             const currentGridName = match ? match[1] : null;

package/dist/processors/gridsetProcessor.d.ts

@@ -1,14 +1,22 @@
 import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
 import { AACTree } from '../core/treeStructure';
+import { ValidationResult } from '../validation/validationTypes';
 declare class GridsetProcessor extends BaseProcessor {
     constructor(options?: ProcessorOptions);
+    /**
+     * Decrypt and inflate a Grid3 encrypted payload (DesktopContentEncrypter).
+     * Uses AES-256-CBC with key/IV derived from the password padded with spaces
+     * and then Deflate decompression.
+     */
+    private decryptGridsetEntry;
+    private getGridsetPassword;
     private ensureAlphaChannel;
     private generateCommandsFromSemanticAction;
     private convertGrid3StyleToAACStyle;
     private getStyleById;
     private textOf;
     extractTexts(filePathOrBuffer: string | Buffer): string[];
-    loadIntoTree(filePathOrBuffer: Buffer): AACTree;
+    loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;
     processTexts(filePathOrBuffer: string | Buffer, translations: Map<string, string>, outputPath: string): Buffer;
     saveFromTree(tree: AACTree, outputPath: string): void;
     private calculateColumnDefinitions;
@@ -24,5 +32,11 @@ declare class GridsetProcessor extends BaseProcessor {
      * Uses the generic implementation from BaseProcessor
      */
     generateTranslatedDownload(filePath: string, translatedStrings: TranslatedString[], sourceStrings: SourceString[]): Promise<string>;
+    /**
+     * Validate Gridset file format
+     * @param filePath - Path to the file to validate
+     * @returns Promise with validation result
+     */
+    validate(filePath: string): Promise<ValidationResult>;
 }
 export { GridsetProcessor };