@willwade/aac-processors 0.1.20 → 0.1.21

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

@@ -0,0 +1,331 @@
+/**
+ * Grid 3 Symbol Extraction Strategy
+ *
+ * For converting Grid 3 gridsets to other formats (like Asterics),
+ * we need to handle symbol library references properly.
+ *
+ * Strategy:
+ * 1. Check if image is embedded in gridset (extract directly)
+ * 2. If symbol library reference:
+ *    a. Check if we can extract from .pix file (limited support)
+ *    b. Provide reference/URL for manual resolution
+ *    c. For Tawasol: provide alternative sources
+ */
+import { resolveSymbolReference, parseSymbolReference } from './symbols';
+import { defaultFileAdapter } from '../../utils/io';
+import { getZipAdapter } from '../../utils/zip';
+/**
+ * Known open-license symbol sources
+ */
+const OPEN_LICENSE_SYMBOLS = {
+    tawasl: {
+        name: 'Tawasol',
+        attribution: 'Tawasol symbols by Mada (Qatar Assistive Technology Center)',
+        license: 'CC BY-SA 4.0',
+        url: 'https://mada.org.qa/en/resources/tawasol-symbols',
+        alternativeSources: ['https://github.com/mada-qatar/Tawasol'],
+    },
+    blissx: {
+        name: 'Blissymbols',
+        attribution: 'Blissymbolics Communication International',
+        license: 'CC BY-ND 3.0',
+        url: 'https://blissymbolics.org',
+    },
+    symoji: {
+        name: 'Symoji',
+        attribution: 'Smartbox Assistive Technology',
+        license: 'Proprietary - Free use in Grid 3',
+    },
+};
+/**
+ * Extract image data for a button
+ * @param gridsetBuffer - Gridset ZIP buffer
+ * @param resolvedImageEntry - Path to embedded image in gridset
+ * @param symbolReference - Symbol library reference
+ * @param options - Extraction options
+ * @returns Extracted image data
+ */
+export async function extractButtonImage(gridsetBuffer, resolvedImageEntry, symbolReference, options = {}, fileAdapter = defaultFileAdapter, zipAdapter) {
+    // Priority 1: Use embedded image if available
+    if (resolvedImageEntry && options.preferEmbedded !== false) {
+        try {
+            const zip = zipAdapter
+                ? await zipAdapter(gridsetBuffer)
+                : await getZipAdapter(gridsetBuffer, fileAdapter);
+            const entries = zip.listFiles();
+            const entry = entries.find((e) => e === resolvedImageEntry);
+            if (entry) {
+                const data = Buffer.from(await zip.readFile(entry));
+                const format = detectImageFormat(data);
+                return {
+                    found: true,
+                    data,
+                    format,
+                    source: 'embedded',
+                    reference: resolvedImageEntry,
+                };
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to extract embedded image: ${String(error)}`);
+        }
+    }
+    // Priority 2: Check symbol library reference
+    if (symbolReference) {
+        return await extractSymbolLibraryImage(symbolReference, options);
+    }
+    // Not found
+    return {
+        found: false,
+        source: 'not-found',
+    };
+}
+/**
+ * Extract image from symbol library
+ * @param reference - Symbol reference like "[tawasl]/food/apple.png"
+ * @param options - Extraction options
+ * @returns Extracted image or reference info
+ */
+export async function extractSymbolLibraryImage(reference, options = {}) {
+    const ref = parseSymbolReferenceSafe(reference);
+    if (!ref || !ref.isValid) {
+        return {
+            found: false,
+            source: 'not-found',
+            reference,
+        };
+    }
+    // Get library metadata
+    const libInfo = OPEN_LICENSE_SYMBOLS[ref.library];
+    // Resolve symbol reference and extract from .symbols file
+    const resolved = await resolveSymbolReference(reference, {
+        grid3Path: options.grid3Path,
+    });
+    const metadata = {
+        library: ref.library,
+        symbolPath: ref.path,
+        attribution: libInfo?.attribution,
+        license: libInfo?.license,
+    };
+    if (!resolved.found) {
+        // Symbol not found in library
+        if (options.onMissingSymbol) {
+            options.onMissingSymbol(ref);
+        }
+        return {
+            found: false,
+            source: 'symbol-library',
+            reference: reference,
+            metadata,
+            error: resolved.error,
+        };
+    }
+    // Successfully extracted!
+    const data = resolved.data;
+    const format = data ? detectImageFormat(data) : 'unknown';
+    return {
+        found: true,
+        data,
+        format,
+        source: 'symbol-library',
+        reference: reference,
+        metadata,
+    };
+}
+/**
+ * Convert extracted image to Asterics Grid format
+ * @param extracted - Extracted image
+ * @returns GridImage object for Asterics
+ */
+export function convertToAstericsImage(extracted) {
+    const image = {};
+    if (extracted.found && extracted.data) {
+        // Embed as base64
+        image.data = Buffer.from(extracted.data).toString('base64');
+    }
+    // Even if embedded, add attribution for symbol libraries
+    if (extracted.source === 'symbol-library') {
+        if (extracted.metadata?.attribution) {
+            image.author = extracted.metadata.attribution;
+        }
+        if (extracted.metadata?.license) {
+            image.searchProviderName = extracted.metadata.license;
+        }
+    }
+    // If not found but we have a reference, keep it for manual handling
+    if (!extracted.found && extracted.reference) {
+        image.url = `symbol:${extracted.reference}`;
+        if (extracted.metadata?.attribution) {
+            image.author = extracted.metadata.attribution;
+        }
+    }
+    return image;
+}
+/**
+ * Analyze symbol usage for a gridset
+ * @param tree - AAC tree
+ * @returns Symbol usage report
+ */
+export function analyzeSymbolExtraction(tree) {
+    const report = {
+        total: 0,
+        embedded: 0,
+        symbolLibraries: 0,
+        notFound: 0,
+        byLibrary: {},
+        missingSymbols: [],
+    };
+    for (const pageId in tree.pages) {
+        const page = tree.pages[pageId];
+        if (page.buttons) {
+            for (const button of page.buttons) {
+                report.total++;
+                // Embedded image
+                if (button.resolvedImageEntry && !button.symbolLibrary) {
+                    report.embedded++;
+                    continue;
+                }
+                // Symbol library reference
+                if (button.symbolLibrary) {
+                    report.symbolLibraries++;
+                    report.byLibrary[button.symbolLibrary] =
+                        (report.byLibrary[button.symbolLibrary] || 0) + 1;
+                    const ref = `[${button.symbolLibrary}]${button.symbolPath || ''}`;
+                    const libInfo = OPEN_LICENSE_SYMBOLS[button.symbolLibrary];
+                    report.missingSymbols.push({
+                        reference: ref,
+                        library: button.symbolLibrary,
+                        path: button.symbolPath || '',
+                        attribution: libInfo?.attribution,
+                        license: libInfo?.license,
+                    });
+                    continue;
+                }
+                // Not found
+                if (!button.resolvedImageEntry && !button.symbolLibrary) {
+                    report.notFound++;
+                }
+            }
+        }
+    }
+    return report;
+}
+/**
+ * Suggest extraction strategy based on report
+ */
+export function suggestExtractionStrategy(report) {
+    const suggestions = [];
+    if (report.embedded > 0) {
+        suggestions.push(`✓ Can extract ${report.embedded} embedded images directly`);
+    }
+    if (report.symbolLibraries > 0) {
+        suggestions.push(`⚠ ${report.symbolLibraries} symbol library references found:`);
+        Object.entries(report.byLibrary).forEach(([lib, count]) => {
+            const libInfo = OPEN_LICENSE_SYMBOLS[lib];
+            if (libInfo) {
+                suggestions.push(`  - ${lib}: ${count} symbols (${libInfo.license})`);
+                if (libInfo.alternativeSources) {
+                    suggestions.push(`    Alternative: ${libInfo.alternativeSources.join(', ')}`);
+                }
+            }
+            else {
+                suggestions.push(`  - ${lib}: ${count} symbols (Proprietary - requires Grid 3)`);
+            }
+        });
+    }
+    if (report.notFound > 0) {
+        suggestions.push(`✗ ${report.notFound} images not found`);
+    }
+    return suggestions.join('\n');
+}
+/**
+ * Detect image format from buffer
+ */
+function detectImageFormat(buffer) {
+    if (buffer.length < 4)
+        return 'unknown';
+    // PNG: 89 50 4E 47
+    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+        return 'png';
+    }
+    // JPEG: FF D8 FF
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return 'jpg';
+    }
+    // GIF: 47 49 46 38
+    if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
+        return 'gif';
+    }
+    // SVG (check for <svg text)
+    const header = buffer.slice(0, Math.min(100, buffer.length)).toString('ascii').toLowerCase();
+    if (header.includes('<svg')) {
+        return 'svg';
+    }
+    return 'unknown';
+}
+/**
+ * Safe parse of symbol reference
+ */
+function parseSymbolReferenceSafe(reference) {
+    try {
+        return parseSymbolReference(reference);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Export symbol references to CSV for manual extraction
+ */
+export function exportSymbolReferencesToCsv(report, outputPath, fileAdapter = defaultFileAdapter) {
+    const { writeTextToPath } = fileAdapter;
+    const lines = ['Reference,Library,Path,Attribution,License'];
+    for (const symbol of report.missingSymbols) {
+        lines.push(`"${symbol.reference}","${symbol.library}","${symbol.path}","${symbol.attribution || ''}","${symbol.license || ''}"`);
+    }
+    writeTextToPath(outputPath, lines.join('\n'));
+}
+export function createSymbolManifest(tree, gridsetName) {
+    const manifest = {
+        generatedAt: new Date().toISOString(),
+        gridset: gridsetName,
+        totalSymbols: 0,
+        embedded: 0,
+        fromLibraries: 0,
+        libraries: {},
+        symbols: [],
+    };
+    for (const pageId in tree.pages) {
+        const page = tree.pages[pageId];
+        if (page.buttons) {
+            for (const button of page.buttons) {
+                manifest.totalSymbols++;
+                if (button.resolvedImageEntry && !button.symbolLibrary) {
+                    manifest.embedded++;
+                    continue;
+                }
+                if (button.symbolLibrary) {
+                    manifest.fromLibraries++;
+                    if (!manifest.libraries[button.symbolLibrary]) {
+                        const libInfo = OPEN_LICENSE_SYMBOLS[button.symbolLibrary];
+                        manifest.libraries[button.symbolLibrary] = {
+                            count: 0,
+                            attribution: libInfo?.attribution,
+                            license: libInfo?.license,
+                            url: libInfo?.url,
+                        };
+                    }
+                    manifest.libraries[button.symbolLibrary].count++;
+                    const ref = `[${button.symbolLibrary}]${button.symbolPath || ''}`;
+                    manifest.symbols.push({
+                        pageId,
+                        buttonId: button.id,
+                        reference: ref,
+                        label: button.label,
+                    });
+                }
+            }
+        }
+    }
+    return manifest;
+}

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

@@ -0,0 +1,248 @@
+/**
+ * Grid 3 Symbol Search Implementation
+ *
+ * The .pix files are simple text mappings:
+ * searchTerm=symbolFilename=searchTerm
+ *
+ * Example:
+ * above bw=above bw.png=above bw
+ * active family=active family.png=active family
+ */
+import { defaultFileAdapter } from '../../utils/io';
+/**
+ * Parse a .pix file into search index
+ * @param pixFilePath - Path to .pix file
+ * @returns Search index
+ */
+export function parsePixFile(pixFilePath, fileAdapter = defaultFileAdapter) {
+    const { readTextFromInput, basename } = fileAdapter;
+    const content = readTextFromInput(pixFilePath);
+    const library = basename(pixFilePath, '.pix');
+    const searchTerms = new Map();
+    const filenames = new Map();
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('encoding=')) {
+            continue;
+        }
+        // Format: searchTerm=symbolFilename=searchTerm
+        const parts = trimmed.split('=');
+        if (parts.length >= 3) {
+            const searchTerm = parts[0];
+            const symbolFilename = parts[1];
+            const displayName = parts[2];
+            searchTerms.set(searchTerm.toLowerCase(), symbolFilename);
+            filenames.set(symbolFilename, displayName || searchTerm);
+        }
+    }
+    return { library, searchTerms, filenames };
+}
+/**
+ * Load search indexes for all available libraries
+ * @param options - Search options
+ * @returns Map of library name to search index
+ */
+export function loadSearchIndexes(options = {}, fileAdapter = defaultFileAdapter) {
+    const { listDir, pathExists, join, basename } = fileAdapter;
+    const { grid3Path, locale = 'en-GB', libraries: specifiedLibs } = options;
+    if (!grid3Path) {
+        throw new Error('grid3Path is required for symbol search');
+    }
+    const searchIndexesDir = join(grid3Path, 'Locale', locale, 'symbolsearch');
+    if (!pathExists(searchIndexesDir)) {
+        throw new Error(`Symbol search directory not found: ${searchIndexesDir}`);
+    }
+    const indexes = new Map();
+    const files = listDir(searchIndexesDir);
+    for (const file of files) {
+        if (!file.endsWith('.pix')) {
+            continue;
+        }
+        const libraryName = basename(file, '.pix');
+        // Filter libraries if specified
+        if (specifiedLibs && specifiedLibs.length > 0) {
+            if (!specifiedLibs.some((lib) => lib.toLowerCase() === libraryName.toLowerCase())) {
+                continue;
+            }
+        }
+        try {
+            const pixFilePath = join(searchIndexesDir, file);
+            const index = parsePixFile(pixFilePath);
+            indexes.set(libraryName, index);
+        }
+        catch (error) {
+            console.warn(`Failed to load index for ${libraryName}:`, error);
+        }
+    }
+    return indexes;
+}
+/**
+ * Search for symbols by term
+ * @param searchTerm - Term to search for
+ * @param options - Search options
+ * @returns Array of search results
+ */
+export function searchSymbols(searchTerm, options = {}) {
+    const indexes = loadSearchIndexes(options);
+    const results = [];
+    const lowerSearchTerm = searchTerm.toLowerCase().trim();
+    const limit = options.limit || 100;
+    for (const [libraryName, index] of indexes.entries()) {
+        // Exact match first
+        if (index.searchTerms.has(lowerSearchTerm)) {
+            const symbolFilename = index.searchTerms.get(lowerSearchTerm);
+            if (symbolFilename) {
+                results.push({
+                    searchTerm: lowerSearchTerm,
+                    symbolFilename,
+                    displayName: index.filenames.get(symbolFilename) || lowerSearchTerm,
+                    library: libraryName,
+                    exactMatch: true,
+                });
+            }
+        }
+        // Fuzzy match if enabled
+        if (options.fuzzyMatch !== false) {
+            for (const [term, symbolFilename] of index.searchTerms.entries()) {
+                if (term.includes(lowerSearchTerm) || lowerSearchTerm.includes(term)) {
+                    // Skip if already added as exact match
+                    if (results.some((r) => r.library === libraryName && r.symbolFilename === symbolFilename)) {
+                        continue;
+                    }
+                    results.push({
+                        searchTerm: lowerSearchTerm,
+                        symbolFilename,
+                        displayName: index.filenames.get(symbolFilename) || term,
+                        library: libraryName,
+                        exactMatch: false,
+                    });
+                }
+            }
+        }
+    }
+    // Sort by exact match first, then by library
+    results.sort((a, b) => {
+        if (a.exactMatch !== b.exactMatch) {
+            return a.exactMatch ? -1 : 1;
+        }
+        return a.library.localeCompare(b.library);
+    });
+    return results.slice(0, limit);
+}
+/**
+ * Get symbol filename for a specific search term
+ * @param searchTerm - Search term to look up
+ * @param library - Library name
+ * @param options - Search options
+ * @returns Symbol filename or undefined
+ */
+export function getSymbolFilename(searchTerm, library, options = {}) {
+    const indexes = loadSearchIndexes({
+        ...options,
+        libraries: [library],
+    });
+    const index = indexes.get(library.toLowerCase());
+    if (!index) {
+        return undefined;
+    }
+    return index.searchTerms.get(searchTerm.toLowerCase());
+}
+/**
+ * Get display name for a symbol filename
+ * @param symbolFilename - Symbol filename (e.g., "above bw.png")
+ * @param library - Library name
+ * @param options - Search options
+ * @returns Display name or undefined
+ */
+export function getSymbolDisplayName(symbolFilename, library, options = {}) {
+    const indexes = loadSearchIndexes({
+        ...options,
+        libraries: [library],
+    });
+    const index = indexes.get(library.toLowerCase());
+    if (!index) {
+        return undefined;
+    }
+    return index.filenames.get(symbolFilename);
+}
+/**
+ * Get all search terms for a library
+ * @param library - Library name
+ * @param options - Search options
+ * @returns Array of search terms
+ */
+export function getAllSearchTerms(library, options = {}) {
+    const indexes = loadSearchIndexes({
+        ...options,
+        libraries: [library],
+    });
+    const index = indexes.get(library.toLowerCase());
+    if (!index) {
+        return [];
+    }
+    return Array.from(index.searchTerms.keys());
+}
+/**
+ * Search suggestions (autocomplete)
+ * @param partialTerm - Partial search term
+ * @param options - Search options
+ * @returns Array of suggested terms
+ */
+export function getSearchSuggestions(partialTerm, options = {}) {
+    const indexes = loadSearchIndexes(options);
+    const suggestions = new Set();
+    const lowerPartial = partialTerm.toLowerCase().trim();
+    for (const index of indexes.values()) {
+        for (const term of index.searchTerms.keys()) {
+            if (term.startsWith(lowerPartial)) {
+                suggestions.add(term);
+            }
+        }
+    }
+    return Array.from(suggestions).sort().slice(0, 20);
+}
+/**
+ * Search for symbols and return results with library references
+ * @param searchTerm - Term to search for
+ * @param options - Search options
+ * @returns Array of full symbol references
+ */
+export function searchSymbolsWithReferences(searchTerm, options = {}) {
+    const results = searchSymbols(searchTerm, options);
+    return results.map((r) => `[${r.library}]${r.symbolFilename}`);
+}
+/**
+ * Count symbols in each library
+ * @param options - Search options
+ * @returns Map of library name to symbol count
+ */
+export function countLibrarySymbols(options = {}) {
+    const indexes = loadSearchIndexes(options);
+    const counts = new Map();
+    for (const [libraryName, index] of indexes.entries()) {
+        counts.set(libraryName, index.searchTerms.size);
+    }
+    return counts;
+}
+/**
+ * Get symbol search statistics
+ * @param options - Search options
+ * @returns Statistics about available symbols
+ */
+export function getSymbolSearchStats(options = {}) {
+    const indexes = loadSearchIndexes(options);
+    const stats = {
+        totalLibraries: indexes.size,
+        totalSymbols: 0,
+        libraries: {},
+    };
+    for (const [libraryName, index] of indexes.entries()) {
+        stats.totalSymbols += index.searchTerms.size;
+        stats.libraries[libraryName] = {
+            symbolCount: index.searchTerms.size,
+            exampleTerms: Array.from(index.searchTerms.keys()).slice(0, 10),
+        };
+    }
+    return stats;
+}