@willwade/aac-processors 0.0.10 → 0.0.11

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;

package/dist/processors/gridset/symbolSearch.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * 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
+ */
+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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePixFile = parsePixFile;
+exports.loadSearchIndexes = loadSearchIndexes;
+exports.searchSymbols = searchSymbols;
+exports.getSymbolFilename = getSymbolFilename;
+exports.getSymbolDisplayName = getSymbolDisplayName;
+exports.getAllSearchTerms = getAllSearchTerms;
+exports.getSearchSuggestions = getSearchSuggestions;
+exports.searchSymbolsWithReferences = searchSymbolsWithReferences;
+exports.countLibrarySymbols = countLibrarySymbols;
+exports.getSymbolSearchStats = getSymbolSearchStats;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Parse a .pix file into search index
+ * @param pixFilePath - Path to .pix file
+ * @returns Search index
+ */
+function parsePixFile(pixFilePath) {
+    const content = fs.readFileSync(pixFilePath, 'utf-8');
+    const library = path.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
+ */
+function loadSearchIndexes(options = {}) {
+    const { grid3Path, locale = 'en-GB', libraries: specifiedLibs } = options;
+    if (!grid3Path) {
+        throw new Error('grid3Path is required for symbol search');
+    }
+    const searchIndexesDir = path.join(grid3Path, 'Locale', locale, 'symbolsearch');
+    if (!fs.existsSync(searchIndexesDir)) {
+        throw new Error(`Symbol search directory not found: ${searchIndexesDir}`);
+    }
+    const indexes = new Map();
+    const files = fs.readdirSync(searchIndexesDir);
+    for (const file of files) {
+        if (!file.endsWith('.pix')) {
+            continue;
+        }
+        const libraryName = path.basename(file, '.pix');
+        // Filter libraries if specified
+        if (specifiedLibs && specifiedLibs.length > 0) {
+            if (!specifiedLibs.some((lib) => lib.toLowerCase() === libraryName.toLowerCase())) {
+                continue;
+            }
+        }
+        try {
+            const pixFilePath = path.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
+ */
+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);
+            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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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;
+}

package/dist/processors/gridset/symbols.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Grid 3 Symbol Library Resolution
+ *
+ * Grid 3 uses symbol libraries stored as .pix files in the installation directory.
+ * Symbol references in Grid files use the format: [library]/path/to/symbol.png
+ *
+ * Examples:
+ * - [widgit]/food/apple.png
+ * - [tawasl]/above bw.png
+ * - [ssnaps]963.jpg
+ * - [grid3x]/folder/document.png
+ *
+ * This module provides symbol resolution and metadata extraction.
+ */
+/**
+ * Known symbol libraries in Grid 3
+ */
+export declare const SYMBOL_LIBRARIES: {
+    readonly WIDGIT: "widgit";
+    readonly TAWASL: "tawasl";
+    readonly SSNAPS: "ssnaps";
+    readonly GRID3X: "grid3x";
+    readonly GRID2X: "grid2x";
+    readonly BLISSX: "blissx";
+    readonly EYEGAZ: "eyegaz";
+    readonly INTERL: "interl";
+    readonly METACM: "metacm";
+    readonly MJPCS: "mjpcs#";
+    readonly PCSHC: "pcshc#";
+    readonly PCSTL: "pcstl#";
+    readonly SESENS: "sesens";
+    readonly SSTIX: "sstix#";
+    readonly SYMOJI: "symoji";
+};
+export type SymbolLibraryName = (typeof SYMBOL_LIBRARIES)[keyof typeof SYMBOL_LIBRARIES];
+/**
+ * Symbol reference parsed from Grid 3 format
+ */
+export interface SymbolReference {
+    library: string;
+    path: string;
+    fullReference: string;
+    isValid: boolean;
+}
+/**
+ * Symbol library information
+ */
+export interface SymbolLibraryInfo {
+    name: string;
+    pixFile: string;
+    exists: boolean;
+    size: number;
+    locale: string;
+}
+/**
+ * Symbol resolution options
+ */
+export interface SymbolResolutionOptions {
+    grid3Path?: string;
+    symbolDir?: string;
+    locale?: string;
+    fallbackToEmbed?: boolean;
+}
+/**
+ * Symbol resolution result
+ */
+export interface SymbolResolutionResult {
+    reference: SymbolReference;
+    found: boolean;
+    path?: string;
+    data?: Buffer;
+    libraryInfo?: SymbolLibraryInfo;
+    error?: string;
+}
+/**
+ * Default locale to use
+ */
+export declare const DEFAULT_LOCALE = "en-GB";
+/**
+ * Parse a symbol reference string
+ * @param reference - Symbol reference like "[widgit]/food/apple.png"
+ * @returns Parsed symbol reference
+ */
+export declare function parseSymbolReference(reference: string): SymbolReference;
+/**
+ * Check if a string is a symbol library reference
+ * @param reference - String to check
+ * @returns True if it's a symbol reference like [widgit]/...
+ */
+export declare function isSymbolReference(reference: string): boolean;
+/**
+ * Get the default Grid 3 installation path for the current platform
+ * @returns Default Grid 3 path or empty string if not found
+ */
+export declare function getDefaultGrid3Path(): string;
+/**
+ * Get the Symbol Libraries directory path
+ * Contains .symbols ZIP archives with actual image files
+ * @param grid3Path - Grid 3 installation path
+ * @returns Path to Symbol Libraries directory (e.g., "C:\...\Grid 3\Resources\Symbols")
+ */
+export declare function getSymbolLibrariesDir(grid3Path: string): string;
+/**
+ * Get the symbol search indexes directory path for a given locale
+ * Contains .pix index files for searching symbols
+ * @param grid3Path - Grid 3 installation path
+ * @param locale - Locale code (e.g., 'en-GB')
+ * @returns Path to symbol search indexes directory (e.g., "C:\...\Grid 3\Locale\en-GB\symbolsearch")
+ */
+export declare function getSymbolSearchIndexesDir(grid3Path: string, locale?: string): string;
+/**
+ * Get all available symbol libraries in the Grid 3 installation
+ * @param options - Resolution options
+ * @returns Array of symbol library information
+ */
+export declare function getAvailableSymbolLibraries(options?: SymbolResolutionOptions): SymbolLibraryInfo[];
+/**
+ * Check if a symbol library exists
+ * @param libraryName - Name of the library (e.g., 'widgit', 'tawasl')
+ * @param options - Resolution options
+ * @returns Symbol library info or undefined if not found
+ */
+export declare function getSymbolLibraryInfo(libraryName: string, options?: SymbolResolutionOptions): SymbolLibraryInfo | undefined;
+/**
+ * Resolve a symbol reference to extract the actual image data
+ * @param reference - Symbol reference like "[tawasl]/above bw.png"
+ * @param options - Resolution options
+ * @returns Resolution result with image data if found
+ */
+export declare function resolveSymbolReference(reference: string, options?: SymbolResolutionOptions): SymbolResolutionResult;
+/**
+ * Get all symbol references from a gridset
+ * This scans button images for symbol references
+ * @param tree - AAC tree from loaded gridset
+ * @returns Array of unique symbol references
+ */
+export declare function extractSymbolReferences(tree: any): string[];
+/**
+ * Create a symbol reference from library and path
+ * @param library - Library name
+ * @param symbolPath - Path within the library
+ * @returns Formatted symbol reference
+ */
+export declare function createSymbolReference(library: string, symbolPath: string): string;
+/**
+ * Get the library name from a symbol reference
+ * @param reference - Symbol reference
+ * @returns Library name or empty string
+ */
+export declare function getSymbolLibraryName(reference: string): string;
+/**
+ * Get the symbol path from a symbol reference
+ * @param reference - Symbol reference
+ * @returns Symbol path or empty string
+ */
+export declare function getSymbolPath(reference: string): string;
+/**
+ * Check if a symbol library is one of the known Grid 3 libraries
+ * @param libraryName - Library name to check
+ * @returns True if it's a known library
+ */
+export declare function isKnownSymbolLibrary(libraryName: string): boolean;
+/**
+ * Get display name for a symbol library
+ * @param libraryName - Library name
+ * @returns Human-readable display name
+ */
+export declare function getSymbolLibraryDisplayName(libraryName: string): string;
+/**
+ * Analyze symbol usage in a gridset
+ * @param tree - AAC tree from loaded gridset
+ * @returns Symbol usage statistics
+ */
+export interface SymbolUsageStats {
+    totalSymbols: number;
+    byLibrary: Record<string, number>;
+    uniqueReferences: string[];
+    librariesUsed: string[];
+}
+export declare function analyzeSymbolUsage(tree: any): SymbolUsageStats;
+/**
+ * Convert symbol reference to filename for embedded images
+ * Grid 3 sometimes embeds symbols with special naming
+ * @param reference - Symbol reference
+ * @param cellX - Cell X coordinate
+ * @param cellY - Cell Y coordinate
+ * @returns Generated filename
+ */
+export declare function symbolReferenceToFilename(reference: string, cellX: number, cellY: number): string;
+/**
+ * @deprecated Use getSymbolLibrariesDir() instead - more descriptive name
+ * Get the Symbols directory path (where .symbols ZIP archives are)
+ */
+export declare function getSymbolsDir(grid3Path: string): string;
+/**
+ * @deprecated Use getSymbolSearchIndexesDir() instead - more descriptive name
+ * Get the symbol search directory for a given locale (where .pix index files are)
+ */
+export declare function getSymbolSearchDir(grid3Path: string, locale?: string): string;