@willwade/aac-processors 0.0.30 → 0.1.1

package/docs/PAGESET_GETTING_STARTED.md

@@ -0,0 +1,185 @@
+# AAC Pageset Quickstart (Node + Browser)
+
+This guide shows two simple ways to generate or convert AAC pagesets using `aac-processors`:
+
+- Node.js: full conversion between formats (read + write)
+- Browser: generate or export to OBF/OBZ in-memory (downloadable)
+
+If you need lossless conversion in the browser, use a Node/worker service for the save step (file I/O is required for most formats).
+
+## Node.js: Convert and Generate Pagesets
+
+### Install
+
+```bash
+npm install aac-processors
+```
+
+### Convert a Gridset to OBF
+
+```ts
+import { getProcessor, ObfProcessor } from 'aac-processors';
+
+async function convertGridsetToObf() {
+  const sourcePath = './input/example.gridset';
+  const targetPath = './output/example.obf';
+
+  const sourceProcessor = getProcessor(sourcePath); // GridsetProcessor
+  const tree = await sourceProcessor.loadIntoTree(sourcePath);
+
+  const obf = new ObfProcessor();
+  await obf.saveFromTree(tree, targetPath);
+
+  console.log('Saved:', targetPath);
+}
+
+convertGridsetToObf().catch(console.error);
+```
+
+### Generate a Simple Pageset and Save as OBZ
+
+```ts
+import { AACTree, AACPage, AACButton, ObfProcessor } from 'aac-processors';
+
+async function generateObz() {
+  const tree = new AACTree();
+  tree.metadata = { name: 'Starter Demo', locale: 'en' };
+
+  const hello = new AACButton({ id: 'hello', label: 'Hello', message: 'Hello' });
+  const thanks = new AACButton({ id: 'thanks', label: 'Thanks', message: 'Thank you' });
+
+  const home = new AACPage({
+    id: 'home',
+    name: 'Home',
+    buttons: [hello, thanks],
+    grid: [[hello, thanks]],
+  });
+
+  tree.addPage(home);
+  tree.rootId = 'home';
+
+  const obf = new ObfProcessor();
+  await obf.saveFromTree(tree, './output/starter.obz');
+
+  console.log('Saved: ./output/starter.obz');
+}
+
+generateObz().catch(console.error);
+```
+
+## Browser: Generate or Convert to OBF/OBZ
+
+In the browser you can still parse files and build an `AACTree`, but most processors cannot write to disk (no `fs`).
+The example below generates an `AACTree`, converts it to OBF JSON in-memory, and downloads it.
+
+If you need full conversions in a browser app, do the save step in Node (server or worker).
+
+### Generate a Pageset and Download as OBF
+
+```ts
+import { AACTree, AACPage, AACButton, ObfProcessor } from 'aac-processors';
+
+function downloadBlob(data: BlobPart, filename: string, type: string) {
+  const blob = new Blob([data], { type });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+function buildSampleTree() {
+  const tree = new AACTree();
+  tree.metadata = { name: 'Browser Demo', locale: 'en' };
+
+  const hello = new AACButton({ id: 'hello', label: 'Hello', message: 'Hello' });
+  const yes = new AACButton({ id: 'yes', label: 'Yes', message: 'Yes' });
+
+  const home = new AACPage({
+    id: 'home',
+    name: 'Home',
+    buttons: [hello, yes],
+    grid: [[hello, yes]],
+  });
+
+  tree.addPage(home);
+  tree.rootId = 'home';
+  return tree;
+}
+
+async function exportObf(tree: AACTree) {
+  // This mirrors the browser demo approach: create OBF JSON and download.
+  // ObfProcessor.saveFromTree writes to disk, so we build a board in-memory.
+  const obf = new ObfProcessor() as ObfProcessor & {
+    createObfBoardFromPage?: (page: AACPage, fallbackName: string, metadata?: AACTree['metadata']) => any;
+  };
+
+  const rootPage = tree.rootId ? tree.getPage(tree.rootId) : Object.values(tree.pages)[0];
+  const board = obf.createObfBoardFromPage
+    ? obf.createObfBoardFromPage(rootPage!, 'Board', tree.metadata)
+    : {
+        format: 'open-board-0.1',
+        id: rootPage?.id ?? 'board',
+        name: rootPage?.name ?? 'Board',
+        locale: tree.metadata?.locale || 'en',
+        grid: { rows: 1, columns: rootPage?.buttons.length ?? 0, order: [] },
+        buttons: (rootPage?.buttons || []).map((button) => ({
+          id: button.id,
+          label: button.label,
+          vocalization: button.message || button.label,
+        })),
+      };
+
+  const json = JSON.stringify(board, null, 2);
+  downloadBlob(json, 'browser-demo.obf', 'application/json');
+}
+
+const tree = buildSampleTree();
+exportObf(tree);
+```
+
+### Convert an Uploaded Pageset to OBZ (Browser)
+
+This uses the same idea as the Vite demo: parse any supported file into a tree,
+then export OBF/OBZ in-memory and download.
+
+```ts
+import { getProcessor, ObfProcessor, type AACTree, type AACPage } from 'aac-processors';
+import JSZip from 'jszip';
+
+async function convertToObz(file: File) {
+  const extension = '.' + file.name.split('.').pop();
+  const processor = getProcessor(extension);
+  const buffer = await file.arrayBuffer();
+  const tree = await processor.loadIntoTree(buffer);
+
+  const obf = new ObfProcessor() as ObfProcessor & {
+    createObfBoardFromPage?: (page: AACPage, fallbackName: string, metadata?: AACTree['metadata']) => any;
+  };
+
+  const zip = new JSZip();
+  Object.values(tree.pages).forEach((page) => {
+    const board = obf.createObfBoardFromPage
+      ? obf.createObfBoardFromPage(page, 'Board', tree.metadata)
+      : { format: 'open-board-0.1', id: page.id, name: page.name, grid: { rows: 0, columns: 0, order: [] }, buttons: [] };
+    zip.file(`${page.id}.obf`, JSON.stringify(board, null, 2));
+  });
+
+  const data = await zip.generateAsync({ type: 'uint8array' });
+  const blob = new Blob([data], { type: 'application/zip' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'converted.obz';
+  a.click();
+  URL.revokeObjectURL(url);
+}
+```
+
+## Tips
+
+- Use `loadIntoTree()` to normalize different AAC formats into one structure.
+- In Node, `saveFromTree()` lets you write to OBF, OBZ, Gridset, etc.
+- In the browser, build the output in memory and offer it for download.
+- For full-fidelity conversions in the browser, use a server-side endpoint to save files.

package/examples/README.md

@@ -48,3 +48,80 @@ These pagesets are used by:
 - Integration examples
 
 To run demo scripts that use these pagesets, see the [scripts/README.md](../scripts/README.md).
+
+## Browser Testing
+
+### ⚠️ 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)

package/examples/browser-test-server.js

@@ -0,0 +1,81 @@
+#!/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                                     ║
+║                                                            ║
+╚════════════════════════════════════════════════════════════╝
+    `);
+});

package/examples/browser-test.html

@@ -0,0 +1,331 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AAC Processors - Browser Compatibility Test</title>
+    <style>
+        body {
+            font-family: system-ui, -apple-system, sans-serif;
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 20px;
+            background: #f5f5f5;
+        }
+        h1 {
+            color: #333;
+            border-bottom: 2px solid #007bff;
+            padding-bottom: 10px;
+        }
+        .test-section {
+            background: white;
+            border-radius: 8px;
+            padding: 20px;
+            margin: 20px 0;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }
+        .file-input {
+            margin: 10px 0;
+        }
+        .file-input label {
+            display: block;
+            font-weight: 600;
+            margin-bottom: 5px;
+            color: #555;
+        }
+        .file-input input {
+            display: block;
+            width: 100%;
+            padding: 8px;
+            border: 2px solid #ddd;
+            border-radius: 4px;
+        }
+        .test-button {
+            background: #007bff;
+            color: white;
+            border: none;
+            padding: 10px 20px;
+            border-radius: 4px;
+            cursor: pointer;
+            font-size: 14px;
+            margin-top: 10px;
+        }
+        .test-button:hover {
+            background: #0056b3;
+        }
+        .test-button:disabled {
+            background: #ccc;
+            cursor: not-allowed;
+        }
+        .result {
+            margin-top: 15px;
+            padding: 15px;
+            border-radius: 4px;
+            font-family: 'Monaco', 'Menlo', monospace;
+            font-size: 13px;
+            white-space: pre-wrap;
+            word-wrap: break-word;
+        }
+        .result.success {
+            background: #d4edda;
+            border: 1px solid #c3e6cb;
+            color: #155724;
+        }
+        .result.error {
+            background: #f8d7da;
+            border: 1px solid #f5c6cb;
+            color: #721c24;
+        }
+        .result.info {
+            background: #d1ecf1;
+            border: 1px solid #bee5eb;
+            color: #0c5460;
+        }
+        .info-box {
+            background: #fff3cd;
+            border: 1px solid #ffc107;
+            border-radius: 4px;
+            padding: 15px;
+            margin: 20px 0;
+        }
+        .info-box strong {
+            display: block;
+            margin-bottom: 5px;
+        }
+        .processor-list {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+            gap: 10px;
+            margin: 15px 0;
+        }
+        .processor-item {
+            background: #e7f3ff;
+            padding: 10px;
+            border-radius: 4px;
+            border-left: 3px solid #007bff;
+        }
+        .processor-item.supported {
+            border-left-color: #28a745;
+            background: #d4edda;
+        }
+    </style>
+</head>
+<body>
+    <h1>🧪 AAC Processors - Browser Compatibility Test</h1>
+
+    <div class="info-box">
+        <strong>ℹ️ About this test page</strong>
+        This page tests AACProcessors in a real browser environment. It verifies that processors
+        can load files using browser APIs (File, Blob, ArrayBuffer) without any Node.js dependencies.
+    </div>
+
+    <div class="test-section">
+        <h2>Supported Processors</h2>
+        <div class="processor-list">
+            <div class="processor-item supported">✅ DotProcessor (.dot)</div>
+            <div class="processor-item supported">✅ OpmlProcessor (.opml)</div>
+            <div class="processor-item supported">✅ ObfProcessor (.obf/.obz)</div>
+            <div class="processor-item supported">✅ GridsetProcessor (.gridset)</div>
+            <div class="processor-item supported">✅ ApplePanelsProcessor (.plist)</div>
+            <div class="processor-item supported">✅ AstericsGridProcessor (.grd)</div>
+        </div>
+        <p style="color: #666; font-size: 14px;">
+            <strong>Note:</strong> SnapProcessor and TouchChatProcessor require Node.js (sqlite).
+            GridsetProcessor .gridsetx files require Node.js (crypto).
+        </p>
+    </div>
+
+    <div class="test-section">
+        <h2>📁 Load and Test Files</h2>
+
+        <div class="file-input">
+            <label for="fileInput">Select a file to test:</label>
+            <input type="file" id="fileInput" accept=".dot,.opml,.obf,.obz,.gridset,.plist,.grd">
+        </div>
+
+        <button id="testButton" class="test-button" disabled>Test File</button>
+        <button id="clearButton" class="test-button">Clear Results</button>
+
+        <div id="result" class="result" style="display: none;"></div>
+    </div>
+
+    <div class="test-section">
+        <h2>🧪 Automated Tests</h2>
+        <button id="runAllTests" class="test-button">Run All Browser Tests</button>
+        <div id="testResults" class="result" style="display: none;"></div>
+    </div>
+
+    <!-- Note: Using a module loader to handle CommonJS exports -->
+    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+    <script data-type="module" type="text/babel" data-presets="env">
+        // Since the build outputs CommonJS, we need to dynamically import the processors
+        // For now, we'll use a simpler approach with inline test code
+
+        class AACProcessorsTest {
+            constructor() {
+                this.processors = {};
+                this.init();
+            }
+
+            async init() {
+                // Initialize processors after DOM is ready
+                const fileInput = document.getElementById('fileInput');
+                const testButton = document.getElementById('testButton');
+                const clearButton = document.getElementById('clearButton');
+                const runAllTestsButton = document.getElementById('runAllTests');
+
+                fileInput.addEventListener('change', (e) => this.handleFileSelect(e));
+                testButton.addEventListener('click', () => this.testFile());
+                clearButton.addEventListener('click', () => this.clearResults());
+                runAllTestsButton.addEventListener('click', () => this.runAutomatedTests());
+
+                console.log('AAC Processors Browser Test Page Ready');
+                console.log('Note: This page tests the library structure but cannot run actual processors without a bundler.');
+                console.log('For actual browser usage, see docs/BROWSER_USAGE.md for bundler setup.');
+            }
+
+            showMessage(message, type = 'info') {
+                const resultDiv = document.getElementById('result');
+                resultDiv.style.display = 'block';
+                resultDiv.className = `result ${type}`;
+                resultDiv.textContent = message;
+            }
+
+            showTestResults(results) {
+                const testResultsDiv = document.getElementById('testResults');
+                testResultsDiv.style.display = 'block';
+                testResultsDiv.className = 'result info';
+                testResultsDiv.textContent = results;
+            }
+
+            handleFileSelect(event) {
+                const file = event.target.files[0];
+                const testButton = document.getElementById('testButton');
+
+                if (file) {
+                    testButton.disabled = false;
+                    this.showMessage(`Selected: ${file.name} (${file.size} bytes)\n\nNote: Actual processing requires a bundler (webpack/vite/rollup) to bundle the library for browser use.`, 'info');
+                } else {
+                    testButton.disabled = true;
+                    document.getElementById('result').style.display = 'none';
+                }
+            }
+
+            async testFile() {
+                this.showMessage(
+                    '⚠️ Browser Build Note\n\n' +
+                    'The current build outputs CommonJS modules which require a bundler.\n\n' +
+                    'To use AACProcessors in a browser:\n\n' +
+                    '1. Use a bundler (webpack, vite, rollup, etc.)\n' +
+                    '2. Or use a CDN bundle (when available)\n' +
+                    '3. See docs/BROWSER_USAGE.md for complete setup instructions\n\n' +
+                    'Example with Vite:\n' +
+                    '```js\n' +
+                    'import { getProcessor } from "aac-processors";\n' +
+                    'const processor = getProcessor(".obf");\n' +
+                    '```',
+                    'info'
+                );
+            }
+
+            clearResults() {
+                document.getElementById('result').style.display = 'none';
+                document.getElementById('testResults').style.display = 'none';
+            }
+
+            async runAutomatedTests() {
+                const results = [];
+                results.push('=== AACProcessors Browser Test ===\n');
+                results.push('\nℹ️ Library Structure Tests:\n');
+
+                // Test 1: Check if dist files exist
+                results.push('1. Checking build files...');
+                try {
+                    const response = await fetch('../dist/index.browser.js');
+                    if (response.ok) {
+                        const content = await response.text();
+                        const hasExports = content.includes('exports.getProcessor') &&
+                                         content.includes('exports.GridsetProcessor') &&
+                                         content.includes('exports.ObfProcessor');
+
+                        if (hasExports) {
+                            results.push('   ✅ PASS: Browser build exists with expected exports');
+                            results.push(`   ✅ Size: ${(content.length / 1024).toFixed(2)} KB`);
+                        } else {
+                            results.push('   ⚠️  WARNING: Some exports may be missing');
+                        }
+                    } else {
+                        results.push('   ❌ FAIL: Browser build not found');
+                    }
+                } catch (error) {
+                    results.push(`   ❌ FAIL: ${error.message}`);
+                }
+
+                // Test 2: Check type definitions
+                results.push('\n2. Checking TypeScript definitions...');
+                try {
+                    const response = await fetch('../dist/index.browser.d.ts');
+                    if (response.ok) {
+                        const content = await response.text();
+                        const hasTypes = content.includes('getProcessor') &&
+                                       content.includes('DotProcessor') &&
+                                       content.includes('GridsetProcessor');
+
+                        if (hasTypes) {
+                            results.push('   ✅ PASS: Type definitions exist');
+                        } else {
+                            results.push('   ⚠️  WARNING: Some type definitions may be missing');
+                        }
+                    } else {
+                        results.push('   ❌ FAIL: Type definitions not found');
+                    }
+                } catch (error) {
+                    results.push(`   ❌ FAIL: ${error.message}`);
+                }
+
+                // Test 3: Processor count
+                results.push('\n3. Counting processors...');
+                try {
+                    const response = await fetch('../dist/index.browser.js');
+                    const content = await response.text();
+                    const processorExports = content.match(/exports\.\w+Processor/g);
+
+                    if (processorExports) {
+                        const uniqueProcessors = [...new Set(processorExports)];
+                        results.push(`   ✅ Found ${uniqueProcessors.length} processor exports:`);
+                        uniqueProcessors.forEach(p => results.push(`   - ${p.replace('exports.', '')}`));
+                    }
+                } catch (error) {
+                    results.push(`   ❌ FAIL: ${error.message}`);
+                }
+
+                results.push('\n=== Setup Instructions ===\n');
+                results.push('To use AACProcessors in your browser project:\n\n');
+                results.push('1. Install with npm: npm install @willwade/aac-processors\n');
+                results.push('2. Use a bundler (Vite example):\n');
+                results.push('   ```js\n');
+                results.push('   // vite.config.js\n');
+                results.push('   export default {\n');
+                results.push('     resolve: {\n');
+                results.push('       alias: {\n');
+                results.push('         "aac-processors": path.resolve(__dirname, "node_modules/@willwade/aac-processors/src/index.browser.ts")\n');
+                results.push('       }\n');
+                results.push('     }\n');
+                results.push('   }\n');
+                results.push('   ```\n\n');
+                results.push('3. Or use a CDN bundle (when available)\n\n');
+                results.push('See docs/BROWSER_USAGE.md for complete guide.');
+
+                this.showTestResults(results.join('\n'));
+            }
+        }
+
+        // Initialize when DOM is ready
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', () => new AACProcessorsTest());
+        } else {
+            new AACProcessorsTest();
+        }
+    </script>
+</body>
+</html>