@willwade/aac-processors 0.0.9 → 0.0.11

package/dist/processors/gridset/symbolExtractor.js

@@ -0,0 +1,362 @@
+"use strict";
+/**
+ * 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
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractButtonImage = extractButtonImage;
+exports.extractSymbolLibraryImage = extractSymbolLibraryImage;
+exports.convertToAstericsImage = convertToAstericsImage;
+exports.analyzeSymbolExtraction = analyzeSymbolExtraction;
+exports.suggestExtractionStrategy = suggestExtractionStrategy;
+exports.exportSymbolReferencesToCsv = exportSymbolReferencesToCsv;
+exports.createSymbolManifest = createSymbolManifest;
+const fs = __importStar(require("fs"));
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const symbols_1 = require("./symbols");
+/**
+ * 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
+ */
+function extractButtonImage(gridsetBuffer, resolvedImageEntry, symbolReference, options = {}) {
+    // Priority 1: Use embedded image if available
+    if (resolvedImageEntry && options.preferEmbedded !== false) {
+        try {
+            const zip = new adm_zip_1.default(gridsetBuffer);
+            const entries = zip.getEntries();
+            const entry = entries.find((e) => e.entryName === resolvedImageEntry);
+            if (entry) {
+                const data = entry.getData();
+                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 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
+ */
+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 = (0, symbols_1.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 format = detectImageFormat(resolved.data);
+    return {
+        found: true,
+        data: resolved.data,
+        format,
+        source: 'symbol-library',
+        reference: reference,
+        metadata,
+    };
+}
+/**
+ * Convert extracted image to Asterics Grid format
+ * @param extracted - Extracted image
+ * @returns GridImage object for Asterics
+ */
+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
+ */
+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
+ */
+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 (0, symbols_1.parseSymbolReference)(reference);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Export symbol references to CSV for manual extraction
+ */
+function exportSymbolReferencesToCsv(report, outputPath) {
+    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 || ''}"`);
+    }
+    fs.writeFileSync(outputPath, lines.join('\n'));
+}
+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/processors/gridset/symbolSearch.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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
+ */
+/**
+ * Symbol search result
+ */
+export interface SymbolSearchResult {
+    searchTerm: string;
+    symbolFilename: string;
+    displayName: string;
+    library: string;
+    exactMatch: boolean;
+}
+/**
+ * Symbol search options
+ */
+export interface SymbolSearchOptions {
+    grid3Path?: string;
+    locale?: string;
+    libraries?: string[];
+    limit?: number;
+    fuzzyMatch?: boolean;
+}
+/**
+ * Search index for a single library
+ */
+export interface LibrarySearchIndex {
+    library: string;
+    searchTerms: Map<string, string>;
+    filenames: Map<string, string>;
+}
+/**
+ * Parse a .pix file into search index
+ * @param pixFilePath - Path to .pix file
+ * @returns Search index
+ */
+export declare function parsePixFile(pixFilePath: string): LibrarySearchIndex;
+/**
+ * Load search indexes for all available libraries
+ * @param options - Search options
+ * @returns Map of library name to search index
+ */
+export declare function loadSearchIndexes(options?: SymbolSearchOptions): Map<string, LibrarySearchIndex>;
+/**
+ * Search for symbols by term
+ * @param searchTerm - Term to search for
+ * @param options - Search options
+ * @returns Array of search results
+ */
+export declare function searchSymbols(searchTerm: string, options?: SymbolSearchOptions): SymbolSearchResult[];
+/**
+ * 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 declare function getSymbolFilename(searchTerm: string, library: string, options?: SymbolSearchOptions): string | undefined;
+/**
+ * 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 declare function getSymbolDisplayName(symbolFilename: string, library: string, options?: SymbolSearchOptions): string | undefined;
+/**
+ * Get all search terms for a library
+ * @param library - Library name
+ * @param options - Search options
+ * @returns Array of search terms
+ */
+export declare function getAllSearchTerms(library: string, options?: SymbolSearchOptions): string[];
+/**
+ * Search suggestions (autocomplete)
+ * @param partialTerm - Partial search term
+ * @param options - Search options
+ * @returns Array of suggested terms
+ */
+export declare function getSearchSuggestions(partialTerm: string, options?: SymbolSearchOptions): string[];
+/**
+ * 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 declare function searchSymbolsWithReferences(searchTerm: string, options?: SymbolSearchOptions): string[];
+/**
+ * Count symbols in each library
+ * @param options - Search options
+ * @returns Map of library name to symbol count
+ */
+export declare function countLibrarySymbols(options?: SymbolSearchOptions): Map<string, number>;
+/**
+ * Get statistics about symbol libraries
+ */
+export interface SymbolSearchStats {
+    totalLibraries: number;
+    totalSymbols: number;
+    libraries: Record<string, {
+        symbolCount: number;
+        exampleTerms: string[];
+    }>;
+}
+/**
+ * Get symbol search statistics
+ * @param options - Search options
+ * @returns Statistics about available symbols
+ */
+export declare function getSymbolSearchStats(options?: SymbolSearchOptions): SymbolSearchStats;