feat: Add Phase 1 Grid3 utilities (GUID, Settings XML, FileMap XML)

- Add generateGrid3Guid() for creating unique Grid3 element identifiers
- Add createSettingsXml() for building Grid3 settings configuration
- Add createFileMapXml() for creating Grid3 FileMap.xml content
- Export new utilities from src/processors/index.ts
- Add comprehensive unit tests (16 new tests, all passing)
- All tests pass: 406 passed, 1 skipped
- No regressions in existing functionality

Author: willwade

src/processors/gridset/helpers.ts

@@ -1,4 +1,5 @@
 import AdmZip from 'adm-zip';
+import { XMLBuilder } from 'fast-xml-parser';
 import { AACTree, AACPage, AACButton } from '../../core/treeStructure';
 
 function normalizeZipPath(p: string): string {
@@ -39,3 +40,88 @@ export function openImage(gridsetBuffer: Buffer, entryPath: string): Buffer | nu
   if (!entry) return null;
   return entry.getData();
 }
+
+/**
+ * Generate a random GUID for Grid3 elements
+ * Grid3 uses GUIDs for grid identification
+ * @returns A UUID v4-like string in the format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+export function generateGrid3Guid(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+/**
+ * Create Grid3 settings XML with start grid and common settings
+ * @param startGrid - Name of the grid to start on
+ * @param options - Optional settings (scan, hover, language, etc.)
+ * @returns XML string for Settings.xml
+ */
+export function createSettingsXml(
+  startGrid: string,
+  options?: {
+    scanEnabled?: boolean;
+    scanTimeoutMs?: number;
+    hoverEnabled?: boolean;
+    hoverTimeoutMs?: number;
+    mouseclickEnabled?: boolean;
+    language?: string;
+  }
+): string {
+  const builder = new XMLBuilder({
+    ignoreAttributes: false,
+    format: true,
+    indentBy: '  ',
+  });
+
+  const settingsData = {
+    GridSetSettings: {
+      '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+      StartGrid: startGrid,
+      ScanEnabled: options?.scanEnabled?.toString() ?? 'false',
+      ScanTimeoutMs: options?.scanTimeoutMs?.toString() ?? '2000',
+      HoverEnabled: options?.hoverEnabled?.toString() ?? 'false',
+      HoverTimeoutMs: options?.hoverTimeoutMs?.toString() ?? '1000',
+      MouseclickEnabled: options?.mouseclickEnabled?.toString() ?? 'true',
+      Language: options?.language ?? 'en-US',
+    },
+  };
+
+  return builder.build(settingsData);
+}
+
+/**
+ * Create Grid3 FileMap.xml content
+ * @param grids - Array of grid configurations with name and path
+ * @returns XML string for FileMap.xml
+ */
+export function createFileMapXml(
+  grids: Array<{ name: string; path: string; dynamicFiles?: string[] }>
+): string {
+  const builder = new XMLBuilder({
+    ignoreAttributes: false,
+    format: true,
+    indentBy: '  ',
+  });
+
+  const entries = grids.map((grid) => ({
+    '@_StaticFile': grid.path,
+    ...(grid.dynamicFiles && grid.dynamicFiles.length > 0
+      ? { DynamicFiles: { File: grid.dynamicFiles } }
+      : {}),
+  }));
+
+  const fileMapData = {
+    FileMap: {
+      '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+      Entries: {
+        Entry: entries,
+      },
+    },
+  };
+
+  return builder.build(fileMapData);
+}

src/processors/index.ts

@@ -9,11 +9,21 @@ export { TouchChatProcessor } from './touchchatProcessor';
 export { AstericsGridProcessor } from './astericsGridProcessor';
 
 // Gridset (Grid 3) helpers
-export { getPageTokenImageMap, getAllowedImageEntries, openImage } from './gridset/helpers';
+export {
+  getPageTokenImageMap,
+  getAllowedImageEntries,
+  openImage,
+  generateGrid3Guid,
+  createSettingsXml,
+  createFileMapXml,
+} from './gridset/helpers';
 export {
   getPageTokenImageMap as getGridsetPageTokenImageMap,
   getAllowedImageEntries as getGridsetAllowedImageEntries,
   openImage as openGridsetImage,
+  generateGrid3Guid as generateGridsetGuid,
+  createSettingsXml as createGridsetSettingsXml,
+  createFileMapXml as createGridsetFileMapXml,
 } from './gridset/helpers';
 export { resolveGrid3CellImage } from './gridset/resolver';
 

test/gridsetHelpers.test.ts

@@ -4,6 +4,9 @@ import {
   getAllowedImageEntries,
   getPageTokenImageMap,
   openImage,
+  generateGrid3Guid,
+  createSettingsXml,
+  createFileMapXml,
 } from '../src/processors/gridset/helpers';
 
 describe('Gridset helper APIs', () => {
@@ -75,3 +78,136 @@ describe('Gridset helper APIs', () => {
     expect(missing).toBeNull();
   });
 });
+
+describe('Grid3 GUID Generation', () => {
+  it('generateGrid3Guid generates a valid GUID format', () => {
+    const guid = generateGrid3Guid();
+    // Check format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+    const guidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    expect(guid).toMatch(guidRegex);
+  });
+
+  it('generateGrid3Guid generates unique GUIDs', () => {
+    const guid1 = generateGrid3Guid();
+    const guid2 = generateGrid3Guid();
+    const guid3 = generateGrid3Guid();
+    expect(guid1).not.toBe(guid2);
+    expect(guid2).not.toBe(guid3);
+    expect(guid1).not.toBe(guid3);
+  });
+
+  it('generateGrid3Guid generates GUIDs with correct version and variant', () => {
+    // Generate multiple GUIDs and check they all have version 4 and variant 1
+    for (let i = 0; i < 10; i++) {
+      const guid = generateGrid3Guid();
+      const parts = guid.split('-');
+      // Version 4 is in the first character of the 3rd group
+      expect(parts[2][0]).toBe('4');
+      // Variant 1 is in the first character of the 4th group (should be 8, 9, a, or b)
+      expect(['8', '9', 'a', 'b']).toContain(parts[3][0].toLowerCase());
+    }
+  });
+});
+
+describe('Grid3 Settings XML Builder', () => {
+  it('createSettingsXml creates valid XML with default options', () => {
+    const xml = createSettingsXml('Home');
+    expect(xml).toContain('<GridSetSettings');
+    expect(xml).toContain('<StartGrid>Home</StartGrid>');
+    expect(xml).toContain('<ScanEnabled>false</ScanEnabled>');
+    expect(xml).toContain('<HoverEnabled>false</HoverEnabled>');
+    expect(xml).toContain('<MouseclickEnabled>true</MouseclickEnabled>');
+    expect(xml).toContain('<Language>en-US</Language>');
+  });
+
+  it('createSettingsXml respects custom options', () => {
+    const xml = createSettingsXml('MainMenu', {
+      scanEnabled: true,
+      scanTimeoutMs: 3000,
+      hoverEnabled: true,
+      hoverTimeoutMs: 1500,
+      mouseclickEnabled: false,
+      language: 'fr-FR',
+    });
+    expect(xml).toContain('<StartGrid>MainMenu</StartGrid>');
+    expect(xml).toContain('<ScanEnabled>true</ScanEnabled>');
+    expect(xml).toContain('<ScanTimeoutMs>3000</ScanTimeoutMs>');
+    expect(xml).toContain('<HoverEnabled>true</HoverEnabled>');
+    expect(xml).toContain('<HoverTimeoutMs>1500</HoverTimeoutMs>');
+    expect(xml).toContain('<MouseclickEnabled>false</MouseclickEnabled>');
+    expect(xml).toContain('<Language>fr-FR</Language>');
+  });
+
+  it('createSettingsXml includes XML namespace', () => {
+    const xml = createSettingsXml('Home');
+    expect(xml).toContain('xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"');
+  });
+
+  it('createSettingsXml handles partial options', () => {
+    const xml = createSettingsXml('Home', {
+      scanEnabled: true,
+      language: 'de-DE',
+    });
+    expect(xml).toContain('<ScanEnabled>true</ScanEnabled>');
+    expect(xml).toContain('<Language>de-DE</Language>');
+    // Should still have defaults for unspecified options
+    expect(xml).toContain('<HoverEnabled>false</HoverEnabled>');
+    expect(xml).toContain('<MouseclickEnabled>true</MouseclickEnabled>');
+  });
+});
+
+describe('Grid3 FileMap XML Builder', () => {
+  it('createFileMapXml creates valid XML with single grid', () => {
+    const xml = createFileMapXml([{ name: 'Home', path: 'Grids\\Home\\grid.xml' }]);
+    expect(xml).toContain('<FileMap');
+    expect(xml).toContain('<Entries>');
+    expect(xml).toContain('<Entry');
+    expect(xml).toContain('StaticFile="Grids\\Home\\grid.xml"');
+  });
+
+  it('createFileMapXml creates valid XML with multiple grids', () => {
+    const xml = createFileMapXml([
+      { name: 'Home', path: 'Grids\\Home\\grid.xml' },
+      { name: 'Menu', path: 'Grids\\Menu\\grid.xml' },
+      { name: 'Settings', path: 'Grids\\Settings\\grid.xml' },
+    ]);
+    expect(xml).toContain('StaticFile="Grids\\Home\\grid.xml"');
+    expect(xml).toContain('StaticFile="Grids\\Menu\\grid.xml"');
+    expect(xml).toContain('StaticFile="Grids\\Settings\\grid.xml"');
+  });
+
+  it('createFileMapXml includes dynamic files when provided', () => {
+    const xml = createFileMapXml([
+      {
+        name: 'Home',
+        path: 'Grids\\Home\\grid.xml',
+        dynamicFiles: ['dynamic1.xml', 'dynamic2.xml'],
+      },
+    ]);
+    expect(xml).toContain('<DynamicFiles>');
+    expect(xml).toContain('<File>dynamic1.xml</File>');
+    expect(xml).toContain('<File>dynamic2.xml</File>');
+  });
+
+  it('createFileMapXml omits DynamicFiles when empty', () => {
+    const xml = createFileMapXml([
+      { name: 'Home', path: 'Grids\\Home\\grid.xml', dynamicFiles: [] },
+    ]);
+    expect(xml).not.toContain('<DynamicFiles>');
+  });
+
+  it('createFileMapXml includes XML namespace', () => {
+    const xml = createFileMapXml([{ name: 'Home', path: 'Grids\\Home\\grid.xml' }]);
+    expect(xml).toContain('xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"');
+  });
+
+  it('createFileMapXml handles mixed grids with and without dynamic files', () => {
+    const xml = createFileMapXml([
+      { name: 'Home', path: 'Grids\\Home\\grid.xml' },
+      { name: 'Menu', path: 'Grids\\Menu\\grid.xml', dynamicFiles: ['menu_dynamic.xml'] },
+    ]);
+    expect(xml).toContain('StaticFile="Grids\\Home\\grid.xml"');
+    expect(xml).toContain('StaticFile="Grids\\Menu\\grid.xml"');
+    expect(xml).toContain('<File>menu_dynamic.xml</File>');
+  });
+});