Add standardized visibility mapping for grid processors

Introduces consistent mapping of visibility/hidden fields to the AAC standard ('Visible', 'Hidden', etc.) across Asterics, OBF, Grid 3, and TouchChat processors. Updates symbol extraction in Grid3SymbolExtractor to use the shared extractSymbolReferences utility. Ensures that cell/button visibility is correctly parsed and exported for all supported grid formats.

Author: willwade

src/optional/symbolTools.ts

@@ -4,6 +4,7 @@ import {
   getZipEntriesWithPassword,
   resolveGridsetPasswordFromEnv,
 } from '../processors/gridset/password';
+import { extractSymbolReferences } from '../processors/gridset/symbols';
 
 // Dynamic imports for optional dependencies
 type Database = typeof import('better-sqlite3');
@@ -79,21 +80,14 @@ try {
 export class Grid3SymbolExtractor extends SymbolExtractor {
   getSymbolReferences(filePath: string): string[] {
     if (!AdmZip || !XMLParser) throw new Error('adm-zip or fast-xml-parser not installed');
-    const zip = new AdmZip(filePath);
-    const parser = new XMLParser();
-    const refs = new Set<string>();
-
-    const entries = getZipEntriesWithPassword(zip, resolveGridsetPasswordFromEnv());
-    entries.forEach((entry) => {
-      if (entry.entryName.endsWith('.gridset') || entry.entryName.endsWith('.gridsetx')) {
-        const xmlBuffer = entry.getData();
-        // Parse to validate XML structure (future: extract refs)
-        parser.parse(xmlBuffer.toString('utf8'));
-        // TODO: Extract symbol references from Grid 3 XML structure when needed
-      }
-    });
-
-    return Array.from(refs);
+
+    // Import GridsetProcessor dynamically to avoid circular dependencies
+    const { GridsetProcessor } = require('../processors/gridsetProcessor');
+    const proc = new GridsetProcessor();
+    const tree = proc.loadIntoTree(filePath);
+
+    // Use the existing extractSymbolReferences function from gridset/symbols.ts
+    return extractSymbolReferences(tree);
   }
 }
 

src/processors/astericsGridProcessor.ts

@@ -49,6 +49,7 @@ interface GridElement {
   dontCollect?: boolean;
   type?: string;
   additionalProps?: any;
+  hidden?: boolean; // Asterics Grid uses boolean hidden field
 }
 
 interface GridImage {
@@ -701,6 +702,18 @@ function getContrastingTextColor(backgroundColor: string): string {
   return luminance < 0.5 ? '#FFFFFF' : '#000000';
 }
 
+/**
+ * Map Asterics Grid hidden value to AAC standard visibility
+ * Asterics Grid: true = hidden, false = visible
+ * Maps to: 'Hidden' | 'Visible' | undefined
+ */
+function mapAstericsVisibility(hidden: boolean | undefined): 'Hidden' | 'Visible' | undefined {
+  if (hidden === undefined) {
+    return undefined; // Default to visible
+  }
+  return hidden ? 'Hidden' : 'Visible';
+}
+
 class AstericsGridProcessor extends BaseProcessor {
   private loadAudio: boolean = false;
 
@@ -1212,6 +1225,7 @@ class AstericsGridProcessor extends BaseProcessor {
 
       semanticAction: semanticAction,
       audioRecording: audioRecording,
+      visibility: mapAstericsVisibility(element.hidden),
       image: imageName, // Store image filename/reference
       parameters: imageData
         ? {

src/processors/gridsetProcessor.ts

@@ -525,18 +525,59 @@ class GridsetProcessor extends BaseProcessor {
             // Extract scan block number (1-8) for block scanning support
             const scanBlock = parseInt(String(cell['@_ScanBlock'] || '1'), 10);
 
+            // Extract visibility from Grid 3's <Visibility> child element
+            // Grid 3 stores visibility as a child element, not an attribute
+            // Valid values: Visible, Hidden, Disabled, PointerAndTouchOnly, TouchOnly, PointerOnly
+            const grid3Visibility = cell.Visibility || cell.visibility;
+
+            // Map Grid 3 visibility values to AAC standard values
+            // Grid 3 can have additional values like TouchOnly, PointerOnly that map to PointerAndTouchOnly
+            let cellVisibility: 'Visible' | 'Hidden' | 'Disabled' | 'PointerAndTouchOnly' | 'Empty' | undefined;
+            if (grid3Visibility) {
+              const vis = String(grid3Visibility);
+              // Direct mapping for standard values
+              if (vis === 'Visible' || vis === 'Hidden' || vis === 'Disabled' || vis === 'PointerAndTouchOnly') {
+                cellVisibility = vis;
+              }
+              // Map Grid 3 specific values to AAC standard
+              else if (vis === 'TouchOnly' || vis === 'PointerOnly') {
+                cellVisibility = 'PointerAndTouchOnly';
+              }
+              // Grid 3 may use 'Empty' for cells that exist but have no content
+              else if (vis === 'Empty') {
+                cellVisibility = 'Empty';
+              }
+              // Unknown visibility - default to Visible
+              else {
+                cellVisibility = undefined; // Let it default
+              }
+            }
+
             // Extract label from CaptionAndImage/Caption
             const content = cell.Content;
             const captionAndImage = content.CaptionAndImage || content.captionAndImage;
             let label = captionAndImage?.Caption || captionAndImage?.caption || '';
 
+            // Check if cell has an image/symbol (needed to decide if we should keep it)
+            const hasImageCandidate = !!(
+              captionAndImage?.Image ||
+              captionAndImage?.image ||
+              captionAndImage?.ImageName ||
+              captionAndImage?.imageName ||
+              captionAndImage?.Symbol ||
+              captionAndImage?.symbol
+            );
+
             // If no caption, try other sources or create a placeholder
             if (!label) {
-              // For cells without captions (like AutoContent cells), create a meaningful label
+              // For cells without captions, check if they have images/symbols before skipping
               if (content.ContentType === 'AutoContent') {
                 label = `AutoContent_${idx}`;
+              } else if (hasImageCandidate || content.ContentType === 'Workspace' || content.ContentType === 'LiveCell') {
+                // Keep cells with images/symbols even if no caption
+                label = `Cell_${idx}`;
               } else {
-                return; // Skip cells without labels
+                return; // Skip cells without labels AND without images/symbols
               }
             }
 
@@ -1013,6 +1054,7 @@ class GridsetProcessor extends BaseProcessor {
                 pluginMetadata.autoContentType,
               symbolLibrary: symbolLibraryRef?.library || undefined,
               symbolPath: symbolLibraryRef?.path || undefined,
+              visibility: cellVisibility,
               style: {
                 ...cellStyle,
                 ...inlineStyle, // Inline styles override referenced styles

src/processors/obfProcessor.ts

@@ -32,6 +32,19 @@ interface ObfButton {
   background_color?: string;
   border_color?: string;
   semantic_id?: string; // Optional semantic identifier for motor planning
+  hidden?: boolean; // OBF uses boolean hidden field
+}
+
+/**
+ * Map OBF hidden value to AAC standard visibility
+ * OBF: true = hidden, false/undefined = visible
+ * Maps to: 'Hidden' | 'Visible' | undefined
+ */
+function mapObfVisibility(hidden: boolean | undefined): 'Hidden' | 'Visible' | undefined {
+  if (hidden === undefined) {
+    return undefined; // Default to visible
+  }
+  return hidden ? 'Hidden' : 'Visible';
 }
 
 interface ObfGrid {
@@ -83,6 +96,7 @@ class ObfProcessor extends BaseProcessor {
         id: String(btn?.id || ''),
         label: String(btn?.label || ''),
         message: String(btn?.vocalization || btn?.label || ''),
+        visibility: mapObfVisibility(btn.hidden),
         style: {
           backgroundColor: btn.background_color,
           borderColor: btn.border_color,

src/processors/touchchatProcessor.ts

@@ -84,6 +84,18 @@ function intToHex(colorInt: number | null | undefined): string | undefined {
   return `#${(colorInt & 0x00ffffff).toString(16).padStart(6, '0')}`;
 }
 
+/**
+ * Map TouchChat visible value to AAC standard visibility
+ * TouchChat: 0 = Hidden, 1 = Visible
+ * Maps to: 'Hidden' | 'Visible' | undefined
+ */
+function mapTouchChatVisibility(visible: number | null | undefined): 'Visible' | 'Hidden' | undefined {
+  if (visible === null || visible === undefined) {
+    return undefined; // Default to visible
+  }
+  return visible === 0 ? 'Hidden' : 'Visible';
+}
+
 class TouchChatProcessor extends BaseProcessor {
   private tree: AACTree | null = null;
   private sourceFile: string | Buffer | null = null;
@@ -257,6 +269,7 @@ class TouchChatProcessor extends BaseProcessor {
             message: cell.message || '',
             semanticAction: semanticAction,
             semantic_id: (cell as any).symbol_link_id || (cell as any).symbolLinkId || undefined, // Extract semantic_id from symbol_link_id
+            visibility: mapTouchChatVisibility((cell as any).visible),
             // Note: TouchChat does not use scan blocks in the file
             // Scanning is a runtime feature (linear/row-column patterns)
             // scanBlock defaults to 1 (no grouping)
@@ -422,6 +435,7 @@ class TouchChatProcessor extends BaseProcessor {
             label: btnRow.label || '',
             message: btnRow.message || '',
             semanticAction: semanticAction,
+            visibility: mapTouchChatVisibility(btnRow.visible),
             // Note: TouchChat does not use scan blocks in the file
             // Scanning is a runtime feature (linear/row-column patterns)
             // scanBlock defaults to 1 (no grouping)