@willwade/aac-processors 0.1.5 → 0.1.7

package/examples/README.md

@@ -49,79 +49,7 @@ These pagesets are used by:
 
 To run demo scripts that use these pagesets, see the [scripts/README.md](../scripts/README.md).
 
-## Browser Testing
+## Browser Demo (Vite)
 
-### ⚠️ Important Note
-
-AACProcessors is built with TypeScript and outputs CommonJS modules. To use it in a browser, you **must use a bundler** (Vite, Webpack, Rollup, etc.). The browser test page below only validates the library structure - it cannot run actual processors without a bundler.
-
-### Browser Test Page
-
-A dedicated browser test page is available for validating the library structure:
-
-**Start the test server:**
-```bash
-node examples/browser-test-server.js
-```
-
-**Open in your browser:**
-```
-http://localhost:8080/examples/browser-test.html
-```
-
-**What it tests:**
-- ✅ Browser build files exist and are accessible
-- ✅ Type definitions are present
-- ✅ Processor exports are available
-- ❌ **Does NOT run actual processors** (requires bundler)
-
-### What Gets Tested
-
-The browser test page (`browser-test.html`) verifies:
-
-1. **Module Loading** - Can the browser load the ES modules?
-2. **Factory Functions** - Do `getProcessor()` and `getSupportedExtensions()` work?
-3. **Processor Instantiation** - Can processors be created?
-4. **File Loading** - Can files be loaded from `<input type="file">`?
-5. **Buffer Handling** - Do ArrayBuffers/Uint8Arrays work correctly?
-6. **Tree Structure** - Can AACTree be created from files?
-7. **Text Extraction** - Can texts be extracted from files?
-
-### Supported File Types in Browser
-
-The browser test page supports all browser-compatible processors:
-
-- **DotProcessor** (.dot) - OpenSymbols Board files
-- **OpmlProcessor** (.opml) - OPML outline files
-- **ObfProcessor** (.obf/.obz) - Open Board Format files
-- **GridsetProcessor** (.gridset) - Grid 3 gridset files (not .gridsetx)
-- **ApplePanelsProcessor** (.plist) - Apple Panels files
-- **AstericsGridProcessor** (.grd) - Asterics Grid files
-
-### Manual Testing
-
-1. Open the browser console (F12 or Cmd+Option+I)
-2. Click "Select a file to test" to upload an AAC file
-3. Click "Test File" to process it
-4. Check the results panel for page count, button count, and extracted texts
-
-### Automated Tests
-
-Click "Run All Browser Tests" to run automated checks:
-- Factory function tests
-- Extension support tests
-- Processor instantiation tests
-- Buffer handling tests
-
-### Node-Only Processors
-
-The following processors are **not available** in the browser:
-- **SnapProcessor** (.spb/.sps) - Requires SQLite
-- **TouchChatProcessor** (.ce) - Requires SQLite
-- **ExcelProcessor** (.xlsx) - Uses fs at top level
-
-### Notes
-
-- Gridset `.gridsetx` files (encrypted) are not supported in browser
-- All processors work with Buffer, Uint8Array, and ArrayBuffer inputs
-- File paths are not supported in browser (use file inputs or fetch)
+For browser testing, use the Vite demo in `examples/vitedemo`. It bundles the
+library and exercises real processors in a browser environment.

package/examples/vitedemo/README.md

@@ -5,7 +5,7 @@ A real browser demo that uses Vite to bundle AACProcessors for browser use.
 ## Features
 
 - ✅ **Real file processing** - Upload and process actual AAC files
-- ✅ **All browser-compatible processors** - Tests Dot, OPML, OBF/OBZ, Gridset, ApplePanels, AstericsGrid
+- ✅ **All browser-compatible processors** - Tests Dot, OPML, OBF/OBZ, Gridset, Snap, TouchChat, ApplePanels, AstericsGrid
 - ✅ **Interactive UI** - Drag & drop files, view pages and buttons
 - ✅ **Text-to-speech** - Click SPEAK buttons to hear messages (browser speech API)
 - ✅ **Navigation** - Click NAVIGATE buttons to jump between pages
@@ -35,15 +35,14 @@ The demo will open automatically at: http://localhost:3000
 This demo is intended for `npm run dev` only. The production build currently fails because the
 demo source includes strict TypeScript issues, so it will not work "out of the box."
 
-If you need a no-build browser check, use the browser test page served by:
-`node examples/browser-test-server.js`
+This demo is the recommended browser test environment.
 
 ## How to Use
 
 1. **Upload a file**
    - Drag & drop an AAC file onto the upload area
    - Or click to open file picker
-   - Supported formats: .dot, .opml, .obf, .obz, .gridset, .plist, .grd
+   - Supported formats: .dot, .opml, .obf, .obz, .gridset, .sps, .spb, .ce, .plist, .grd
 
 2. **Process the file**
    - Click "Process File" button
@@ -57,7 +56,7 @@ If you need a no-build browser check, use the browser test page served by:
 4. **Run compatibility tests**
    - Click "Run Compatibility Tests"
    - See test results in the left panel
-   - Tests all 6 browser-compatible processors
+   - Tests all browser-compatible processors
 
 ## Supported File Types
 
@@ -67,6 +66,8 @@ If you need a no-build browser check, use the browser test page served by:
 | OPML     | .opml           | OpmlProcessor           |
 | OBF/OBZ  | .obf, .obz      | ObfProcessor            |
 | Gridset  | .gridset        | GridsetProcessor        |
+| Snap     | .sps, .spb      | SnapProcessor           |
+| TouchChat| .ce             | TouchChatProcessor      |
 | Apple    | .plist          | ApplePanelsProcessor    |
 | Asterics | .grd            | AstericsGridProcessor   |
 
@@ -102,10 +103,15 @@ export default defineConfig({
 
 This allows direct TypeScript import without pre-building.
 
-### Import Example
+### Import Example (with SQLite WASM)
 
 ```typescript
-import { getProcessor } from 'aac-processors';
+import { configureSqlJs, getProcessor } from 'aac-processors';
+import sqlWasmUrl from 'sql.js/dist/sql-wasm.wasm?url';
+
+configureSqlJs({
+  locateFile: () => sqlWasmUrl
+});
 
 // Get processor for file type
 const processor = getProcessor('.obf');

package/examples/vitedemo/index.html

@@ -191,6 +191,48 @@
             font-size: 13px;
         }
 
+        .validation-panel {
+            margin-top: 15px;
+        }
+
+        .validation-summary {
+            background: #f8f9fa;
+            border-radius: 8px;
+            padding: 10px 12px;
+            font-size: 13px;
+            font-weight: 600;
+            margin-bottom: 10px;
+        }
+
+        .validation-summary.success {
+            border-left: 4px solid #2ecc71;
+            color: #2d7a4f;
+        }
+
+        .validation-summary.error {
+            border-left: 4px solid #e74c3c;
+            color: #b03a2e;
+        }
+
+        .validation-list {
+            max-height: 180px;
+            overflow-y: auto;
+            font-size: 12px;
+        }
+
+        .validation-item {
+            padding: 6px 0;
+            border-bottom: 1px solid #ececec;
+        }
+
+        .validation-item.warn {
+            color: #c18401;
+        }
+
+        .validation-item.error {
+            color: #b03a2e;
+        }
+
         .processor-name {
             font-weight: 600;
             color: #333;
@@ -423,11 +465,11 @@
                     <div class="upload-icon">📤</div>
                     <p><strong>Drop file here</strong> or click to upload</p>
                     <p style="font-size: 12px; color: #999; margin-top: 5px;">
-                        Supports: .dot, .opml, .obf, .obz, .gridset, .plist, .grd
+                        Supports: .dot, .opml, .obf, .obz, .gridset, .sps, .spb, .ce, .plist, .grd
                     </p>
                 </div>
 
-                <input type="file" id="fileInput" accept=".dot,.opml,.obf,.obz,.gridset,.plist,.grd">
+                <input type="file" id="fileInput" accept=".dot,.opml,.obf,.obz,.gridset,.sps,.spb,.ce,.plist,.grd">
 
                 <div id="fileInfo" style="display: none;">
                     <div class="processor-info">
@@ -437,6 +479,7 @@
                 </div>
 
                 <button class="btn" id="processBtn" disabled>🚀 Process File</button>
+                <button class="btn btn-secondary" id="validateBtn" disabled>✅ Validate File</button>
                 <button class="btn btn-secondary" id="runTestsBtn">🧪 Run Compatibility Tests</button>
                 <button class="btn btn-secondary" id="clearBtn">🗑️ Clear Results</button>
 
@@ -467,6 +510,12 @@
                     <div class="panel-title">Test Results</div>
                     <div id="testList"></div>
                 </div>
+
+                <div class="validation-panel" id="validationPanel" style="display: none;">
+                    <div class="panel-title">Validation</div>
+                    <div class="validation-summary" id="validationSummary"></div>
+                    <div class="validation-list" id="validationList"></div>
+                </div>
             </div>
 
             <!-- Right Panel: Results -->

package/examples/vitedemo/package-lock.json

@@ -11,6 +11,7 @@
         "@willwade/aac-processors": "file:../..",
         "events": "^3.3.0",
         "jszip": "^3.10.1",
+        "sql.js": "^1.13.0",
         "stream-browserify": "^3.0.0",
         "timers-browserify": "^2.0.12",
         "util": "^0.12.5"
@@ -34,6 +35,7 @@
         "fast-xml-parser": "^5.2.0",
         "jszip": "^3.10.1",
         "plist": "^3.1.0",
+        "sql.js": "^1.13.0",
         "xml2js": "^0.6.2",
         "yauzl": "^3.2.0"
       },
@@ -47,6 +49,7 @@
         "@types/jest": "^29.5.12",
         "@types/node": "^20.11.24",
         "@types/plist": "^3.0.5",
+        "@types/sql.js": "^1.4.9",
         "@typescript-eslint/eslint-plugin": "^7.1.0",
         "@typescript-eslint/parser": "^7.1.0",
         "eslint": "^8.56.0",
@@ -1547,6 +1550,12 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/sql.js": {
+      "version": "1.13.0",
+      "resolved": "https://registry.npmjs.org/sql.js/-/sql.js-1.13.0.tgz",
+      "integrity": "sha512-RJbVP1HRDlUUXahJ7VMTcu9Rm1Nzw+EBpoPr94vnbD4LwR715F3CcxE2G2k45PewcaZ57pjetYa+LoSJLAASgA==",
+      "license": "MIT"
+    },
     "node_modules/stream-browserify": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/stream-browserify/-/stream-browserify-3.0.0.tgz",

package/examples/vitedemo/package.json

@@ -16,6 +16,7 @@
     "@willwade/aac-processors": "file:../..",
     "events": "^3.3.0",
     "jszip": "^3.10.1",
+    "sql.js": "^1.13.0",
     "stream-browserify": "^3.0.0",
     "timers-browserify": "^2.0.12",
     "util": "^0.12.5"

package/examples/vitedemo/src/main.ts

@@ -66,23 +66,34 @@ if (typeof (window as any).Buffer === 'undefined') {
 }
 
 import {
+  configureSqlJs,
   getProcessor,
   getSupportedExtensions,
   DotProcessor,
   OpmlProcessor,
   ObfProcessor,
   GridsetProcessor,
+  SnapProcessor,
+  TouchChatProcessor,
   ApplePanelsProcessor,
   AstericsGridProcessor,
   AACTree,
   AACPage,
   AACButton
 } from 'aac-processors';
+import { validateFileOrBuffer, type ValidationResult } from 'aac-processors/validation';
+
+import sqlWasmUrl from 'sql.js/dist/sql-wasm.wasm?url';
+
+configureSqlJs({
+  locateFile: () => sqlWasmUrl
+});
 
 // UI Elements
 const dropArea = document.getElementById('dropArea') as HTMLElement;
 const fileInput = document.getElementById('fileInput') as HTMLInputElement;
 const processBtn = document.getElementById('processBtn') as HTMLButtonElement;
+const validateBtn = document.getElementById('validateBtn') as HTMLButtonElement;
 const runTestsBtn = document.getElementById('runTestsBtn') as HTMLButtonElement;
 const clearBtn = document.getElementById('clearBtn') as HTMLButtonElement;
 const fileInfo = document.getElementById('fileInfo') as HTMLElement;
@@ -93,6 +104,9 @@ const results = document.getElementById('results') as HTMLElement;
 const logPanel = document.getElementById('logPanel') as HTMLElement;
 const testResults = document.getElementById('testResults') as HTMLElement;
 const testList = document.getElementById('testList') as HTMLElement;
+const validationPanel = document.getElementById('validationPanel') as HTMLElement;
+const validationSummary = document.getElementById('validationSummary') as HTMLElement;
+const validationList = document.getElementById('validationList') as HTMLElement;
 const tabButtons = document.querySelectorAll('.tab-btn') as NodeListOf<HTMLButtonElement>;
 const inspectTab = document.getElementById('inspectTab') as HTMLElement;
 const pagesetTab = document.getElementById('pagesetTab') as HTMLElement;
@@ -209,6 +223,7 @@ function handleFile(file: File) {
     fileDetails.textContent = extension;
     fileInfo.style.display = 'block';
     processBtn.disabled = true;
+    validateBtn.disabled = true;
     return;
   }
 
@@ -219,12 +234,14 @@ function handleFile(file: File) {
     fileDetails.textContent = `${file.name} • ${formatFileSize(file.size)}`;
     fileInfo.style.display = 'block';
     processBtn.disabled = false;
+    validateBtn.disabled = false;
     currentSourceLabel = file.name;
 
     log(`Using processor: ${currentProcessor.constructor.name}`, 'success');
   } catch (error) {
     log(`Error getting processor: ${(error as Error).message}`, 'error');
     processBtn.disabled = true;
+    validateBtn.disabled = true;
   }
 }
 
@@ -305,6 +322,79 @@ processBtn.addEventListener('click', async () => {
   }
 });
 
+function collectValidationMessages(
+  result: ValidationResult,
+  prefix = ''
+): Array<{ type: 'error' | 'warn'; message: string }> {
+  const messages: Array<{ type: 'error' | 'warn'; message: string }> = [];
+  const label = prefix ? `${prefix}: ` : '';
+  result.results.forEach((check) => {
+    if (!check.valid && check.error) {
+      messages.push({ type: 'error', message: `${label}${check.description}: ${check.error}` });
+    }
+    if (check.warnings?.length) {
+      check.warnings.forEach((warning) => {
+        messages.push({ type: 'warn', message: `${label}${check.description}: ${warning}` });
+      });
+    }
+  });
+  result.sub_results?.forEach((sub) => {
+    const nextPrefix = `${label}${sub.filename || sub.format}`;
+    messages.push(...collectValidationMessages(sub, nextPrefix));
+  });
+  return messages;
+}
+
+function renderValidationResult(result: ValidationResult) {
+  validationPanel.style.display = 'block';
+  validationSummary.classList.remove('success', 'error');
+  validationSummary.classList.add(result.valid ? 'success' : 'error');
+  validationSummary.textContent = `${result.valid ? '✅ Valid' : '❌ Invalid'} • ${result.format.toUpperCase()} • ${result.errors} errors, ${result.warnings} warnings`;
+
+  validationList.innerHTML = '';
+  const messages = collectValidationMessages(result).slice(0, 30);
+  if (messages.length === 0) {
+    const empty = document.createElement('div');
+    empty.className = 'validation-item';
+    empty.textContent = 'No issues reported.';
+    validationList.appendChild(empty);
+    return;
+  }
+
+  messages.forEach((entry) => {
+    const item = document.createElement('div');
+    item.className = `validation-item ${entry.type}`;
+    item.textContent = entry.message;
+    validationList.appendChild(item);
+  });
+}
+
+validateBtn.addEventListener('click', async () => {
+  if (!currentFile) return;
+  log('Validating file...', 'info');
+
+  try {
+    validateBtn.disabled = true;
+    const arrayBuffer = await currentFile.arrayBuffer();
+    const result = await validateFileOrBuffer(new Uint8Array(arrayBuffer), currentFile.name);
+    renderValidationResult(result);
+    log(
+      `${result.valid ? '✅' : '❌'} Validation complete: ${result.errors} errors, ${result.warnings} warnings`,
+      result.valid ? 'success' : 'warn'
+    );
+  } catch (error) {
+    const errorMsg = (error as Error).message;
+    validationPanel.style.display = 'block';
+    validationSummary.classList.remove('success');
+    validationSummary.classList.add('error');
+    validationSummary.textContent = `❌ Validation failed: ${errorMsg}`;
+    validationList.innerHTML = '';
+    log(`❌ Validation failed: ${errorMsg}`, 'error');
+  } finally {
+    validateBtn.disabled = !currentFile;
+  }
+});
+
 // Display results
 function displayResults(tree: AACTree) {
   results.innerHTML = '';
@@ -414,6 +504,9 @@ clearBtn.addEventListener('click', () => {
   stats.style.display = 'none';
   results.innerHTML = '<p style="color: #999; text-align: center; padding: 40px;">Load a file to see its contents here</p>';
   testResults.style.display = 'none';
+  validationPanel.style.display = 'none';
+  validationSummary.textContent = '';
+  validationList.innerHTML = '';
   logPanel.innerHTML = '<div class="log-entry log-info">Cleared. Ready to process files...</div>';
   pagesetOutput.textContent = 'Generate or convert a pageset to preview the output JSON.';
   updateConvertButtons();
@@ -717,11 +810,15 @@ runTestsBtn.addEventListener('click', async () => {
         const opmlProc = getProcessor('.opml');
         const obfProc = getProcessor('.obf');
         const gridsetProc = getProcessor('.gridset');
+        const snapProc = getProcessor('.sps');
+        const touchChatProc = getProcessor('.ce');
         return (
           dotProc instanceof DotProcessor &&
           opmlProc instanceof OpmlProcessor &&
           obfProc instanceof ObfProcessor &&
-          gridsetProc instanceof GridsetProcessor
+          gridsetProc instanceof GridsetProcessor &&
+          snapProc instanceof SnapProcessor &&
+          touchChatProc instanceof TouchChatProcessor
         );
       }
     },
@@ -729,7 +826,18 @@ runTestsBtn.addEventListener('click', async () => {
       name: 'getSupportedExtensions() returns all extensions',
       fn: async () => {
         const extensions = getSupportedExtensions();
-        const expected = ['.dot', '.opml', '.obf', '.obz', '.gridset', '.plist', '.grd'];
+        const expected = [
+          '.dot',
+          '.opml',
+          '.obf',
+          '.obz',
+          '.gridset',
+          '.spb',
+          '.sps',
+          '.ce',
+          '.plist',
+          '.grd'
+        ];
         return expected.every((ext) => extensions.includes(ext));
       }
     },
@@ -777,6 +885,28 @@ runTestsBtn.addEventListener('click', async () => {
         }
       }
     },
+    {
+      name: 'SnapProcessor instantiation',
+      fn: async () => {
+        try {
+          new SnapProcessor();
+          return true;
+        } catch {
+          return false;
+        }
+      }
+    },
+    {
+      name: 'TouchChatProcessor instantiation',
+      fn: async () => {
+        try {
+          new TouchChatProcessor();
+          return true;
+        } catch {
+          return false;
+        }
+      }
+    },
     {
       name: 'ApplePanelsProcessor instantiation',
       fn: async () => {

package/examples/vitedemo/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/examples/vitedemo/vite.config.ts

@@ -3,13 +3,32 @@ import path from 'path';
 
 export default defineConfig({
   resolve: {
-    alias: {
-      'aac-processors': path.resolve(__dirname, '../../src/index.browser.ts'),
-      stream: path.resolve(__dirname, 'node_modules/stream-browserify'),
-      events: path.resolve(__dirname, 'node_modules/events'),
-      timers: path.resolve(__dirname, 'node_modules/timers-browserify'),
-      util: path.resolve(__dirname, 'node_modules/util')
-    }
+    alias: [
+      {
+        find: /^aac-processors\/validation$/,
+        replacement: path.resolve(__dirname, '../../src/validation.ts'),
+      },
+      {
+        find: /^aac-processors$/,
+        replacement: path.resolve(__dirname, '../../src/index.browser.ts'),
+      },
+      {
+        find: /^stream$/,
+        replacement: path.resolve(__dirname, 'node_modules/stream-browserify'),
+      },
+      {
+        find: /^events$/,
+        replacement: path.resolve(__dirname, 'node_modules/events'),
+      },
+      {
+        find: /^timers$/,
+        replacement: path.resolve(__dirname, 'node_modules/timers-browserify'),
+      },
+      {
+        find: /^util$/,
+        replacement: path.resolve(__dirname, 'node_modules/util'),
+      },
+    ],
   },
   optimizeDeps: {
     exclude: ['aac-processors'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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",
@@ -151,6 +151,7 @@
     "@types/jest": "^29.5.12",
     "@types/node": "^20.11.24",
     "@types/plist": "^3.0.5",
+    "@types/sql.js": "^1.4.9",
     "@typescript-eslint/eslint-plugin": "^7.1.0",
     "@typescript-eslint/parser": "^7.1.0",
     "eslint": "^8.56.0",
@@ -174,6 +175,7 @@
     "fast-xml-parser": "^5.2.0",
     "jszip": "^3.10.1",
     "plist": "^3.1.0",
+    "sql.js": "^1.13.0",
     "xml2js": "^0.6.2",
     "yauzl": "^3.2.0"
   },

package/examples/browser-test-server.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Simple HTTP server for testing AACProcessors in a browser
- *
- * Usage:
- *   node examples/browser-test-server.js
- *
- * Then open: http://localhost:8080/examples/browser-test.html
- */
-
-const http = require('http');
-const fs = require('fs');
-const path = require('path');
-
-const PORT = 8080;
-const MIME_TYPES = {
-    '.html': 'text/html',
-    '.js': 'text/javascript',
-    '.css': 'text/css',
-    '.json': 'application/json',
-    '.png': 'image/png',
-    '.jpg': 'image/jpg',
-    '.gif': 'image/gif',
-    '.svg': 'image/svg+xml',
-    '.ico': 'image/x-icon',
-};
-
-const server = http.createServer((req, res) => {
-    // Enable CORS
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-
-    if (req.method === 'OPTIONS') {
-        res.writeHead(200);
-        res.end();
-        return;
-    }
-
-    // Parse URL
-    let filePath = '.' + req.url;
-    if (filePath === './') {
-        filePath = './examples/browser-test.html';
-    }
-
-    // Get file extension
-    const extname = String(path.extname(filePath)).toLowerCase();
-    const contentType = MIME_TYPES[extname] || 'application/octet-stream';
-
-    // Read and serve file
-    fs.readFile(filePath, (error, content) => {
-        if (error) {
-            if (error.code === 'ENOENT') {
-                res.writeHead(404, { 'Content-Type': 'text/html' });
-                res.end('<h1>404 Not Found</h1>', 'utf-8');
-            } else {
-                res.writeHead(500);
-                res.end(`Server Error: ${error.code}`, 'utf-8');
-            }
-        } else {
-            res.writeHead(200, { 'Content-Type': contentType });
-            res.end(content, 'utf-8');
-        }
-    });
-});
-
-server.listen(PORT, () => {
-    console.log(`
-╔════════════════════════════════════════════════════════════╗
-║   AACProcessors Browser Test Server                       ║
-╠════════════════════════════════════════════════════════════╣
-║                                                            ║
-║   Server running at:                                       ║
-║   🌐 http://localhost:${PORT}/examples/browser-test.html           ║
-║                                                            ║
-║   Press Ctrl+C to stop                                     ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-    `);
-});