@willwade/aac-processors 0.1.17 → 0.1.19

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

@@ -352,9 +352,20 @@ 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]');
             tree.addPage(page);
@@ -372,20 +383,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) {

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

@@ -4,6 +4,11 @@ import * as path from 'path';
 import Database from 'better-sqlite3';
 import { dotNetTicksToDate } from '../../utils/dotnetTicks';
 // Minimal Snap helpers (stubs) to align with processors/<engine>/helpers pattern
+// NOTE: Snap files can store different types of image data in PageSetData:
+// - PNG/JPEG binaries: Actual images that can be displayed
+// - Vector graphics: Custom format (d7 cd c6 9a) requiring rendering engine
+//
+// We extract PNG/JPEG images but skip vector graphics (requires renderer).
 // NOTE: Snap buttons currently do not populate resolvedImageEntry; these helpers
 // therefore return empty collections until image resolution is implemented.
 function collectFiles(root, matcher, maxDepth = 3) {
@@ -105,6 +110,9 @@ export function openImage(dbOrFile, entryPath) {
             .prepare('SELECT Id, Identifier, Data FROM PageSetData WHERE Identifier = ?')
             .get(entryPath);
         if (row && row.Data && row.Data.length > 0) {
+            // Snap files can store different types of image data:
+            // 1. PNG/JPEG binaries (actual images) - return as-is
+            // 2. Vector graphics (custom format d7 cd c6 9a) - return but may not be displayable
             return row.Data;
         }
         return null;

package/dist/browser/processors/snapProcessor.js

@@ -4,6 +4,25 @@ import { generateCloneId } from '../utilities/analytics/utils/idGenerator';
 import { SnapValidator } from '../validation/snapValidator';
 import { getFs, getNodeRequire, getPath, isNodeRuntime } from '../utils/io';
 import { openSqliteDatabase, requireBetterSqlite3 } from '../utils/sqlite';
+/**
+ * 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
@@ -15,41 +34,6 @@ function mapSnapVisibility(visible) {
     }
     return visible === 0 ? 'Hidden' : 'Visible';
 }
-/**
- * Detect image MIME type from binary data using magic bytes
- * @param buffer Image data buffer
- * @returns MIME type string (defaults to 'image/png' if unknown)
- */
-function detectImageMimeType(buffer) {
-    if (!buffer || buffer.length < 8) {
-        return 'image/png';
-    }
-    // Check for PNG: 89 50 4E 47 0D 0A 1A 0A
-    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
-        return 'image/png';
-    }
-    // Check for JPEG: FF D8 FF
-    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
-        return 'image/jpeg';
-    }
-    // Check for GIF: 47 49 46 38 (GIF8)
-    if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
-        return 'image/gif';
-    }
-    // Check for WebP: 52 49 46 46 ... 57 45 42 50 (RIFF...WEBP)
-    if (buffer[0] === 0x52 &&
-        buffer[1] === 0x49 &&
-        buffer[2] === 0x46 &&
-        buffer[3] === 0x46 &&
-        buffer[8] === 0x57 &&
-        buffer[9] === 0x45 &&
-        buffer[10] === 0x42 &&
-        buffer[11] === 0x50) {
-        return 'image/webp';
-    }
-    // Default to PNG
-    return 'image/png';
-}
 class SnapProcessor extends BaseProcessor {
     constructor(symbolResolver = null, options = {}) {
         super(options);
@@ -465,14 +449,30 @@ class SnapProcessor extends BaseProcessor {
                 `)
                                 .get(btnRow.PageSetImageId);
                             if (imageData && imageData.Data && imageData.Data.length > 0) {
-                                const mimeType = detectImageMimeType(imageData.Data);
-                                const base64 = imageData.Data.toString('base64');
-                                buttonImage = `data:${mimeType};base64,${base64}`;
-                                buttonParameters.image_id = imageData.Identifier;
-                                // NOTE: We don't include imageData in parameters because Buffers don't serialize
-                                // correctly across server/client boundaries (Next.js SSR, JSON, etc.)
-                                // The data URL in buttonImage is sufficient for display purposes.
-                                // For conversions, images can be reloaded from the source file/database.
+                                // Snap files can store different types of image data:
+                                // 1. PNG/JPEG binaries (actual images) - extract and display
+                                // 2. Vector graphics (custom format d7 cd c6 9a) - skip (requires renderer)
+                                const data = imageData.Data;
+                                // Check for PNG: 89 50 4E 47
+                                const isPng = data.length > 4 &&
+                                    data[0] === 0x89 &&
+                                    data[1] === 0x50 &&
+                                    data[2] === 0x4e &&
+                                    data[3] === 0x47;
+                                // Check for JPEG: FF D8 FF
+                                const isJpeg = data.length > 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;
+                                if (isPng || isJpeg) {
+                                    // Actual PNG/JPEG image - can be displayed
+                                    const mimeType = isPng ? 'image/png' : 'image/jpeg';
+                                    const base64 = arrayBufferToBase64(data);
+                                    buttonImage = `data:${mimeType};base64,${base64}`;
+                                    buttonParameters.image_id = imageData.Identifier;
+                                }
+                                else {
+                                    // Vector graphics or other format - skip rendering
+                                    // Store identifier but don't create image URL
+                                    buttonParameters.image_id = imageData.Identifier;
+                                }
                             }
                         }
                         catch (e) {

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/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

@@ -378,9 +378,20 @@ 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]');
             tree.addPage(page);
@@ -398,20 +409,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) {

package/dist/processors/snap/helpers.js

@@ -43,6 +43,11 @@ const path = __importStar(require("path"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const dotnetTicks_1 = require("../../utils/dotnetTicks");
 // Minimal Snap helpers (stubs) to align with processors/<engine>/helpers pattern
+// NOTE: Snap files can store different types of image data in PageSetData:
+// - PNG/JPEG binaries: Actual images that can be displayed
+// - Vector graphics: Custom format (d7 cd c6 9a) requiring rendering engine
+//
+// We extract PNG/JPEG images but skip vector graphics (requires renderer).
 // NOTE: Snap buttons currently do not populate resolvedImageEntry; these helpers
 // therefore return empty collections until image resolution is implemented.
 function collectFiles(root, matcher, maxDepth = 3) {
@@ -144,6 +149,9 @@ function openImage(dbOrFile, entryPath) {
             .prepare('SELECT Id, Identifier, Data FROM PageSetData WHERE Identifier = ?')
             .get(entryPath);
         if (row && row.Data && row.Data.length > 0) {
+            // Snap files can store different types of image data:
+            // 1. PNG/JPEG binaries (actual images) - return as-is
+            // 2. Vector graphics (custom format d7 cd c6 9a) - return but may not be displayable
             return row.Data;
         }
         return null;

package/dist/processors/snapProcessor.js

@@ -7,6 +7,25 @@ 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");
+/**
+ * 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
@@ -18,41 +37,6 @@ function mapSnapVisibility(visible) {
     }
     return visible === 0 ? 'Hidden' : 'Visible';
 }
-/**
- * Detect image MIME type from binary data using magic bytes
- * @param buffer Image data buffer
- * @returns MIME type string (defaults to 'image/png' if unknown)
- */
-function detectImageMimeType(buffer) {
-    if (!buffer || buffer.length < 8) {
-        return 'image/png';
-    }
-    // Check for PNG: 89 50 4E 47 0D 0A 1A 0A
-    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
-        return 'image/png';
-    }
-    // Check for JPEG: FF D8 FF
-    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
-        return 'image/jpeg';
-    }
-    // Check for GIF: 47 49 46 38 (GIF8)
-    if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
-        return 'image/gif';
-    }
-    // Check for WebP: 52 49 46 46 ... 57 45 42 50 (RIFF...WEBP)
-    if (buffer[0] === 0x52 &&
-        buffer[1] === 0x49 &&
-        buffer[2] === 0x46 &&
-        buffer[3] === 0x46 &&
-        buffer[8] === 0x57 &&
-        buffer[9] === 0x45 &&
-        buffer[10] === 0x42 &&
-        buffer[11] === 0x50) {
-        return 'image/webp';
-    }
-    // Default to PNG
-    return 'image/png';
-}
 class SnapProcessor extends baseProcessor_1.BaseProcessor {
     constructor(symbolResolver = null, options = {}) {
         super(options);
@@ -468,14 +452,30 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                 `)
                                 .get(btnRow.PageSetImageId);
                             if (imageData && imageData.Data && imageData.Data.length > 0) {
-                                const mimeType = detectImageMimeType(imageData.Data);
-                                const base64 = imageData.Data.toString('base64');
-                                buttonImage = `data:${mimeType};base64,${base64}`;
-                                buttonParameters.image_id = imageData.Identifier;
-                                // NOTE: We don't include imageData in parameters because Buffers don't serialize
-                                // correctly across server/client boundaries (Next.js SSR, JSON, etc.)
-                                // The data URL in buttonImage is sufficient for display purposes.
-                                // For conversions, images can be reloaded from the source file/database.
+                                // Snap files can store different types of image data:
+                                // 1. PNG/JPEG binaries (actual images) - extract and display
+                                // 2. Vector graphics (custom format d7 cd c6 9a) - skip (requires renderer)
+                                const data = imageData.Data;
+                                // Check for PNG: 89 50 4E 47
+                                const isPng = data.length > 4 &&
+                                    data[0] === 0x89 &&
+                                    data[1] === 0x50 &&
+                                    data[2] === 0x4e &&
+                                    data[3] === 0x47;
+                                // Check for JPEG: FF D8 FF
+                                const isJpeg = data.length > 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;
+                                if (isPng || isJpeg) {
+                                    // Actual PNG/JPEG image - can be displayed
+                                    const mimeType = isPng ? 'image/png' : 'image/jpeg';
+                                    const base64 = arrayBufferToBase64(data);
+                                    buttonImage = `data:${mimeType};base64,${base64}`;
+                                    buttonParameters.image_id = imageData.Identifier;
+                                }
+                                else {
+                                    // Vector graphics or other format - skip rendering
+                                    // Store identifier but don't create image URL
+                                    buttonParameters.image_id = imageData.Identifier;
+                                }
                             }
                         }
                         catch (e) {

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.17",
+  "version": "0.1.19",
   "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",