Enhance Grid 3 symbol library and color utilities support

 Fixed import error in src/processors/index.ts - isSymbolLibraryReference and parseImageSymbolReference are exported from resolver.ts, not symbols.ts
  3. Fixed self-reference bug in src/processors/gridsetProcessor.ts - removed ...button?.parameters that referenced the variable being created
  4. Added missing constructor parameters to AACButton class in src/core/treeStructure.ts for symbolLibrary and symbolPath
  5. Fixed resolver logic in src/processors/gridset/resolver.ts - restructured the check to ensure [grid3x] built-in resources use the builtinHandler before treating them as symbol library references

Author: willwade

src/core/baseProcessor.ts

@@ -16,6 +16,18 @@ export interface ProcessorOptions {
 
   // Preserve original behavior for backwards compatibility
   preserveAllButtons?: boolean;
+
+  // Grid 3 symbol library directory (for resolving [widgit]/ style references)
+  // If not specified, will attempt to auto-detect from Grid 3 installation
+  grid3SymbolDir?: string;
+
+  // Grid 3 installation path (for auto-detecting symbol directory)
+  // If not specified, will use default platform-specific path
+  grid3Path?: string;
+
+  // Locale for symbol libraries (e.g., 'en-GB', 'en-US')
+  // Defaults to 'en-GB' if not specified
+  grid3Locale?: string;
 }
 
 // Types for aac-tools-platform compatibility

src/core/treeStructure.ts

@@ -156,6 +156,8 @@ export class AACButton implements IAACButton {
     contentSubType,
     image,
     resolvedImageEntry,
+    symbolLibrary,
+    symbolPath,
     x,
     y,
     columnSpan,
@@ -184,6 +186,8 @@ export class AACButton implements IAACButton {
     contentSubType?: string;
     image?: string;
     resolvedImageEntry?: string;
+    symbolLibrary?: string;
+    symbolPath?: string;
     x?: number;
     y?: number;
     columnSpan?: number;
@@ -211,6 +215,8 @@ export class AACButton implements IAACButton {
     this.contentSubType = contentSubType;
     this.image = image;
     this.resolvedImageEntry = resolvedImageEntry;
+    this.symbolLibrary = symbolLibrary;
+    this.symbolPath = symbolPath;
     this.x = x;
     this.y = y;
     this.columnSpan = columnSpan;

src/processors/gridset/colorUtils.ts

@@ -289,6 +289,42 @@ export function darkenColor(hex: string, amount: number): string {
   return `#${channelToHex(newR)}${channelToHex(newG)}${channelToHex(newB)}${alpha.toUpperCase()}`;
 }
 
+/**
+ * Lighten a hex color by a specified amount
+ * @param hex - Hex color string
+ * @param amount - Amount to lighten (0-255)
+ * @returns Lightened hex color
+ */
+export function lightenColor(hex: string, amount: number): string {
+  const normalized = ensureAlphaChannel(hex).substring(1); // strip #
+  const rgb = normalized.substring(0, 6);
+  const alpha = normalized.substring(6) || 'FF';
+  const r = parseInt(rgb.substring(0, 2), 16);
+  const g = parseInt(rgb.substring(2, 4), 16);
+  const b = parseInt(rgb.substring(4, 6), 16);
+  const clamp = (val: number): number => Math.max(0, Math.min(255, val));
+  const newR = clamp(r + amount);
+  const newG = clamp(g + amount);
+  const newB = clamp(b + amount);
+  return `#${channelToHex(newR)}${channelToHex(newG)}${channelToHex(newB)}${alpha.toUpperCase()}`;
+}
+
+/**
+ * Convert hex color to RGBA object
+ * @param hex - Hex color string (#RRGGBB or #RRGGBBAA)
+ * @returns RGBA object with r, g, b, a properties (0-1 for alpha)
+ */
+export function hexToRgba(hex: string): { r: number; g: number; b: number; a: number } {
+  const normalized = ensureAlphaChannel(hex).substring(1); // strip #
+  const rgb = normalized.substring(0, 6);
+  const alphaHex = normalized.substring(6) || 'FF';
+  const r = parseInt(rgb.substring(0, 2), 16);
+  const g = parseInt(rgb.substring(2, 4), 16);
+  const b = parseInt(rgb.substring(4, 6), 16);
+  const a = parseInt(alphaHex, 16) / 255;
+  return { r, g, b, a };
+}
+
 /**
  * Normalize any color format to Grid3's 8-digit hex format
  * @param input - Color string in any supported format

src/processors/gridset/resolver.ts

@@ -1,4 +1,4 @@
-import { isSymbolReference, parseSymbolReference, type SymbolReference } from './symbols';
+import { isSymbolReference, parseSymbolReference } from './symbols';
 
 function normalizeZipPathLocal(p: string): string {
   const unified = p.replace(/\\/g, '/');
@@ -57,16 +57,22 @@ export function resolveGrid3CellImage(
   const entries = new Set(listZipEntries(zip, zipEntries));
   const has = (p: string): boolean => entries.has(normalizeZipPathLocal(p));
 
-  // Check for symbol library reference like [widgit]/food/apple.png
-  if (imageName && isSymbolReference(imageName)) {
-    // 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;
-  }
-
   // 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 (isSymbolReference(imageName)) {
+      const parsed = 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) return mapped;
@@ -135,7 +141,7 @@ export function isSymbolLibraryReference(imageName?: string): boolean {
  * @param imageName - Image reference from Grid 3
  * @returns Parsed reference or null if not a symbol reference
  */
-export function parseImageSymbolReference(imageName: string): SymbolReference | null {
+export function parseImageSymbolReference(imageName: string) {
   if (!isSymbolLibraryReference(imageName)) {
     return null;
   }

src/processors/gridsetProcessor.ts

@@ -24,10 +24,27 @@ import zlib from 'zlib';
 import { GridsetValidator } from '../validation/gridsetValidator';
 import { ValidationResult } from '../validation/validationTypes';
 // New imports for enhanced Grid 3 support
-import { detectPluginCellType, Grid3CellType } from './gridset/pluginTypes';
-import { detectCommand } from './gridset/commands';
-import { parseSymbolReference, type SymbolReference } from './gridset/symbols';
-import { isSymbolLibraryReference } from './gridset/resolver';
+import { CellBackgroundShape } from './gridset/styleHelpers';
+import { detectPluginCellType, Grid3PluginMetadata, Grid3CellType } from './gridset/pluginTypes';
+import {
+  detectCommand,
+  getCommandDefinition,
+  Grid3CommandCategory,
+  GRID3_COMMANDS,
+  getAllCommandIds,
+  getAllPluginIds,
+} from './gridset/commands';
+import {
+  isSymbolReference,
+  parseSymbolReference,
+  resolveSymbolReference,
+  getSymbolLibraryDisplayName,
+  type SymbolReference,
+} from './gridset/symbols';
+import {
+  isSymbolLibraryReference,
+  parseImageSymbolReference,
+} from './gridset/resolver';
 
 class GridsetProcessor extends BaseProcessor {
   constructor(options?: ProcessorOptions) {
@@ -282,10 +299,9 @@ class GridsetProcessor extends BaseProcessor {
       fontColor: grid3Style.FontColour,
       fontFamily: grid3Style.FontName,
       fontSize: grid3Style.FontSize ? parseInt(String(grid3Style.FontSize)) : undefined,
-      backgroundShape:
-        grid3Style.BackgroundShape !== undefined
-          ? parseInt(String(grid3Style.BackgroundShape))
-          : undefined,
+      backgroundShape: grid3Style.BackgroundShape !== undefined
+        ? parseInt(String(grid3Style.BackgroundShape))
+        : undefined,
     };
   }
 
@@ -583,7 +599,7 @@ class GridsetProcessor extends BaseProcessor {
 
             if (commands) {
               const commandArr = Array.isArray(commands) ? commands : [commands];
-              detectedCommands = commandArr.map((cmd) => detectCommand(cmd));
+              detectedCommands = commandArr.map(cmd => detectCommand(cmd));
 
               for (const command of commandArr) {
                 const commandId = command['@_ID'] || command.ID || command.id;
@@ -993,18 +1009,14 @@ class GridsetProcessor extends BaseProcessor {
               y: cellY,
               columnSpan: colSpan,
               rowSpan: rowSpan,
-              contentType:
-                pluginMetadata.cellType === Grid3CellType.Regular
-                  ? 'Normal'
-                  : pluginMetadata.cellType === Grid3CellType.Workspace
-                    ? 'Workspace'
-                    : pluginMetadata.cellType === Grid3CellType.LiveCell
-                      ? 'LiveCell'
-                      : 'AutoContent',
-              contentSubType:
-                pluginMetadata.subType ||
-                pluginMetadata.liveCellType ||
-                pluginMetadata.autoContentType,
+              contentType: pluginMetadata.cellType === Grid3CellType.Regular
+                ? 'Normal'
+                : pluginMetadata.cellType === Grid3CellType.Workspace
+                  ? 'Workspace'
+                  : pluginMetadata.cellType === Grid3CellType.LiveCell
+                    ? 'LiveCell'
+                    : 'AutoContent',
+              contentSubType: pluginMetadata.subType || pluginMetadata.liveCellType || pluginMetadata.autoContentType,
               symbolLibrary: symbolLibraryRef?.library || undefined,
               symbolPath: symbolLibraryRef?.path || undefined,
               style: {
@@ -1019,7 +1031,7 @@ class GridsetProcessor extends BaseProcessor {
             });
 
             // Add button to page
-            page.addButton(button as AACButton);
+            page.addButton(button);
 
             // Place button in grid layout (handle colspan/rowspan)
             for (let r = cellY; r < cellY + rowSpan && r < maxRows; r++) {

src/processors/index.ts

@@ -48,6 +48,7 @@ export {
   readGrid3HistoryForUser as readGridsetHistoryForUser,
   readAllGrid3History as readAllGridsetHistory,
 } from './gridset/helpers';
+export { resolveGrid3CellImage } from './gridset/resolver';
 
 // Gridset (Grid 3) wordlist helpers
 export {
@@ -140,16 +141,13 @@ export {
   symbolReferenceToFilename,
   SYMBOL_LIBRARIES,
 } from './gridset/symbols';
-
-// Gridset image resolution helpers
-export {
-  resolveGrid3CellImage,
-  isSymbolLibraryReference,
-  parseImageSymbolReference,
-} from './gridset/resolver';
+export { isSymbolLibraryReference, parseImageSymbolReference } from './gridset/resolver';
 
 // Backward compatibility
-export { getSymbolsDir, getSymbolSearchDir } from './gridset/symbols';
+export {
+  getSymbolsDir,
+  getSymbolSearchDir,
+} from './gridset/symbols';
 
 // Gridset (Grid 3) symbol extraction for conversion
 export {