@willwade/aac-processors 0.1.18 → 0.1.20

package/dist/browser/index.browser.js

@@ -48,29 +48,29 @@ export { configureSqlJs } from './utils/sqlite';
  * @returns The appropriate processor instance
  * @throws Error if the file extension is not supported
  */
-export function getProcessor(filePathOrExtension) {
+export function getProcessor(filePathOrExtension, options) {
     const extension = filePathOrExtension.includes('.')
         ? filePathOrExtension.substring(filePathOrExtension.lastIndexOf('.'))
         : filePathOrExtension;
     switch (extension.toLowerCase()) {
         case '.dot':
-            return new DotProcessor();
+            return new DotProcessor(options);
         case '.opml':
-            return new OpmlProcessor();
+            return new OpmlProcessor(options);
         case '.obf':
         case '.obz':
-            return new ObfProcessor();
+            return new ObfProcessor(options);
         case '.gridset':
-            return new GridsetProcessor();
+            return new GridsetProcessor(options);
         case '.spb':
         case '.sps':
-            return new SnapProcessor();
+            return new SnapProcessor(options);
         case '.ce':
-            return new TouchChatProcessor();
+            return new TouchChatProcessor(options);
         case '.plist':
-            return new ApplePanelsProcessor();
+            return new ApplePanelsProcessor(options);
         case '.grd':
-            return new AstericsGridProcessor();
+            return new AstericsGridProcessor(options);
         default:
             throw new Error(`Unsupported file extension: ${extension}`);
     }

package/dist/browser/processors/gridset/helpers.js

@@ -52,9 +52,11 @@ export function getAllowedImageEntries(tree) {
  * @param entryPath Entry name inside the zip
  * @returns Image data buffer or null if not found
  */
-export async function openImage(gridsetBuffer, entryPath, password = resolveGridsetPasswordFromEnv()) {
+export async function openImage(gridsetBuffer, entryPath, password = resolveGridsetPasswordFromEnv(), zipAdapter) {
     try {
-        const { zip } = await openZipFromInput(gridsetBuffer);
+        const { zip } = zipAdapter
+            ? await zipAdapter(gridsetBuffer)
+            : await openZipFromInput(gridsetBuffer);
         const entries = getZipEntriesFromAdapter(zip, password);
         const want = normalizeZipPath(entryPath);
         const entry = entries.find((e) => normalizeZipPath(e.entryName) === want);

package/dist/browser/processors/gridsetProcessor.js

@@ -398,7 +398,10 @@ class GridsetProcessor extends BaseProcessor {
         const tree = new AACTree();
         let zipResult;
         try {
-            zipResult = await openZipFromInput(readBinaryFromInput(filePathOrBuffer));
+            const zipInput = readBinaryFromInput(filePathOrBuffer);
+            zipResult = this.options.zipAdapter
+                ? await this.options.zipAdapter(zipInput)
+                : await openZipFromInput(zipInput);
         }
         catch (error) {
             throw new Error(`Invalid ZIP file format: ${error.message}`);

package/dist/browser/processors/obfProcessor.js

@@ -120,13 +120,9 @@ class ObfProcessor extends BaseProcessor {
                 return 'image/png';
         }
     }
-    async processBoard(boardData, _boardPath) {
+    async processBoard(boardData, _boardPath, isZipEntry) {
         const sourceButtons = boardData.buttons || [];
         // Calculate page ID first (used to make button IDs unique)
-        const isZipEntry = _boardPath &&
-            _boardPath.endsWith('.obf') &&
-            !_boardPath.includes('/') &&
-            !_boardPath.includes('\\');
         const pageId = isZipEntry
             ? _boardPath // Zip entry - use filename to match navigation paths
             : boardData?.id
@@ -328,7 +324,7 @@ class ObfProcessor extends BaseProcessor {
                 const boardData = tryParseObfJson(content);
                 if (boardData) {
                     console.log('[OBF] Detected .obf file, parsed as JSON');
-                    const page = await this.processBoard(boardData, filePathOrBuffer);
+                    const page = await this.processBoard(boardData, filePathOrBuffer, false);
                     tree.addPage(page);
                     // Set metadata from root board
                     tree.metadata.format = 'obf';
@@ -352,11 +348,22 @@ class ObfProcessor extends BaseProcessor {
                 throw err;
             }
         }
-        // If input is a buffer or string that parses as OBF JSON
-        const asJson = tryParseObfJson(filePathOrBuffer);
-        if (asJson) {
+        // Detect likely zip signature first
+        function isLikelyZip(input) {
+            if (typeof input === 'string') {
+                const lowered = input.toLowerCase();
+                return lowered.endsWith('.zip') || lowered.endsWith('.obz');
+            }
+            const bytes = readBinaryFromInput(input);
+            return bytes.length >= 2 && bytes[0] === 0x50 && bytes[1] === 0x4b;
+        }
+        // Check if input is a buffer or string that parses as OBF JSON; throw if neither JSON nor ZIP
+        if (!isLikelyZip(filePathOrBuffer)) {
+            const asJson = tryParseObfJson(filePathOrBuffer);
+            if (!asJson)
+                throw new Error('Invalid OBF content: not JSON and not ZIP');
             console.log('[OBF] Detected buffer/string as OBF JSON');
-            const page = await this.processBoard(asJson, '[bufferOrString]');
+            const page = await this.processBoard(asJson, '[bufferOrString]', false);
             tree.addPage(page);
             // Set metadata from root board
             tree.metadata.format = 'obf';
@@ -372,20 +379,10 @@ class ObfProcessor extends BaseProcessor {
             tree.rootId = page.id;
             return tree;
         }
-        // Otherwise, try as ZIP (.obz). Detect likely zip signature first; throw if neither JSON nor ZIP
-        function isLikelyZip(input) {
-            if (typeof input === 'string') {
-                const lowered = input.toLowerCase();
-                return lowered.endsWith('.zip') || lowered.endsWith('.obz');
-            }
-            const bytes = readBinaryFromInput(input);
-            return bytes.length >= 2 && bytes[0] === 0x50 && bytes[1] === 0x4b;
-        }
-        if (!isLikelyZip(filePathOrBuffer)) {
-            throw new Error('Invalid OBF content: not JSON and not ZIP');
-        }
         try {
-            const zipResult = await openZipFromInput(filePathOrBuffer);
+            const zipResult = this.options.zipAdapter
+                ? await this.options.zipAdapter(filePathOrBuffer)
+                : await openZipFromInput(filePathOrBuffer);
             this.zipFile = zipResult.zip;
         }
         catch (err) {
@@ -395,17 +392,42 @@ class ObfProcessor extends BaseProcessor {
         // Store the ZIP file reference for image extraction
         this.imageCache.clear(); // Clear cache for new file
         console.log('[OBF] Detected zip archive, extracting .obf files');
-        // Collect all .obf entries
-        const obfEntries = this.zipFile
-            .listFiles()
-            .filter((name) => name.toLowerCase().endsWith('.obf'));
+        // List manifest and OBF files
+        const filesInZip = this.zipFile.listFiles();
+        const manifestFile = filesInZip.filter((name) => name.toLowerCase() === 'manifest.json');
+        let obfEntries = filesInZip.filter((name) => name.toLowerCase().endsWith('.obf'));
+        // Attempt to read manifest
+        if (manifestFile && manifestFile.length === 1) {
+            try {
+                const content = await this.zipFile.readFile(manifestFile[0]);
+                const data = decodeText(content);
+                const str = typeof data === 'string' ? data : readTextFromInput(data);
+                if (!str.trim())
+                    throw new Error('Manifest object missing');
+                const manifestObject = JSON.parse(str);
+                if (!manifestObject)
+                    throw new Error('Manifest object is empty');
+                // Replace OBF file list
+                if (manifestObject.paths && manifestObject.paths.boards) {
+                    obfEntries = Object.values(manifestObject.paths.boards);
+                }
+                // Move root board to top of list
+                if (manifestObject.root) {
+                    obfEntries = obfEntries.filter((item) => item !== manifestObject.root);
+                    obfEntries.unshift(manifestObject.root);
+                }
+            }
+            catch (err) {
+                console.warn('[OBF] Error processing mainfest', err);
+            }
+        }
         // Process each .obf entry
         for (const entryName of obfEntries) {
             try {
                 const content = await this.zipFile.readFile(entryName);
                 const boardData = tryParseObfJson(decodeText(content));
                 if (boardData) {
-                    const page = await this.processBoard(boardData, entryName);
+                    const page = await this.processBoard(boardData, entryName, true);
                     tree.addPage(page);
                     // Set metadata if not already set (use first board as reference)
                     if (!tree.metadata.format) {

package/dist/browser/processors/snapProcessor.js

@@ -2,8 +2,28 @@ import { BaseProcessor, } from '../core/baseProcessor';
 import { AACTree, AACPage, AACButton, AACSemanticCategory, AACSemanticIntent, } from '../core/treeStructure';
 import { generateCloneId } from '../utilities/analytics/utils/idGenerator';
 import { SnapValidator } from '../validation/snapValidator';
-import { getFs, getNodeRequire, getPath, isNodeRuntime } from '../utils/io';
+import { getFs, getNodeRequire, getPath, isNodeRuntime, getOs } from '../utils/io';
 import { openSqliteDatabase, requireBetterSqlite3 } from '../utils/sqlite';
+import { openZipFromInput } from '../utils/zip';
+/**
+ * Convert a Buffer or Uint8Array to base64 string (browser and Node compatible)
+ * Node.js Buffers support toString('base64'), but Uint8Arrays in browser do not.
+ * This function works in both environments.
+ */
+function arrayBufferToBase64(data) {
+    // Node.js environment - Buffer has built-in base64 encoding
+    if (typeof Buffer !== 'undefined' && data instanceof Buffer) {
+        return data.toString('base64');
+    }
+    // Browser environment - use btoa with binary string conversion
+    const bytes = new Uint8Array(data);
+    let binary = '';
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
 /**
  * Map Snap Visible value to AAC standard visibility
  * Snap: 0 = hidden, 1 (or non-zero) = visible
@@ -48,8 +68,37 @@ class SnapProcessor extends BaseProcessor {
         await Promise.resolve();
         const tree = new AACTree();
         let dbResult = null;
+        let cleanupTempZip = null;
         try {
-            dbResult = await openSqliteDatabase(filePathOrBuffer, { readonly: true });
+            // Handle .sub.zip files (Snap pageset backups containing .sps files)
+            let inputFile = filePathOrBuffer;
+            if (typeof filePathOrBuffer === 'string') {
+                const fileName = getPath().basename(filePathOrBuffer).toLowerCase();
+                if (fileName.endsWith('.sub.zip') || filePathOrBuffer.endsWith('.sub')) {
+                    const fs = getFs();
+                    const path = getPath();
+                    const os = getOs();
+                    // Extract .sub.zip to find the embedded .sps file
+                    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'snap-sub-'));
+                    const { zip } = await openZipFromInput(filePathOrBuffer);
+                    // Find the .sps file in the archive
+                    const files = zip.listFiles();
+                    const spsFile = files.find((f) => f.endsWith('.sps'));
+                    if (!spsFile) {
+                        fs.rmSync(tempDir, { recursive: true, force: true });
+                        throw new Error('No .sps file found in .sub.zip archive');
+                    }
+                    // Extract the .sps file
+                    const spsData = await zip.readFile(spsFile);
+                    const extractedSpsPath = path.join(tempDir, path.basename(spsFile));
+                    fs.writeFileSync(extractedSpsPath, Buffer.from(spsData));
+                    inputFile = extractedSpsPath;
+                    cleanupTempZip = () => {
+                        fs.rmSync(tempDir, { recursive: true, force: true });
+                    };
+                }
+            }
+            dbResult = await openSqliteDatabase(inputFile, { readonly: true });
             const db = dbResult.db;
             const getTableColumns = (tableName) => {
                 try {
@@ -445,7 +494,7 @@ class SnapProcessor extends BaseProcessor {
                                 if (isPng || isJpeg) {
                                     // Actual PNG/JPEG image - can be displayed
                                     const mimeType = isPng ? 'image/png' : 'image/jpeg';
-                                    const base64 = data.toString('base64');
+                                    const base64 = arrayBufferToBase64(data);
                                     buttonImage = `data:${mimeType};base64,${base64}`;
                                     buttonParameters.image_id = imageData.Identifier;
                                 }
@@ -639,6 +688,15 @@ class SnapProcessor extends BaseProcessor {
             else if (dbResult?.db) {
                 dbResult.db.close();
             }
+            // Clean up temporary extracted .sps file from .sub.zip
+            if (cleanupTempZip) {
+                try {
+                    cleanupTempZip();
+                }
+                catch (e) {
+                    console.warn('[SnapProcessor] Failed to clean up temporary .sps file:', e);
+                }
+            }
         }
     }
     async processTexts(filePathOrBuffer, translations, outputPath) {

package/dist/browser/processors/touchchatProcessor.js

@@ -64,7 +64,9 @@ class TouchChatProcessor extends BaseProcessor {
             this.sourceFile = filePathOrBuffer;
             // Step 1: Unzip
             const zipInput = readBinaryFromInput(filePathOrBuffer);
-            const { zip } = await openZipFromInput(zipInput);
+            const { zip } = this.options.zipAdapter
+                ? await this.options.zipAdapter(zipInput)
+                : await openZipFromInput(zipInput);
             const vocabEntry = zip.listFiles().find((name) => name.endsWith('.c4v'));
             if (!vocabEntry) {
                 throw new Error('No .c4v vocab DB found in TouchChat export');

package/dist/browser/validation/touchChatValidator.js

@@ -3,7 +3,7 @@
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 import * as xml2js from 'xml2js';
 import { BaseValidator } from './baseValidator';
-import { decodeText, getBasename, getFs, readBinaryFromInput, toUint8Array } from '../utils/io';
+import { decodeText, getBasename, getFs, readBinaryFromInput, toUint8Array, } from '../utils/io';
 import { openZipFromInput } from '../utils/zip';
 import { openSqliteDatabase } from '../utils/sqlite';
 /**
@@ -27,14 +27,14 @@ export class TouchChatValidator extends BaseValidator {
     /**
      * Check if content is TouchChat format
      */
-    static async identifyFormat(content, filename) {
+    static async identifyFormat(content, filename, zipAdapter) {
         const name = filename.toLowerCase();
         if (name.endsWith('.ce')) {
             return true;
         }
         // Try to parse as ZIP and check for .c4v database
         try {
-            const { zip } = await openZipFromInput(content);
+            const { zip } = zipAdapter ? await zipAdapter(content) : await openZipFromInput(content);
             const entries = zip.listFiles();
             if (entries.some((entry) => entry.toLowerCase().endsWith('.c4v'))) {
                 return true;

package/dist/core/baseProcessor.d.ts

@@ -43,6 +43,7 @@ import { AACTree, AACButton } from './treeStructure';
 import { StringCasing } from './stringCasing';
 import { ValidationResult } from '../validation/validationTypes';
 import { BinaryOutput, ProcessorInput } from '../utils/io';
+import type { ZipAdapter } from '../utils/zip';
 export interface ProcessorOptions {
     excludeNavigationButtons?: boolean;
     excludeSystemButtons?: boolean;
@@ -52,6 +53,9 @@ export interface ProcessorOptions {
     grid3SymbolDir?: string;
     grid3Path?: string;
     grid3Locale?: string;
+    zipAdapter?: (input: ProcessorInput) => Promise<{
+        zip: ZipAdapter;
+    }>;
 }
 export interface ExtractedString {
     string: string;

package/dist/core/fileProcessor.js

@@ -18,6 +18,11 @@ class FileProcessor {
     static detectFormat(filePathOrBuffer) {
         if (typeof filePathOrBuffer === 'string') {
             const ext = path_1.default.extname(filePathOrBuffer).toLowerCase();
+            const fileName = path_1.default.basename(filePathOrBuffer).toLowerCase();
+            // Handle double extensions like .sub.zip
+            if (fileName.endsWith('.sub.zip') || ext === '.sub') {
+                return 'snap';
+            }
             switch (ext) {
                 case '.gridset':
                 case '.gridsetx':

package/dist/index.browser.d.ts

@@ -23,7 +23,7 @@ export { TouchChatProcessor } from './processors/touchchatProcessor';
 export { ApplePanelsProcessor } from './processors/applePanelsProcessor';
 export { AstericsGridProcessor } from './processors/astericsGridProcessor';
 export * as Metrics from './metrics';
-import { BaseProcessor } from './core/baseProcessor';
+import { BaseProcessor, ProcessorOptions } from './core/baseProcessor';
 export { configureSqlJs } from './utils/sqlite';
 /**
  * Factory function to get the appropriate processor for a file extension
@@ -31,7 +31,7 @@ export { configureSqlJs } from './utils/sqlite';
  * @returns The appropriate processor instance
  * @throws Error if the file extension is not supported
  */
-export declare function getProcessor(filePathOrExtension: string): BaseProcessor;
+export declare function getProcessor(filePathOrExtension: string, options?: ProcessorOptions): BaseProcessor;
 /**
  * Get all supported file extensions
  * @returns Array of supported file extensions

package/dist/index.browser.js

@@ -89,29 +89,29 @@ Object.defineProperty(exports, "configureSqlJs", { enumerable: true, get: functi
  * @returns The appropriate processor instance
  * @throws Error if the file extension is not supported
  */
-function getProcessor(filePathOrExtension) {
+function getProcessor(filePathOrExtension, options) {
     const extension = filePathOrExtension.includes('.')
         ? filePathOrExtension.substring(filePathOrExtension.lastIndexOf('.'))
         : filePathOrExtension;
     switch (extension.toLowerCase()) {
         case '.dot':
-            return new dotProcessor_2.DotProcessor();
+            return new dotProcessor_2.DotProcessor(options);
         case '.opml':
-            return new opmlProcessor_2.OpmlProcessor();
+            return new opmlProcessor_2.OpmlProcessor(options);
         case '.obf':
         case '.obz':
-            return new obfProcessor_2.ObfProcessor();
+            return new obfProcessor_2.ObfProcessor(options);
         case '.gridset':
-            return new gridsetProcessor_2.GridsetProcessor();
+            return new gridsetProcessor_2.GridsetProcessor(options);
         case '.spb':
         case '.sps':
-            return new snapProcessor_2.SnapProcessor();
+            return new snapProcessor_2.SnapProcessor(options);
         case '.ce':
-            return new touchchatProcessor_2.TouchChatProcessor();
+            return new touchchatProcessor_2.TouchChatProcessor(options);
         case '.plist':
-            return new applePanelsProcessor_2.ApplePanelsProcessor();
+            return new applePanelsProcessor_2.ApplePanelsProcessor(options);
         case '.grd':
-            return new astericsGridProcessor_2.AstericsGridProcessor();
+            return new astericsGridProcessor_2.AstericsGridProcessor(options);
         default:
             throw new Error(`Unsupported file extension: ${extension}`);
     }

package/dist/index.node.d.ts

@@ -23,7 +23,7 @@ export * as Opml from './opml';
 export * as ApplePanels from './applePanels';
 export * as AstericsGrid from './astericsGrid';
 export * as Translation from './translation';
-import { BaseProcessor } from './core/baseProcessor';
+import { BaseProcessor, ProcessorOptions } from './core/baseProcessor';
 /**
  * Factory function to get the appropriate processor for a file extension
  * @param filePathOrExtension - File path or extension (e.g., '.dot', '/path/to/file.obf')
@@ -34,7 +34,7 @@ import { BaseProcessor } from './core/baseProcessor';
  * const processor = getProcessor('/path/to/file.gridset');
  * const tree = processor.loadIntoTree('/path/to/file.gridset');
  */
-export declare function getProcessor(filePathOrExtension: string): BaseProcessor;
+export declare function getProcessor(filePathOrExtension: string, options?: ProcessorOptions): BaseProcessor;
 /**
  * Get all supported file extensions
  * @returns Array of supported file extensions

package/dist/index.node.js

@@ -88,35 +88,35 @@ const obfsetProcessor_1 = require("./processors/obfsetProcessor");
  * const processor = getProcessor('/path/to/file.gridset');
  * const tree = processor.loadIntoTree('/path/to/file.gridset');
  */
-function getProcessor(filePathOrExtension) {
+function getProcessor(filePathOrExtension, options) {
     // Extract extension from file path
     const extension = filePathOrExtension.includes('.')
         ? filePathOrExtension.substring(filePathOrExtension.lastIndexOf('.'))
         : filePathOrExtension;
     switch (extension.toLowerCase()) {
         case '.dot':
-            return new dotProcessor_1.DotProcessor();
+            return new dotProcessor_1.DotProcessor(options);
         case '.xlsx':
-            return new excelProcessor_1.ExcelProcessor();
+            return new excelProcessor_1.ExcelProcessor(options);
         case '.opml':
-            return new opmlProcessor_1.OpmlProcessor();
+            return new opmlProcessor_1.OpmlProcessor(options);
         case '.obf':
         case '.obz':
-            return new obfProcessor_1.ObfProcessor();
+            return new obfProcessor_1.ObfProcessor(options);
         case '.obfset':
-            return new obfsetProcessor_1.ObfsetProcessor();
+            return new obfsetProcessor_1.ObfsetProcessor(options);
         case '.gridset':
         case '.gridsetx':
-            return new gridsetProcessor_1.GridsetProcessor();
+            return new gridsetProcessor_1.GridsetProcessor(options);
         case '.spb':
         case '.sps':
-            return new snapProcessor_1.SnapProcessor();
+            return new snapProcessor_1.SnapProcessor(options);
         case '.ce':
-            return new touchchatProcessor_1.TouchChatProcessor();
+            return new touchchatProcessor_1.TouchChatProcessor(options);
         case '.plist':
-            return new applePanelsProcessor_1.ApplePanelsProcessor();
+            return new applePanelsProcessor_1.ApplePanelsProcessor(options);
         case '.grd':
-            return new astericsGridProcessor_1.AstericsGridProcessor();
+            return new astericsGridProcessor_1.AstericsGridProcessor(options);
         default:
             throw new Error(`Unsupported file extension: ${extension}`);
     }

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

@@ -1,4 +1,6 @@
 import { AACTree, AACSemanticCategory, AACSemanticIntent } from '../../core/treeStructure';
+import { type ZipAdapter } from '../../utils/zip';
+import type { ProcessorInput } from '../../utils/io';
 /**
  * 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.
@@ -15,7 +17,9 @@ 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: Uint8Array, entryPath: string, password?: string | undefined): Promise<Uint8Array | null>;
+export declare function openImage(gridsetBuffer: Uint8Array, entryPath: string, password?: string | undefined, zipAdapter?: (input: ProcessorInput) => Promise<{
+    zip: ZipAdapter;
+}>): Promise<Uint8Array | null>;
 /**
  * Generate a random GUID for Grid3 elements
  * Grid3 uses GUIDs for grid identification

package/dist/processors/gridset/helpers.js

@@ -96,9 +96,11 @@ function getAllowedImageEntries(tree) {
  * @param entryPath Entry name inside the zip
  * @returns Image data buffer or null if not found
  */
-async function openImage(gridsetBuffer, entryPath, password = (0, password_1.resolveGridsetPasswordFromEnv)()) {
+async function openImage(gridsetBuffer, entryPath, password = (0, password_1.resolveGridsetPasswordFromEnv)(), zipAdapter) {
     try {
-        const { zip } = await (0, zip_1.openZipFromInput)(gridsetBuffer);
+        const { zip } = zipAdapter
+            ? await zipAdapter(gridsetBuffer)
+            : await (0, zip_1.openZipFromInput)(gridsetBuffer);
         const entries = (0, password_1.getZipEntriesFromAdapter)(zip, password);
         const want = normalizeZipPath(entryPath);
         const entry = entries.find((e) => normalizeZipPath(e.entryName) === want);

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

@@ -4,6 +4,8 @@
  * These utilities help developers understand why images might not be resolving
  * correctly in Grid3 gridsets.
  */
+import { type ZipAdapter } from '../../utils/zip';
+import { type ProcessorInput } from '../../utils/io';
 export interface ImageIssue {
     gridName: string;
     cellX: number;
@@ -34,7 +36,9 @@ export interface ImageAuditResult {
  *   console.log(`Cell (${issue.cellX}, ${issue.cellY}): ${issue.suggestion}`);
  * });
  */
-export declare function auditGridsetImages(gridsetBuffer: Uint8Array, password?: string | undefined): Promise<ImageAuditResult>;
+export declare function auditGridsetImages(gridsetBuffer: Uint8Array, password?: string | undefined, zipAdapter?: (input: ProcessorInput) => Promise<{
+    zip: ZipAdapter;
+}>): Promise<ImageAuditResult>;
 /**
  * Get a human-readable summary of image audit results
  */

package/dist/processors/gridset/imageDebug.js

@@ -26,7 +26,7 @@ const io_1 = require("../../utils/io");
  *   console.log(`Cell (${issue.cellX}, ${issue.cellY}): ${issue.suggestion}`);
  * });
  */
-async function auditGridsetImages(gridsetBuffer, password = (0, password_2.resolveGridsetPasswordFromEnv)()) {
+async function auditGridsetImages(gridsetBuffer, password = (0, password_2.resolveGridsetPasswordFromEnv)(), zipAdapter) {
     const issues = [];
     const availableImages = new Set();
     let totalCells = 0;
@@ -34,7 +34,9 @@ async function auditGridsetImages(gridsetBuffer, password = (0, password_2.resol
     let resolvedImages = 0;
     let unresolvedImages = 0;
     try {
-        const { zip } = await (0, zip_1.openZipFromInput)(gridsetBuffer);
+        const { zip } = zipAdapter
+            ? await zipAdapter(gridsetBuffer)
+            : await (0, zip_1.openZipFromInput)(gridsetBuffer);
         const entries = (0, password_1.getZipEntriesFromAdapter)(zip, password);
         const parser = new fast_xml_parser_1.XMLParser();
         // Collect all image files in the gridset

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

@@ -8,6 +8,8 @@
  * Note: Wordlists are only supported in Grid3 format. Other AAC formats
  * do not have equivalent wordlist functionality.
  */
+import { type ZipAdapter } from '../../utils/zip';
+import { type ProcessorInput } from '../../utils/io';
 /**
  * Represents a single item in a wordlist
  */
@@ -64,7 +66,9 @@ export declare function wordlistToXml(wordlist: WordList): string;
  *   console.log(`Grid "${gridName}" has ${wordlist.items.length} items`);
  * });
  */
-export declare function extractWordlists(gridsetBuffer: Uint8Array, password?: string | undefined): Promise<Map<string, WordList>>;
+export declare function extractWordlists(gridsetBuffer: Uint8Array, password?: string | undefined, zipAdapter?: (input: ProcessorInput) => Promise<{
+    zip: ZipAdapter;
+}>): Promise<Map<string, WordList>>;
 /**
  * Updates or adds a wordlist to a specific grid in a gridset
  *

package/dist/processors/gridset/wordlistHelpers.js

@@ -127,11 +127,13 @@ function wordlistToXml(wordlist) {
  *   console.log(`Grid "${gridName}" has ${wordlist.items.length} items`);
  * });
  */
-async function extractWordlists(gridsetBuffer, password = (0, password_1.resolveGridsetPasswordFromEnv)()) {
+async function extractWordlists(gridsetBuffer, password = (0, password_1.resolveGridsetPasswordFromEnv)(), zipAdapter) {
     const wordlists = new Map();
     const parser = new fast_xml_parser_1.XMLParser();
     try {
-        const { zip } = await (0, zip_1.openZipFromInput)(gridsetBuffer);
+        const { zip } = zipAdapter
+            ? await zipAdapter(gridsetBuffer)
+            : await (0, zip_1.openZipFromInput)(gridsetBuffer);
         const entries = (0, password_1.getZipEntriesFromAdapter)(zip, password);
         // Process each grid file
         for (const entry of entries) {

package/dist/processors/gridsetProcessor.js

@@ -424,7 +424,10 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         const tree = new treeStructure_1.AACTree();
         let zipResult;
         try {
-            zipResult = await (0, zip_1.openZipFromInput)((0, io_1.readBinaryFromInput)(filePathOrBuffer));
+            const zipInput = (0, io_1.readBinaryFromInput)(filePathOrBuffer);
+            zipResult = this.options.zipAdapter
+                ? await this.options.zipAdapter(zipInput)
+                : await (0, zip_1.openZipFromInput)(zipInput);
         }
         catch (error) {
             throw new Error(`Invalid ZIP file format: ${error.message}`);

package/dist/processors/obfProcessor.js

@@ -146,13 +146,9 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 return 'image/png';
         }
     }
-    async processBoard(boardData, _boardPath) {
+    async processBoard(boardData, _boardPath, isZipEntry) {
         const sourceButtons = boardData.buttons || [];
         // Calculate page ID first (used to make button IDs unique)
-        const isZipEntry = _boardPath &&
-            _boardPath.endsWith('.obf') &&
-            !_boardPath.includes('/') &&
-            !_boardPath.includes('\\');
         const pageId = isZipEntry
             ? _boardPath // Zip entry - use filename to match navigation paths
             : boardData?.id
@@ -354,7 +350,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 const boardData = tryParseObfJson(content);
                 if (boardData) {
                     console.log('[OBF] Detected .obf file, parsed as JSON');
-                    const page = await this.processBoard(boardData, filePathOrBuffer);
+                    const page = await this.processBoard(boardData, filePathOrBuffer, false);
                     tree.addPage(page);
                     // Set metadata from root board
                     tree.metadata.format = 'obf';
@@ -378,11 +374,22 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 throw err;
             }
         }
-        // If input is a buffer or string that parses as OBF JSON
-        const asJson = tryParseObfJson(filePathOrBuffer);
-        if (asJson) {
+        // Detect likely zip signature first
+        function isLikelyZip(input) {
+            if (typeof input === 'string') {
+                const lowered = input.toLowerCase();
+                return lowered.endsWith('.zip') || lowered.endsWith('.obz');
+            }
+            const bytes = (0, io_1.readBinaryFromInput)(input);
+            return bytes.length >= 2 && bytes[0] === 0x50 && bytes[1] === 0x4b;
+        }
+        // Check if input is a buffer or string that parses as OBF JSON; throw if neither JSON nor ZIP
+        if (!isLikelyZip(filePathOrBuffer)) {
+            const asJson = tryParseObfJson(filePathOrBuffer);
+            if (!asJson)
+                throw new Error('Invalid OBF content: not JSON and not ZIP');
             console.log('[OBF] Detected buffer/string as OBF JSON');
-            const page = await this.processBoard(asJson, '[bufferOrString]');
+            const page = await this.processBoard(asJson, '[bufferOrString]', false);
             tree.addPage(page);
             // Set metadata from root board
             tree.metadata.format = 'obf';
@@ -398,20 +405,10 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
             tree.rootId = page.id;
             return tree;
         }
-        // Otherwise, try as ZIP (.obz). Detect likely zip signature first; throw if neither JSON nor ZIP
-        function isLikelyZip(input) {
-            if (typeof input === 'string') {
-                const lowered = input.toLowerCase();
-                return lowered.endsWith('.zip') || lowered.endsWith('.obz');
-            }
-            const bytes = (0, io_1.readBinaryFromInput)(input);
-            return bytes.length >= 2 && bytes[0] === 0x50 && bytes[1] === 0x4b;
-        }
-        if (!isLikelyZip(filePathOrBuffer)) {
-            throw new Error('Invalid OBF content: not JSON and not ZIP');
-        }
         try {
-            const zipResult = await (0, zip_1.openZipFromInput)(filePathOrBuffer);
+            const zipResult = this.options.zipAdapter
+                ? await this.options.zipAdapter(filePathOrBuffer)
+                : await (0, zip_1.openZipFromInput)(filePathOrBuffer);
             this.zipFile = zipResult.zip;
         }
         catch (err) {
@@ -421,17 +418,42 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
         // Store the ZIP file reference for image extraction
         this.imageCache.clear(); // Clear cache for new file
         console.log('[OBF] Detected zip archive, extracting .obf files');
-        // Collect all .obf entries
-        const obfEntries = this.zipFile
-            .listFiles()
-            .filter((name) => name.toLowerCase().endsWith('.obf'));
+        // List manifest and OBF files
+        const filesInZip = this.zipFile.listFiles();
+        const manifestFile = filesInZip.filter((name) => name.toLowerCase() === 'manifest.json');
+        let obfEntries = filesInZip.filter((name) => name.toLowerCase().endsWith('.obf'));
+        // Attempt to read manifest
+        if (manifestFile && manifestFile.length === 1) {
+            try {
+                const content = await this.zipFile.readFile(manifestFile[0]);
+                const data = (0, io_1.decodeText)(content);
+                const str = typeof data === 'string' ? data : (0, io_1.readTextFromInput)(data);
+                if (!str.trim())
+                    throw new Error('Manifest object missing');
+                const manifestObject = JSON.parse(str);
+                if (!manifestObject)
+                    throw new Error('Manifest object is empty');
+                // Replace OBF file list
+                if (manifestObject.paths && manifestObject.paths.boards) {
+                    obfEntries = Object.values(manifestObject.paths.boards);
+                }
+                // Move root board to top of list
+                if (manifestObject.root) {
+                    obfEntries = obfEntries.filter((item) => item !== manifestObject.root);
+                    obfEntries.unshift(manifestObject.root);
+                }
+            }
+            catch (err) {
+                console.warn('[OBF] Error processing mainfest', err);
+            }
+        }
         // Process each .obf entry
         for (const entryName of obfEntries) {
             try {
                 const content = await this.zipFile.readFile(entryName);
                 const boardData = tryParseObfJson((0, io_1.decodeText)(content));
                 if (boardData) {
-                    const page = await this.processBoard(boardData, entryName);
+                    const page = await this.processBoard(boardData, entryName, true);
                     tree.addPage(page);
                     // Set metadata if not already set (use first board as reference)
                     if (!tree.metadata.format) {

package/dist/processors/snapProcessor.js

@@ -7,6 +7,26 @@ const idGenerator_1 = require("../utilities/analytics/utils/idGenerator");
 const snapValidator_1 = require("../validation/snapValidator");
 const io_1 = require("../utils/io");
 const sqlite_1 = require("../utils/sqlite");
+const zip_1 = require("../utils/zip");
+/**
+ * Convert a Buffer or Uint8Array to base64 string (browser and Node compatible)
+ * Node.js Buffers support toString('base64'), but Uint8Arrays in browser do not.
+ * This function works in both environments.
+ */
+function arrayBufferToBase64(data) {
+    // Node.js environment - Buffer has built-in base64 encoding
+    if (typeof Buffer !== 'undefined' && data instanceof Buffer) {
+        return data.toString('base64');
+    }
+    // Browser environment - use btoa with binary string conversion
+    const bytes = new Uint8Array(data);
+    let binary = '';
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
 /**
  * Map Snap Visible value to AAC standard visibility
  * Snap: 0 = hidden, 1 (or non-zero) = visible
@@ -51,8 +71,37 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
         await Promise.resolve();
         const tree = new treeStructure_1.AACTree();
         let dbResult = null;
+        let cleanupTempZip = null;
         try {
-            dbResult = await (0, sqlite_1.openSqliteDatabase)(filePathOrBuffer, { readonly: true });
+            // Handle .sub.zip files (Snap pageset backups containing .sps files)
+            let inputFile = filePathOrBuffer;
+            if (typeof filePathOrBuffer === 'string') {
+                const fileName = (0, io_1.getPath)().basename(filePathOrBuffer).toLowerCase();
+                if (fileName.endsWith('.sub.zip') || filePathOrBuffer.endsWith('.sub')) {
+                    const fs = (0, io_1.getFs)();
+                    const path = (0, io_1.getPath)();
+                    const os = (0, io_1.getOs)();
+                    // Extract .sub.zip to find the embedded .sps file
+                    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'snap-sub-'));
+                    const { zip } = await (0, zip_1.openZipFromInput)(filePathOrBuffer);
+                    // Find the .sps file in the archive
+                    const files = zip.listFiles();
+                    const spsFile = files.find((f) => f.endsWith('.sps'));
+                    if (!spsFile) {
+                        fs.rmSync(tempDir, { recursive: true, force: true });
+                        throw new Error('No .sps file found in .sub.zip archive');
+                    }
+                    // Extract the .sps file
+                    const spsData = await zip.readFile(spsFile);
+                    const extractedSpsPath = path.join(tempDir, path.basename(spsFile));
+                    fs.writeFileSync(extractedSpsPath, Buffer.from(spsData));
+                    inputFile = extractedSpsPath;
+                    cleanupTempZip = () => {
+                        fs.rmSync(tempDir, { recursive: true, force: true });
+                    };
+                }
+            }
+            dbResult = await (0, sqlite_1.openSqliteDatabase)(inputFile, { readonly: true });
             const db = dbResult.db;
             const getTableColumns = (tableName) => {
                 try {
@@ -448,7 +497,7 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                                 if (isPng || isJpeg) {
                                     // Actual PNG/JPEG image - can be displayed
                                     const mimeType = isPng ? 'image/png' : 'image/jpeg';
-                                    const base64 = data.toString('base64');
+                                    const base64 = arrayBufferToBase64(data);
                                     buttonImage = `data:${mimeType};base64,${base64}`;
                                     buttonParameters.image_id = imageData.Identifier;
                                 }
@@ -642,6 +691,15 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
             else if (dbResult?.db) {
                 dbResult.db.close();
             }
+            // Clean up temporary extracted .sps file from .sub.zip
+            if (cleanupTempZip) {
+                try {
+                    cleanupTempZip();
+                }
+                catch (e) {
+                    console.warn('[SnapProcessor] Failed to clean up temporary .sps file:', e);
+                }
+            }
         }
     }
     async processTexts(filePathOrBuffer, translations, outputPath) {

package/dist/processors/touchchatProcessor.js

@@ -67,7 +67,9 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
             this.sourceFile = filePathOrBuffer;
             // Step 1: Unzip
             const zipInput = (0, io_1.readBinaryFromInput)(filePathOrBuffer);
-            const { zip } = await (0, zip_1.openZipFromInput)(zipInput);
+            const { zip } = this.options.zipAdapter
+                ? await this.options.zipAdapter(zipInput)
+                : await (0, zip_1.openZipFromInput)(zipInput);
             const vocabEntry = zip.listFiles().find((name) => name.endsWith('.c4v'));
             if (!vocabEntry) {
                 throw new Error('No .c4v vocab DB found in TouchChat export');

package/dist/validation/touchChatValidator.d.ts

@@ -1,5 +1,7 @@
 import { BaseValidator } from './baseValidator';
 import { ValidationResult } from './validationTypes';
+import { type ProcessorInput } from '../utils/io';
+import { type ZipAdapter } from '../utils/zip';
 /**
  * Validator for TouchChat files (.ce)
  * TouchChat files are ZIP archives that contain a .c4v SQLite database.
@@ -14,7 +16,9 @@ export declare class TouchChatValidator extends BaseValidator {
     /**
      * Check if content is TouchChat format
      */
-    static identifyFormat(content: any, filename: string): Promise<boolean>;
+    static identifyFormat(content: any, filename: string, zipAdapter?: (input: ProcessorInput) => Promise<{
+        zip: ZipAdapter;
+    }>): Promise<boolean>;
     /**
      * Main validation method
      */

package/dist/validation/touchChatValidator.js

@@ -53,14 +53,14 @@ class TouchChatValidator extends baseValidator_1.BaseValidator {
     /**
      * Check if content is TouchChat format
      */
-    static async identifyFormat(content, filename) {
+    static async identifyFormat(content, filename, zipAdapter) {
         const name = filename.toLowerCase();
         if (name.endsWith('.ce')) {
             return true;
         }
         // Try to parse as ZIP and check for .c4v database
         try {
-            const { zip } = await (0, zip_1.openZipFromInput)(content);
+            const { zip } = zipAdapter ? await zipAdapter(content) : await (0, zip_1.openZipFromInput)(content);
             const entries = zip.listFiles();
             if (entries.some((entry) => entry.toLowerCase().endsWith('.c4v'))) {
                 return true;

package/package.json

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