@willwade/aac-processors 0.1.9 → 0.1.10

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

@@ -67,6 +67,14 @@ export function resolveGrid3CellImage(zip, args, zipEntries) {
     }
     // Direct declared file
     if (imageName) {
+        // Check for partial image names that start with '-' (common in Grid3)
+        // These are coordinate-based suffixes like "-0-text-0.png" that need
+        // to be prefixed with the cell coordinates
+        if (imageName.startsWith('-') && x != null && y != null) {
+            const coordPrefixed = joinBaseDir(baseDir, `${x}-${y}${imageName}`);
+            if (has(coordPrefixed))
+                return coordPrefixed;
+        }
         const p1 = joinBaseDir(baseDir, imageName);
         if (has(p1))
             return p1;

package/dist/gridset.d.ts

@@ -15,3 +15,4 @@ export { parseSymbolReference, isSymbolReference, resolveSymbolReference, getAva
 export { extractButtonImage, extractSymbolLibraryImage, convertToAstericsImage, analyzeSymbolExtraction, suggestExtractionStrategy, exportSymbolReferencesToCsv, createSymbolManifest, } from './processors/gridset/symbolExtractor';
 export { parsePixFile, loadSearchIndexes, searchSymbols, searchSymbolsWithReferences, getSymbolFilename, getSymbolDisplayName, getAllSearchTerms, getSearchSuggestions, countLibrarySymbols, getSymbolSearchStats, } from './processors/gridset/symbolSearch';
 export { resolveGridsetPassword, resolveGridsetPasswordFromEnv, } from './processors/gridset/password';
+export { auditGridsetImages, formatImageAuditSummary, type ImageAuditResult, type ImageIssue, } from './processors/gridset/imageDebug';

package/dist/gridset.js

@@ -7,7 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCommandsByPlugin = exports.getCommandDefinition = exports.detectCommand = exports.AUTOCONTENT_TYPES = exports.LIVECELL_TYPES = exports.WORKSPACE_TYPES = exports.Grid3CellType = exports.isRegularCell = exports.isAutoContentCell = exports.isLiveCell = exports.isWorkspaceCell = exports.getCellTypeDisplayName = exports.detectPluginCellType = exports.ensureAlphaChannelFromStyles = exports.SHAPE_NAMES = exports.CellBackgroundShape = exports.createCategoryStyle = exports.createDefaultStylesXml = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = exports.ensureAlphaChannel = exports.normalizeColor = exports.darkenColor = exports.toHexColor = exports.clampAlpha = exports.clampColorChannel = exports.channelToHex = exports.rgbaToHex = exports.getNamedColor = exports.wordlistToXml = exports.updateWordlist = exports.extractWordlists = exports.createWordlist = exports.createFileMapXml = exports.createSettingsXml = exports.generateGrid3Guid = exports.readAllGrid3History = exports.readGrid3HistoryForUser = exports.readGrid3History = exports.isGrid3Installed = exports.findGrid3UserHistory = exports.findGrid3Vocabularies = exports.findGrid3Users = exports.findGrid3HistoryDatabases = exports.findGrid3UserPaths = exports.getCommonDocumentsPath = exports.openImage = exports.getAllowedImageEntries = exports.getPageTokenImageMap = exports.GridsetProcessor = void 0;
-exports.resolveGridsetPasswordFromEnv = exports.resolveGridsetPassword = exports.getSymbolSearchStats = exports.countLibrarySymbols = exports.getSearchSuggestions = exports.getAllSearchTerms = exports.getSymbolDisplayName = exports.getSymbolFilename = exports.searchSymbolsWithReferences = exports.searchSymbols = exports.loadSearchIndexes = exports.parsePixFile = exports.createSymbolManifest = exports.exportSymbolReferencesToCsv = exports.suggestExtractionStrategy = exports.analyzeSymbolExtraction = exports.convertToAstericsImage = exports.extractSymbolLibraryImage = exports.extractButtonImage = exports.getSymbolSearchDir = exports.getSymbolsDir = exports.resolveGrid3CellImage = exports.parseImageSymbolReference = exports.isSymbolLibraryReference = exports.SYMBOL_LIBRARIES = exports.symbolReferenceToFilename = exports.getSymbolSearchIndexesDir = exports.getSymbolLibrariesDir = exports.getDefaultGrid3Path = exports.getSymbolLibraryDisplayName = exports.isKnownSymbolLibrary = exports.getSymbolPath = exports.getSymbolLibraryName = exports.createSymbolReference = exports.analyzeSymbolUsage = exports.extractSymbolReferences = exports.getSymbolLibraryInfo = exports.getAvailableSymbolLibraries = exports.resolveSymbolReference = exports.isSymbolReference = exports.parseSymbolReference = exports.Grid3CommandCategory = exports.GRID3_COMMANDS = exports.extractCommandParameters = exports.getAllPluginIds = exports.getAllCommandIds = exports.getCommandsByCategory = void 0;
+exports.formatImageAuditSummary = exports.auditGridsetImages = exports.resolveGridsetPasswordFromEnv = exports.resolveGridsetPassword = exports.getSymbolSearchStats = exports.countLibrarySymbols = exports.getSearchSuggestions = exports.getAllSearchTerms = exports.getSymbolDisplayName = exports.getSymbolFilename = exports.searchSymbolsWithReferences = exports.searchSymbols = exports.loadSearchIndexes = exports.parsePixFile = exports.createSymbolManifest = exports.exportSymbolReferencesToCsv = exports.suggestExtractionStrategy = exports.analyzeSymbolExtraction = exports.convertToAstericsImage = exports.extractSymbolLibraryImage = exports.extractButtonImage = exports.getSymbolSearchDir = exports.getSymbolsDir = exports.resolveGrid3CellImage = exports.parseImageSymbolReference = exports.isSymbolLibraryReference = exports.SYMBOL_LIBRARIES = exports.symbolReferenceToFilename = exports.getSymbolSearchIndexesDir = exports.getSymbolLibrariesDir = exports.getDefaultGrid3Path = exports.getSymbolLibraryDisplayName = exports.isKnownSymbolLibrary = exports.getSymbolPath = exports.getSymbolLibraryName = exports.createSymbolReference = exports.analyzeSymbolUsage = exports.extractSymbolReferences = exports.getSymbolLibraryInfo = exports.getAvailableSymbolLibraries = exports.resolveSymbolReference = exports.isSymbolReference = exports.parseSymbolReference = exports.Grid3CommandCategory = exports.GRID3_COMMANDS = exports.extractCommandParameters = exports.getAllPluginIds = exports.getAllCommandIds = exports.getCommandsByCategory = void 0;
 // Processor class
 var gridsetProcessor_1 = require("./processors/gridsetProcessor");
 Object.defineProperty(exports, "GridsetProcessor", { enumerable: true, get: function () { return gridsetProcessor_1.GridsetProcessor; } });
@@ -128,3 +128,7 @@ Object.defineProperty(exports, "getSymbolSearchStats", { enumerable: true, get:
 var password_1 = require("./processors/gridset/password");
 Object.defineProperty(exports, "resolveGridsetPassword", { enumerable: true, get: function () { return password_1.resolveGridsetPassword; } });
 Object.defineProperty(exports, "resolveGridsetPasswordFromEnv", { enumerable: true, get: function () { return password_1.resolveGridsetPasswordFromEnv; } });
+// === Image Debugging ===
+var imageDebug_1 = require("./processors/gridset/imageDebug");
+Object.defineProperty(exports, "auditGridsetImages", { enumerable: true, get: function () { return imageDebug_1.auditGridsetImages; } });
+Object.defineProperty(exports, "formatImageAuditSummary", { enumerable: true, get: function () { return imageDebug_1.formatImageAuditSummary; } });

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

@@ -0,0 +1,41 @@
+/**
+ * Image Debugging Utilities for Grid3 Files
+ *
+ * These utilities help developers understand why images might not be resolving
+ * correctly in Grid3 gridsets.
+ */
+export interface ImageIssue {
+    gridName: string;
+    cellX: number;
+    cellY: number;
+    declaredImage: string | undefined;
+    expectedPaths: string[];
+    issue: 'not_found' | 'symbol_library' | 'external_reference';
+    suggestion: string;
+}
+export interface ImageAuditResult {
+    totalCells: number;
+    cellsWithImages: number;
+    resolvedImages: number;
+    unresolvedImages: number;
+    issues: ImageIssue[];
+    availableImages: string[];
+}
+/**
+ * Audit a gridset file to find image resolution issues
+ *
+ * @param gridsetBuffer - The gridset file as a Buffer
+ * @returns Detailed audit report of image issues
+ *
+ * @example
+ * const audit = await auditGridsetImages(gridsetBuffer);
+ * console.log(`Found ${audit.unresolvedImages} unresolved images`);
+ * audit.issues.forEach(issue => {
+ *   console.log(`Cell (${issue.cellX}, ${issue.cellY}): ${issue.suggestion}`);
+ * });
+ */
+export declare function auditGridsetImages(gridsetBuffer: Uint8Array, password?: string | undefined): Promise<ImageAuditResult>;
+/**
+ * Get a human-readable summary of image audit results
+ */
+export declare function formatImageAuditSummary(audit: ImageAuditResult): string;

package/dist/processors/gridset/imageDebug.js

@@ -0,0 +1,222 @@
+"use strict";
+/**
+ * Image Debugging Utilities for Grid3 Files
+ *
+ * These utilities help developers understand why images might not be resolving
+ * correctly in Grid3 gridsets.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditGridsetImages = auditGridsetImages;
+exports.formatImageAuditSummary = formatImageAuditSummary;
+const zip_1 = require("../../utils/zip");
+const password_1 = require("./password");
+const password_2 = require("./password");
+const fast_xml_parser_1 = require("fast-xml-parser");
+const io_1 = require("../../utils/io");
+/**
+ * Audit a gridset file to find image resolution issues
+ *
+ * @param gridsetBuffer - The gridset file as a Buffer
+ * @returns Detailed audit report of image issues
+ *
+ * @example
+ * const audit = await auditGridsetImages(gridsetBuffer);
+ * console.log(`Found ${audit.unresolvedImages} unresolved images`);
+ * audit.issues.forEach(issue => {
+ *   console.log(`Cell (${issue.cellX}, ${issue.cellY}): ${issue.suggestion}`);
+ * });
+ */
+async function auditGridsetImages(gridsetBuffer, password = (0, password_2.resolveGridsetPasswordFromEnv)()) {
+    const issues = [];
+    const availableImages = new Set();
+    let totalCells = 0;
+    let cellsWithImages = 0;
+    let resolvedImages = 0;
+    let unresolvedImages = 0;
+    try {
+        const { zip } = await (0, zip_1.openZipFromInput)(gridsetBuffer);
+        const entries = (0, password_1.getZipEntriesFromAdapter)(zip, password);
+        const parser = new fast_xml_parser_1.XMLParser();
+        // Collect all image files in the gridset
+        const imageExtensions = ['.png', '.jpg', '.jpeg', '.bmp', '.gif', '.emf', '.wmf'];
+        for (const entry of entries) {
+            const name = entry.entryName.toLowerCase();
+            if (imageExtensions.some((ext) => name.endsWith(ext))) {
+                availableImages.add(entry.entryName);
+            }
+        }
+        // Process each grid file
+        for (const entry of entries) {
+            if (!entry.entryName.startsWith('Grids/') || !entry.entryName.endsWith('grid.xml')) {
+                continue;
+            }
+            try {
+                const xmlContent = (0, io_1.decodeText)(await entry.getData());
+                const data = parser.parse(xmlContent);
+                const grid = data.Grid || data.grid;
+                if (!grid)
+                    continue;
+                const gridNameMatch = entry.entryName.match(/^Grids\/([^/]+)\//);
+                const gridName = gridNameMatch ? gridNameMatch[1] : entry.entryName;
+                const gridEntryPath = entry.entryName.replace(/\\/g, '/');
+                const baseDir = gridEntryPath.replace(/\/grid\.xml$/, '/');
+                // Check for FileMap.xml
+                const fileMapEntry = entries.find((e) => e.entryName === baseDir + 'FileMap.xml');
+                const dynamicFilesMap = new Map();
+                if (fileMapEntry) {
+                    try {
+                        const fmXml = (0, io_1.decodeText)(await fileMapEntry.getData());
+                        const fmData = parser.parse(fmXml);
+                        const fileEntries = fmData?.FileMap?.Entries?.Entry || fmData?.fileMap?.entries?.entry;
+                        if (fileEntries) {
+                            const arr = Array.isArray(fileEntries) ? fileEntries : [fileEntries];
+                            for (const ent of arr) {
+                                const rawStaticFile = ent['@_StaticFile'] || ent.StaticFile || ent.staticFile;
+                                const staticFile = typeof rawStaticFile === 'string' ? rawStaticFile.replace(/\\/g, '/') : '';
+                                if (!staticFile)
+                                    continue;
+                                const df = ent.DynamicFiles || ent.dynamicFiles;
+                                const candidates = df?.File || df?.file || df?.Files || df?.files;
+                                const list = Array.isArray(candidates)
+                                    ? candidates
+                                    : candidates
+                                        ? [candidates]
+                                        : [];
+                                dynamicFilesMap.set(staticFile, list);
+                            }
+                        }
+                    }
+                    catch (e) {
+                        // FileMap parsing failed, continue without it
+                    }
+                }
+                // Process cells
+                const cells = grid.Cells?.Cell || grid.cells?.cell;
+                if (!cells)
+                    continue;
+                const cellArr = Array.isArray(cells) ? cells : [cells];
+                for (const cell of cellArr) {
+                    totalCells++;
+                    const content = cell.Content;
+                    if (!content)
+                        continue;
+                    const captionAndImage = content.CaptionAndImage || content.captionAndImage;
+                    const imageCandidate = captionAndImage?.Image ||
+                        captionAndImage?.image ||
+                        captionAndImage?.ImageName ||
+                        captionAndImage?.imageName;
+                    if (!imageCandidate)
+                        continue;
+                    cellsWithImages++;
+                    const cellX = Math.max(0, parseInt(String(cell['@_X'] || '1'), 10) - 1);
+                    const cellY = Math.max(0, parseInt(String(cell['@_Y'] || '1'), 10) - 1);
+                    // Try to resolve the image
+                    const imageName = String(imageCandidate).trim();
+                    const imageFound = availableImages.has(`${baseDir}${imageName}`) ||
+                        availableImages.has(`${baseDir}Images/${imageName}`);
+                    if (imageFound) {
+                        resolvedImages++;
+                    }
+                    else {
+                        unresolvedImages++;
+                        // Determine the issue
+                        const expectedPaths = [
+                            `${baseDir}${imageName}`,
+                            `${baseDir}Images/${imageName}`,
+                            `${baseDir}${cellX + 1}-${cellY + 1}-0-text-0.png`,
+                            `${baseDir}${cellX + 1}-${cellY + 1}.png`,
+                        ];
+                        let issue;
+                        let suggestion;
+                        if (imageName.startsWith('[')) {
+                            // Check if it's a symbol library reference
+                            if (imageName.includes('widgit') || imageName.includes('Widgit')) {
+                                issue = 'symbol_library';
+                                suggestion =
+                                    'This is a Widgit symbol library reference. These symbols are not stored in the gridset - they require the Widgit Symbols to be installed on the system.';
+                            }
+                            else if (imageName.includes('grid3x') || imageName.includes('Grid3')) {
+                                issue = 'external_reference';
+                                suggestion =
+                                    'This is a built-in Grid3 resource reference. These images are not included in the gridset file.';
+                            }
+                            else {
+                                issue = 'symbol_library';
+                                suggestion = `External symbol library reference: ${imageName}. Symbol libraries are not embedded in gridset files.`;
+                            }
+                        }
+                        else {
+                            issue = 'not_found';
+                            const similarImages = Array.from(availableImages).filter((img) => img.toLowerCase().includes(imageName.toLowerCase().substring(0, 10)));
+                            if (similarImages.length > 0) {
+                                suggestion = `Image not found. Did you mean one of these?\n  ${similarImages.slice(0, 3).join('\n  ')}`;
+                            }
+                            else {
+                                suggestion = `Image file not found in gridset. The file may have been excluded or the path is incorrect.`;
+                            }
+                        }
+                        issues.push({
+                            gridName,
+                            cellX: cellX + 1,
+                            cellY: cellY + 1,
+                            declaredImage: imageName,
+                            expectedPaths,
+                            issue,
+                            suggestion,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                // Skip grids that can't be processed
+                continue;
+            }
+        }
+        return {
+            totalCells,
+            cellsWithImages,
+            resolvedImages,
+            unresolvedImages,
+            issues,
+            availableImages: Array.from(availableImages).sort(),
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to audit gridset images: ${error.message}`);
+    }
+}
+/**
+ * Get a human-readable summary of image audit results
+ */
+function formatImageAuditSummary(audit) {
+    const lines = [];
+    lines.push('=== Grid3 Image Audit Summary ===');
+    lines.push(`Total cells: ${audit.totalCells}`);
+    lines.push(`Cells with images: ${audit.cellsWithImages}`);
+    lines.push(`Resolved images: ${audit.resolvedImages}`);
+    lines.push(`Unresolved images: ${audit.unresolvedImages}`);
+    lines.push(`Available image files: ${audit.availableImages.length}`);
+    lines.push('');
+    if (audit.issues.length > 0) {
+        lines.push('=== Image Issues ===');
+        // Group by issue type
+        const byType = new Map();
+        for (const issue of audit.issues) {
+            const list = byType.get(issue.issue) || [];
+            list.push(issue);
+            byType.set(issue.issue, list);
+        }
+        for (const [type, issues] of byType) {
+            lines.push(`\n${type.toUpperCase()} (${issues.length} occurrences):`);
+            for (const issue of issues.slice(0, 5)) {
+                // Show first 5 of each type
+                lines.push(`  [${issue.gridName}] Cell (${issue.cellX}, ${issue.cellY}): ${issue.declaredImage}`);
+                lines.push(`    → ${issue.suggestion}`);
+            }
+            if (issues.length > 5) {
+                lines.push(`  ... and ${issues.length - 5} more`);
+            }
+        }
+    }
+    return lines.join('\n');
+}

package/dist/processors/gridset/resolver.js

@@ -72,6 +72,14 @@ function resolveGrid3CellImage(zip, args, zipEntries) {
     }
     // Direct declared file
     if (imageName) {
+        // Check for partial image names that start with '-' (common in Grid3)
+        // These are coordinate-based suffixes like "-0-text-0.png" that need
+        // to be prefixed with the cell coordinates
+        if (imageName.startsWith('-') && x != null && y != null) {
+            const coordPrefixed = joinBaseDir(baseDir, `${x}-${y}${imageName}`);
+            if (has(coordPrefixed))
+                return coordPrefixed;
+        }
         const p1 = joinBaseDir(baseDir, imageName);
         if (has(p1))
             return p1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "browser": "dist/browser/index.browser.js",