Merge pull request #16 from willwade/full-browser-migration

Full browser migration

Author: willwade

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';
 

docs/BROWSER_USAGE.md

@@ -565,14 +565,7 @@ async function safeLoadFile(file) {
 
 ## Testing
 
-See [Browser Test Page](../examples/browser-test.html) for interactive testing.
-
-To run the test server:
-```bash
-node examples/browser-test-server.js
-```
-
-Then open: http://localhost:8080/examples/browser-test.html
+Use the Vite demo in `examples/vitedemo` for interactive browser testing.
 
 ## Troubleshooting
 
@@ -614,5 +607,4 @@ await processor.loadIntoTree(uint8Array);
 
 - [API Documentation](./API.md)
 - [Examples](../examples/)
-- [Browser Test Page](../examples/browser-test.html)
-- [Test Server](../examples/browser-test-server.js)
+- [Vite Browser Demo](../examples/vitedemo)

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.

examples/browser-test-server.js

@@ -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');

examples/vitedemo/README.md

@@ -423,11 +423,11 @@ <h1>🎯 AAC Processors Browser Demo</h1>
                     <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">

examples/vitedemo/index.html

@@ -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"