@willwade/aac-processors 0.1.4 → 0.1.6

package/README.md

@@ -30,6 +30,20 @@ const texts = await snap.extractTexts('board.sps');
 Browser-safe entry that avoids Node-only dependencies. It expects `Buffer`,
 `Uint8Array`, or `ArrayBuffer` inputs rather than file paths.
 
+SQLite-backed formats (Snap `.sps/.spb` and TouchChat `.ce`) require a WASM
+SQLite engine. Configure `sql.js` in your bundler before loading those formats:
+
+```ts
+import { configureSqlJs, SnapProcessor } from '@willwade/aac-processors/browser';
+
+configureSqlJs({
+  locateFile: (file) => new URL(`./${file}`, import.meta.url).toString(),
+});
+
+const snap = new SnapProcessor();
+const tree = await snap.loadIntoTree(snapUint8Array);
+```
+
 ```ts
 import { GridsetProcessor } from '@willwade/aac-processors/browser';
 

package/dist/browser/index.browser.js

@@ -6,6 +6,10 @@
  * **NOTE: Gridset .gridsetx files**
  * GridsetProcessor supports regular `.gridset` files in browser.
  * Encrypted `.gridsetx` files require Node.js for crypto operations and are not supported in browser.
+ *
+ * **NOTE: SQLite-backed formats**
+ * Snap (.sps/.spb) and TouchChat (.ce) require a WASM-backed SQLite engine.
+ * Configure `sql.js` in browser builds via `configureSqlJs()` before loading these formats.
  */
 // ===================================================================
 // CORE TYPES
@@ -20,14 +24,19 @@ export { DotProcessor } from './processors/dotProcessor';
 export { OpmlProcessor } from './processors/opmlProcessor';
 export { ObfProcessor } from './processors/obfProcessor';
 export { GridsetProcessor } from './processors/gridsetProcessor';
+export { SnapProcessor } from './processors/snapProcessor';
+export { TouchChatProcessor } from './processors/touchchatProcessor';
 export { ApplePanelsProcessor } from './processors/applePanelsProcessor';
 export { AstericsGridProcessor } from './processors/astericsGridProcessor';
 import { DotProcessor } from './processors/dotProcessor';
 import { OpmlProcessor } from './processors/opmlProcessor';
 import { ObfProcessor } from './processors/obfProcessor';
 import { GridsetProcessor } from './processors/gridsetProcessor';
+import { SnapProcessor } from './processors/snapProcessor';
+import { TouchChatProcessor } from './processors/touchchatProcessor';
 import { ApplePanelsProcessor } from './processors/applePanelsProcessor';
 import { AstericsGridProcessor } from './processors/astericsGridProcessor';
+export { configureSqlJs } from './utils/sqlite';
 /**
  * Factory function to get the appropriate processor for a file extension
  * @param filePathOrExtension - File path or extension (e.g., '.dot', '/path/to/file.obf')
@@ -48,6 +57,11 @@ export function getProcessor(filePathOrExtension) {
             return new ObfProcessor();
         case '.gridset':
             return new GridsetProcessor();
+        case '.spb':
+        case '.sps':
+            return new SnapProcessor();
+        case '.ce':
+            return new TouchChatProcessor();
         case '.plist':
             return new ApplePanelsProcessor();
         case '.grd':
@@ -61,7 +75,7 @@ export function getProcessor(filePathOrExtension) {
  * @returns Array of supported file extensions
  */
 export function getSupportedExtensions() {
-    return ['.dot', '.opml', '.obf', '.obz', '.gridset', '.plist', '.grd'];
+    return ['.dot', '.opml', '.obf', '.obz', '.gridset', '.spb', '.sps', '.ce', '.plist', '.grd'];
 }
 /**
  * Check if a file extension is supported

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

@@ -47,3 +47,14 @@ export function getZipEntriesWithPassword(zip, password) {
     });
     return entries;
 }
+export function getZipEntriesFromAdapter(zip, password) {
+    if (password) {
+        console.warn('Zip password support is handled at the archive level for .gridsetx files.');
+    }
+    return zip.listFiles().map((entryName) => ({
+        name: entryName,
+        entryName,
+        dir: false,
+        getData: () => zip.readFile(entryName),
+    }));
+}

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

@@ -12,7 +12,7 @@
  *
  * This module provides symbol resolution and metadata extraction.
  */
-import { getFs, getPath } from '../../utils/io';
+import { getFs, getNodeRequire, getPath } from '../../utils/io';
 /**
  * Default Grid 3 installation paths by platform
  */
@@ -76,8 +76,9 @@ function getAdmZip() {
     if (cachedAdmZip)
         return cachedAdmZip;
     try {
+        const nodeRequire = getNodeRequire();
         // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const module = require('adm-zip');
+        const module = nodeRequire('adm-zip');
         const resolved = module.default || module;
         cachedAdmZip = resolved;
         return resolved;

package/dist/browser/processors/gridsetProcessor.js

@@ -3,7 +3,7 @@ import { AACTree, AACPage, AACButton, AACSemanticCategory, AACSemanticIntent, }
 import { XMLParser, XMLBuilder } from 'fast-xml-parser';
 import { resolveGrid3CellImage } from './gridset/resolver';
 import { extractAllButtonsForTranslation, validateTranslationResults, } from '../utilities/translation/translationProcessor';
-import { getZipEntriesWithPassword, resolveGridsetPassword } from './gridset/password';
+import { getZipEntriesFromAdapter, resolveGridsetPassword, } from './gridset/password';
 import { decryptGridsetEntry } from './gridset/crypto';
 import { GridsetValidator } from '../validation/gridsetValidator';
 // New imports for enhanced Grid 3 support
@@ -13,32 +13,8 @@ import { parseSymbolReference } from './gridset/symbols';
 import { isSymbolLibraryReference } from './gridset/resolver';
 import { generateCloneId } from '../utilities/analytics/utils/idGenerator';
 import { translateWithSymbols, extractSymbolsFromButton } from './gridset/symbolAlignment';
-import { readBinaryFromInput, decodeText, writeBinaryToPath } from '../utils/io';
-let JSZipModule;
-async function getJSZip() {
-    if (!JSZipModule) {
-        try {
-            // Try ES module import first (browser/Vite)
-            const module = await import('jszip');
-            JSZipModule = module.default || module;
-        }
-        catch (error) {
-            // Fall back to CommonJS require (Node.js)
-            try {
-                // eslint-disable-next-line @typescript-eslint/no-var-requires
-                const module = require('jszip');
-                JSZipModule = module.default || module;
-            }
-            catch (err2) {
-                throw new Error('Zip handling requires JSZip in this environment.');
-            }
-        }
-    }
-    if (!JSZipModule) {
-        throw new Error('Zip handling requires JSZip in this environment.');
-    }
-    return JSZipModule;
-}
+import { readBinaryFromInput, decodeText, writeBinaryToPath, getNodeRequire, isNodeRuntime, } from '../utils/io';
+import { openZipFromInput } from '../utils/zip';
 class GridsetProcessor extends BaseProcessor {
     constructor(options) {
         super(options);
@@ -411,17 +387,15 @@ class GridsetProcessor extends BaseProcessor {
     }
     async loadIntoTree(filePathOrBuffer) {
         const tree = new AACTree();
-        let zip;
+        let zipResult;
         try {
-            const JSZip = await getJSZip();
-            const zipInput = readBinaryFromInput(filePathOrBuffer);
-            zip = await JSZip.loadAsync(zipInput);
+            zipResult = await openZipFromInput(readBinaryFromInput(filePathOrBuffer));
         }
         catch (error) {
             throw new Error(`Invalid ZIP file format: ${error.message}`);
         }
         const password = this.getGridsetPassword(filePathOrBuffer);
-        const entries = getZipEntriesWithPassword(zip, password);
+        const entries = getZipEntriesFromAdapter(zipResult.zip, password);
         const parser = new XMLParser({ ignoreAttributes: false });
         const isEncryptedArchive = typeof filePathOrBuffer === 'string' && filePathOrBuffer.toLowerCase().endsWith('.gridsetx');
         const encryptedContentPassword = this.getGridsetPassword(filePathOrBuffer);
@@ -432,14 +406,11 @@ class GridsetProcessor extends BaseProcessor {
             passwordProtected: !!password,
         };
         const readEntryBuffer = async (entry) => {
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument
             const raw = await entry.getData();
             if (!isEncryptedArchive) {
-                // eslint-disable-next-line @typescript-eslint/no-unsafe-return
                 return raw;
             }
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-return
-            return decryptGridsetEntry(raw, encryptedContentPassword);
+            return decryptGridsetEntry(Buffer.from(raw), encryptedContentPassword);
         };
         // Parse FileMap.xml if present to index dynamic files per grid
         const fileMapIndex = new Map();
@@ -759,7 +730,7 @@ class GridsetProcessor extends BaseProcessor {
                         const gridEntryPath = entry.entryName.replace(/\\/g, '/');
                         const baseDir = gridEntryPath.replace(/\/grid\.xml$/, '/');
                         const dynamicFiles = fileMapIndex.get(gridEntryPath) || [];
-                        const resolvedImageEntry = resolveGrid3CellImage(zip, {
+                        const resolvedImageEntry = resolveGrid3CellImage(null, {
                             baseDir,
                             imageName: declaredImageName,
                             x: cellX + 1,
@@ -1610,11 +1581,36 @@ class GridsetProcessor extends BaseProcessor {
         return readBinaryFromInput(outputPath);
     }
     async saveFromTree(tree, outputPath) {
-        const JSZip = await getJSZip();
-        const zip = new JSZip();
+        const useNodeZip = isNodeRuntime();
+        let addText;
+        let addBinary;
+        let finalizeZip;
+        if (useNodeZip) {
+            const AdmZip = getNodeRequire()('adm-zip');
+            const zip = new AdmZip();
+            addText = (entryPath, content) => {
+                zip.addFile(entryPath, Buffer.from(content, 'utf8'));
+            };
+            addBinary = (entryPath, content) => {
+                zip.addFile(entryPath, Buffer.from(content));
+            };
+            finalizeZip = () => Promise.resolve(zip.toBuffer());
+        }
+        else {
+            const module = await import('jszip');
+            const JSZip = module.default || module;
+            const zip = new JSZip();
+            addText = (entryPath, content) => {
+                zip.file(entryPath, content, { binary: false });
+            };
+            addBinary = (entryPath, content) => {
+                zip.file(entryPath, content);
+            };
+            finalizeZip = async () => zip.generateAsync({ type: 'uint8array' });
+        }
         if (Object.keys(tree.pages).length === 0) {
             // Create empty zip for empty tree
-            const zipBuffer = await zip.generateAsync({ type: 'uint8array' });
+            const zipBuffer = await finalizeZip();
             writeBinaryToPath(outputPath, zipBuffer);
             return;
         }
@@ -1687,7 +1683,7 @@ class GridsetProcessor extends BaseProcessor {
             suppressEmptyNode: true,
         });
         const settingsXmlContent = settingsBuilder.build(settingsData);
-        zip.file('Settings0/settings.xml', settingsXmlContent, { binary: false });
+        addText('Settings0/settings.xml', settingsXmlContent);
         // Create Settings0/Styles/style.xml if there are styles
         if (uniqueStyles.size > 0) {
             const stylesArray = Array.from(uniqueStyles.values()).map(({ id, style }) => {
@@ -1720,7 +1716,7 @@ class GridsetProcessor extends BaseProcessor {
                 indentBy: '  ',
             });
             const styleXmlContent = styleBuilder.build(styleData);
-            zip.file('Settings0/Styles/styles.xml', styleXmlContent, { binary: false });
+            addText('Settings0/Styles/styles.xml', styleXmlContent);
         }
         // Collect grid file paths for FileMap.xml
         const gridFilePaths = [];
@@ -1861,14 +1857,14 @@ class GridsetProcessor extends BaseProcessor {
             // Add to zip in Grids folder with proper Grid3 naming
             const gridPath = `Grids/${page.name || page.id}/grid.xml`;
             gridFilePaths.push(gridPath);
-            zip.file(gridPath, xmlContent, { binary: false });
+            addText(gridPath, xmlContent);
         });
         // Write image files to ZIP
         buttonImages.forEach((imgData) => {
             if (imgData.imageData && imgData.imageData.length > 0) {
                 // Create image path in the grid's directory
                 const imagePath = `Grids/${imgData.pageName}/${imgData.x}-${imgData.y}-0-text-0.${imgData.ext}`;
-                zip.file(imagePath, imgData.imageData);
+                addBinary(imagePath, imgData.imageData);
             }
         });
         // Create FileMap.xml to map all grid files with their dynamic image files
@@ -1907,9 +1903,9 @@ class GridsetProcessor extends BaseProcessor {
             indentBy: '  ',
         });
         const fileMapXmlContent = fileMapBuilder.build(fileMapData);
-        zip.file('FileMap.xml', fileMapXmlContent, { binary: false });
+        addText('FileMap.xml', fileMapXmlContent);
         // Write the zip file
-        const zipBuffer = await zip.generateAsync({ type: 'uint8array' });
+        const zipBuffer = await finalizeZip();
         writeBinaryToPath(outputPath, zipBuffer);
     }
     // Helper method to calculate column definitions based on page layout

package/dist/browser/processors/obfProcessor.js

@@ -2,32 +2,8 @@ import { BaseProcessor, } from '../core/baseProcessor';
 import { AACTree, AACPage, AACButton, AACSemanticCategory, AACSemanticIntent, } from '../core/treeStructure';
 import { generateCloneId } from '../utilities/analytics/utils/idGenerator';
 import { extractAllButtonsForTranslation, validateTranslationResults, } from '../utilities/translation/translationProcessor';
-import { readBinaryFromInput, readTextFromInput, writeTextToPath, encodeBase64, } from '../utils/io';
-let JSZipModuleObf;
-async function getJSZipObf() {
-    if (!JSZipModuleObf) {
-        try {
-            // Try ES module import first (browser/Vite)
-            const module = await import('jszip');
-            JSZipModuleObf = module.default || module;
-        }
-        catch (error) {
-            // Fall back to CommonJS require (Node.js)
-            try {
-                // eslint-disable-next-line @typescript-eslint/no-var-requires
-                const module = require('jszip');
-                JSZipModuleObf = module.default || module;
-            }
-            catch (err2) {
-                throw new Error('Zip handling requires JSZip in this environment.');
-            }
-        }
-    }
-    if (!JSZipModuleObf) {
-        throw new Error('Zip handling requires JSZip in this environment.');
-    }
-    return JSZipModuleObf;
-}
+import { readBinaryFromInput, readTextFromInput, writeTextToPath, encodeBase64, decodeText, getNodeRequire, isNodeRuntime, } from '../utils/io';
+import { openZipFromInput } from '../utils/zip';
 const OBF_FORMAT_VERSION = 'open-board-0.1';
 /**
  * Map OBF hidden value to AAC standard visibility
@@ -65,10 +41,12 @@ class ObfProcessor extends BaseProcessor {
         ].filter(Boolean);
         for (const imagePath of possiblePaths) {
             try {
-                const file = this.zipFile.file(imagePath);
-                if (file) {
-                    const buffer = await file.async('nodebuffer');
-                    return buffer;
+                const buffer = await this.zipFile.readFile(imagePath);
+                if (buffer) {
+                    if (typeof Buffer !== 'undefined') {
+                        return Buffer.from(buffer);
+                    }
+                    return null;
                 }
             }
             catch (err) {
@@ -102,9 +80,8 @@ class ObfProcessor extends BaseProcessor {
         ].filter(Boolean);
         for (const imagePath of possiblePaths) {
             try {
-                const file = this.zipFile.file(imagePath);
-                if (file) {
-                    const buffer = await file.async('uint8array');
+                const buffer = await this.zipFile.readFile(imagePath);
+                if (buffer) {
                     const contentType = imageData.content_type ||
                         this.getMimeTypeFromFilename(imagePath);
                     const dataUrl = `data:${contentType};base64,${encodeBase64(buffer)}`;
@@ -407,36 +384,28 @@ class ObfProcessor extends BaseProcessor {
         if (!isLikelyZip(filePathOrBuffer)) {
             throw new Error('Invalid OBF content: not JSON and not ZIP');
         }
-        const JSZip = await getJSZipObf();
-        let zip;
         try {
-            const zipInput = readBinaryFromInput(filePathOrBuffer);
-            zip = await JSZip.loadAsync(zipInput);
+            const zipResult = await openZipFromInput(filePathOrBuffer);
+            this.zipFile = zipResult.zip;
         }
         catch (err) {
-            console.error('[OBF] Error loading ZIP with JSZip:', err);
+            console.error('[OBF] Error loading ZIP:', err);
             throw err;
         }
         // Store the ZIP file reference for image extraction
-        this.zipFile = zip;
         this.imageCache.clear(); // Clear cache for new file
         console.log('[OBF] Detected zip archive, extracting .obf files');
         // Collect all .obf entries
-        const obfEntries = [];
-        zip.forEach((relativePath, file) => {
-            if (file.dir)
-                return;
-            if (relativePath.toLowerCase().endsWith('.obf')) {
-                obfEntries.push({ name: relativePath, file });
-            }
-        });
+        const obfEntries = this.zipFile
+            .listFiles()
+            .filter((name) => name.toLowerCase().endsWith('.obf'));
         // Process each .obf entry
-        for (const entry of obfEntries) {
+        for (const entryName of obfEntries) {
             try {
-                const content = await entry.file.async('string');
-                const boardData = tryParseObfJson(content);
+                const content = await this.zipFile.readFile(entryName);
+                const boardData = tryParseObfJson(decodeText(content));
                 if (boardData) {
-                    const page = await this.processBoard(boardData, entry.name);
+                    const page = await this.processBoard(boardData, entryName);
                     tree.addPage(page);
                     // Set metadata if not already set (use first board as reference)
                     if (!tree.metadata.format) {
@@ -453,11 +422,11 @@ class ObfProcessor extends BaseProcessor {
                     }
                 }
                 else {
-                    console.warn('[OBF] Skipped entry (not valid OBF JSON):', entry.name);
+                    console.warn('[OBF] Skipped entry (not valid OBF JSON):', entryName);
                 }
             }
             catch (err) {
-                console.warn('[OBF] Error processing entry:', entry.name, err);
+                console.warn('[OBF] Error processing entry:', entryName, err);
             }
         }
         return tree;
@@ -583,16 +552,31 @@ class ObfProcessor extends BaseProcessor {
         }
         else {
             // Save as OBZ (zip with multiple OBF files)
-            const JSZip = await getJSZipObf();
-            const zip = new JSZip();
-            Object.values(tree.pages).forEach((page) => {
-                const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
-                const obfContent = JSON.stringify(obfBoard, null, 2);
-                zip.file(`${page.id}.obf`, obfContent);
-            });
-            const zipBuffer = await zip.generateAsync({ type: 'uint8array' });
-            const { writeBinaryToPath } = await import('../utils/io');
-            writeBinaryToPath(outputPath, zipBuffer);
+            if (isNodeRuntime()) {
+                const AdmZip = getNodeRequire()('adm-zip');
+                const zip = new AdmZip();
+                Object.values(tree.pages).forEach((page) => {
+                    const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
+                    const obfContent = JSON.stringify(obfBoard, null, 2);
+                    zip.addFile(`${page.id}.obf`, Buffer.from(obfContent, 'utf8'));
+                });
+                const zipBuffer = zip.toBuffer();
+                const { writeBinaryToPath } = await import('../utils/io');
+                writeBinaryToPath(outputPath, zipBuffer);
+            }
+            else {
+                const module = await import('jszip');
+                const JSZip = module.default || module;
+                const zip = new JSZip();
+                Object.values(tree.pages).forEach((page) => {
+                    const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
+                    const obfContent = JSON.stringify(obfBoard, null, 2);
+                    zip.file(`${page.id}.obf`, obfContent);
+                });
+                const zipBuffer = await zip.generateAsync({ type: 'uint8array' });
+                const { writeBinaryToPath } = await import('../utils/io');
+                writeBinaryToPath(outputPath, zipBuffer);
+            }
         }
     }
     /**