@willwade/aac-processors 0.0.10 → 0.0.12

package/dist/processors/gridset/resolver.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveGrid3CellImage = resolveGrid3CellImage;
+exports.isSymbolLibraryReference = isSymbolLibraryReference;
+exports.parseImageSymbolReference = parseImageSymbolReference;
+const symbols_1 = require("./symbols");
 function normalizeZipPathLocal(p) {
     const unified = p.replace(/\\/g, '/');
     try {
@@ -44,8 +47,22 @@ function resolveGrid3CellImage(zip, args, zipEntries) {
     const y = args.y;
     const entries = new Set(listZipEntries(zip, zipEntries));
     const has = (p) => entries.has(normalizeZipPathLocal(p));
-    // Built-in resource like [grid3x]...
+    // Built-in resource like [grid3x]... (old format, not symbol library)
+    // Check this BEFORE general symbol references to avoid misclassification
     if (imageName && imageName.startsWith('[')) {
+        // Check if it's a symbol library reference like [widgit]/food/apple.png
+        // Symbol library references have a path after the library name
+        if ((0, symbols_1.isSymbolReference)(imageName)) {
+            const parsed = (0, symbols_1.parseSymbolReference)(imageName);
+            // If it's grid3x, it's a built-in resource, not a symbol library
+            if (parsed.library !== 'grid3x') {
+                // Symbol library references are NOT stored as files in the gridset
+                // They are resolved from the external Grid 3 installation
+                // Return null to indicate this is an external symbol reference
+                return null;
+            }
+        }
+        // For grid3x and other built-in resources, use the builtinHandler
         if (args.builtinHandler) {
             const mapped = args.builtinHandler(imageName);
             if (mapped)
@@ -102,3 +119,24 @@ function resolveGrid3CellImage(zip, args, zipEntries) {
     }
     return null;
 }
+/**
+ * Check if an image reference is a symbol library reference
+ * @param imageName - Image reference from Grid 3
+ * @returns True if it's a symbol library reference
+ */
+function isSymbolLibraryReference(imageName) {
+    if (!imageName)
+        return false;
+    return (0, symbols_1.isSymbolReference)(imageName.trim());
+}
+/**
+ * Parse a symbol library reference from an image name
+ * @param imageName - Image reference from Grid 3
+ * @returns Parsed reference or null if not a symbol reference
+ */
+function parseImageSymbolReference(imageName) {
+    if (!isSymbolLibraryReference(imageName)) {
+        return null;
+    }
+    return (0, symbols_1.parseSymbolReference)(imageName.trim());
+}

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

@@ -4,6 +4,27 @@
  * Utilities for creating and managing Grid3 styles, including default styles,
  * style XML generation, and style conversion utilities.
  */
+/**
+ * Cell background shapes supported by Grid 3
+ * Maps to Grid 3's CellBackgroundShape enum
+ */
+export declare enum CellBackgroundShape {
+    Rectangle = 0,
+    RoundedRectangle = 1,
+    FoldedCorner = 2,
+    Octagon = 3,
+    Folder = 4,
+    Ellipse = 5,
+    SpeechBubble = 6,
+    ThoughtBubble = 7,
+    Star = 8,
+    Circle = 9,
+    ColouredCorner = 10
+}
+/**
+ * Human-readable shape names
+ */
+export declare const SHAPE_NAMES: Record<CellBackgroundShape, string>;
 /**
  * Grid3 Style object structure
  */
@@ -14,6 +35,7 @@ export interface Grid3Style {
     FontColour?: string;
     FontName?: string;
     FontSize?: string | number;
+    BackgroundShape?: CellBackgroundShape;
 }
 /**
  * Default Grid3 styles for common use cases

package/dist/processors/gridset/styleHelpers.js

@@ -6,11 +6,45 @@
  * style XML generation, and style conversion utilities.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureAlphaChannel = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = void 0;
+exports.ensureAlphaChannel = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = exports.SHAPE_NAMES = exports.CellBackgroundShape = void 0;
 exports.createDefaultStylesXml = createDefaultStylesXml;
 exports.createCategoryStyle = createCategoryStyle;
 const fast_xml_parser_1 = require("fast-xml-parser");
 const colorUtils_1 = require("./colorUtils");
+/**
+ * Cell background shapes supported by Grid 3
+ * Maps to Grid 3's CellBackgroundShape enum
+ */
+var CellBackgroundShape;
+(function (CellBackgroundShape) {
+    CellBackgroundShape[CellBackgroundShape["Rectangle"] = 0] = "Rectangle";
+    CellBackgroundShape[CellBackgroundShape["RoundedRectangle"] = 1] = "RoundedRectangle";
+    CellBackgroundShape[CellBackgroundShape["FoldedCorner"] = 2] = "FoldedCorner";
+    CellBackgroundShape[CellBackgroundShape["Octagon"] = 3] = "Octagon";
+    CellBackgroundShape[CellBackgroundShape["Folder"] = 4] = "Folder";
+    CellBackgroundShape[CellBackgroundShape["Ellipse"] = 5] = "Ellipse";
+    CellBackgroundShape[CellBackgroundShape["SpeechBubble"] = 6] = "SpeechBubble";
+    CellBackgroundShape[CellBackgroundShape["ThoughtBubble"] = 7] = "ThoughtBubble";
+    CellBackgroundShape[CellBackgroundShape["Star"] = 8] = "Star";
+    CellBackgroundShape[CellBackgroundShape["Circle"] = 9] = "Circle";
+    CellBackgroundShape[CellBackgroundShape["ColouredCorner"] = 10] = "ColouredCorner";
+})(CellBackgroundShape || (exports.CellBackgroundShape = CellBackgroundShape = {}));
+/**
+ * Human-readable shape names
+ */
+exports.SHAPE_NAMES = {
+    [CellBackgroundShape.Rectangle]: 'Rectangle',
+    [CellBackgroundShape.RoundedRectangle]: 'Rounded Rectangle',
+    [CellBackgroundShape.FoldedCorner]: 'Folded Corner',
+    [CellBackgroundShape.Octagon]: 'Octagon',
+    [CellBackgroundShape.Folder]: 'Folder',
+    [CellBackgroundShape.Ellipse]: 'Ellipse',
+    [CellBackgroundShape.SpeechBubble]: 'Speech Bubble',
+    [CellBackgroundShape.ThoughtBubble]: 'Thought Bubble',
+    [CellBackgroundShape.Star]: 'Star',
+    [CellBackgroundShape.Circle]: 'Circle',
+    [CellBackgroundShape.ColouredCorner]: 'Coloured Corner',
+};
 /**
  * Default Grid3 styles for common use cases
  * Colors are in 8-digit ARGB hex format (#AARRGGBBFF)

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

@@ -0,0 +1,121 @@
+/**
+ * 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 { type SymbolReference } from './symbols';
+/**
+ * Image extraction result
+ */
+export interface ExtractedImage {
+    found: boolean;
+    data?: Buffer;
+    format?: 'png' | 'jpg' | 'jpeg' | 'gif' | 'svg' | 'unknown';
+    source: 'embedded' | 'symbol-library' | 'external-file' | 'not-found';
+    reference?: string;
+    error?: string;
+    metadata?: {
+        library?: string;
+        symbolPath?: string;
+        attribution?: string;
+        license?: string;
+    };
+}
+/**
+ * Symbol extraction options
+ */
+export interface SymbolExtractionOptions {
+    grid3Path?: string;
+    locale?: string;
+    preferEmbedded?: boolean;
+    includeAttribution?: boolean;
+    /** For Tawasol: try to find alternative sources */
+    tryAlternativeSources?: boolean;
+    /** Callback for when symbol needs manual extraction */
+    onMissingSymbol?: (ref: SymbolReference) => void;
+}
+/**
+ * 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 declare function extractButtonImage(gridsetBuffer: Buffer, resolvedImageEntry: string | undefined, symbolReference: string | undefined, options?: SymbolExtractionOptions): ExtractedImage;
+/**
+ * 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 declare function extractSymbolLibraryImage(reference: string, options?: SymbolExtractionOptions): ExtractedImage;
+/**
+ * Convert extracted image to Asterics Grid format
+ * @param extracted - Extracted image
+ * @returns GridImage object for Asterics
+ */
+export declare function convertToAstericsImage(extracted: ExtractedImage): any;
+/**
+ * Generate a symbol extraction report
+ * Useful for identifying which symbols need manual extraction
+ */
+export interface SymbolReport {
+    total: number;
+    embedded: number;
+    symbolLibraries: number;
+    notFound: number;
+    byLibrary: Record<string, number>;
+    missingSymbols: Array<{
+        reference: string;
+        library: string;
+        path: string;
+        attribution?: string;
+        license?: string;
+    }>;
+}
+/**
+ * Analyze symbol usage for a gridset
+ * @param tree - AAC tree
+ * @returns Symbol usage report
+ */
+export declare function analyzeSymbolExtraction(tree: any): SymbolReport;
+/**
+ * Suggest extraction strategy based on report
+ */
+export declare function suggestExtractionStrategy(report: SymbolReport): string;
+/**
+ * Export symbol references to CSV for manual extraction
+ */
+export declare function exportSymbolReferencesToCsv(report: SymbolReport, outputPath: string): void;
+/**
+ * Create a manifest file for missing symbols
+ */
+export interface SymbolManifest {
+    generatedAt: string;
+    gridset: string;
+    totalSymbols: number;
+    embedded: number;
+    fromLibraries: number;
+    libraries: Record<string, {
+        count: number;
+        attribution?: string;
+        license?: string;
+        url?: string;
+    }>;
+    symbols: Array<{
+        pageId: string;
+        buttonId: string;
+        reference: string;
+        label?: string;
+    }>;
+}
+export declare function createSymbolManifest(tree: any, gridsetName: string): SymbolManifest;

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;
+}