@willwade/aac-processors 0.0.6 → 0.0.7

package/README.md

@@ -658,13 +658,8 @@ npm test
 
 - The repository keeps `package.json` at `0.0.0-development`; release tags control the published version.
 - Create a GitHub release with a semantic tag (e.g. `v2.1.0`). Publishing only runs for non-prerelease tags.
-- Add an `NPM_TOKEN` repository secret with publish rights. The release workflow uses it to authenticate and calls `npm publish`.
 - The workflow (`.github/workflows/publish.yml`) automatically installs dependencies, rewrites the package version from the tag, and runs the standard publish pipeline.
 
-**Private distribution options**
-- Unscoped packages on npm must be public. To keep this package private, re-scope it (e.g. `@your-org/aac-processors`) and configure `publishConfig.access: "restricted"`—this requires an npm org with paid seats.
-- Alternatively, publish to GitHub Packages by adjusting the workflow’s registry URL and using a `GITHUB_TOKEN` with the `packages: write` permission.
-
 ---
 
 ## 📄 License
@@ -715,15 +710,6 @@ Inspired by the Python AACProcessors project
 - [ ] **Add Symbol Tools coverage** (currently 0%) - Implement tests for PCS and ARASAAC symbol lookups to reach >70% coverage
 - [ ] **Fix property-based test failures** - Resolve TypeScript interface compatibility issues in edge case generators
 
-### Recently Completed ✅
-
-- [x] **Core utilities test coverage** - Complete implementation for analyze.ts and fileProcessor.ts (0% → 100% coverage, 45 comprehensive tests, src/core/ directory 30% → 83% coverage)
-- [x] **CLI test infrastructure** - Fixed DotProcessor parsing and test expectations (0 → 25 passing tests, 100% CLI functionality)
-- [x] **Critical linting fixes** - Resolved unsafe argument types and CLI type safety issues (177 → 123 errors, 32% improvement)
-- [x] **Audio test syntax fixes** - Fixed non-null assertion errors in audio tests (21 → 5 failing tests, 76% improvement)
-- [x] **Comprehensive styling support** - Complete implementation across all AAC formats with cross-format preservation (Added: AACStyle interface, enhanced all processors, 7 new test cases, complete documentation)
-- [x] **TouchChatProcessor save/load functionality** - Fixed button persistence and ID mapping (coverage improved from 57.62% to 86.44%)
-- [x] **Build integration** - Ensure `npm run build` is executed before CLI tests (Fixed: All test scripts now automatically build before running)
 
 ### Medium Priority
 
@@ -749,29 +735,6 @@ Inspired by the Python AACProcessors project
 - [ ] **CI/CD improvements** - Add automated releases and npm publishing
 - [ ] **Documentation improvements** - Add more real-world examples and tutorials
 
-### Known Issues
-
-- ⚠️ **Audio Persistence**: 5 functional tests failing due to audio recording not persisting through SnapProcessor save/load cycle
-- ⚠️ **Grid3 Layout**: Grid sizes not reliable and X,Y positions incorrect, particularly affecting Grid3 processor functionality
-- ⚠️ **Database Constraints**: UNIQUE constraint violations with real-world data files (Page.Id and buttons.id conflicts)
-- ⚠️ **Linting**: 123 ESLint issues remaining (mostly in test files, reduced from 177)
-- ⚠️ **SnapProcessor**: Lowest coverage at 48.32%, missing comprehensive audio handling tests
-- ⚠️ **Memory usage**: Large files (>50MB) may cause memory pressure
-- ⚠️ **Concurrent access**: Some processors not fully thread-safe for simultaneous writes
-
-### 🧪 Current Test Status & Immediate Follow-Up
-
-As of the latest run (`npm test`), **47 suites pass / 6 fail (10 individual tests)**. Remaining blockers are:
-
-1. **Edge-case loaders** – corrupted JSON/XML fixtures still expect explicit exceptions. Decide whether to restore the old throwing behaviour (Asterics/OPML/DOT) or update the tests to accept the softer error reporting.
-2. **Gridset exports & styling** – round-trip continues to lose a button and the styling suite cannot find `style.xml`. GridsetProcessor needs to preserve button arrays and emit the styling assets Grid 3 expects.
-3. **DOT navigation semantics** – the deterministic DOT test still falls back to `SPEAK`. Improve semantic reconstruction when loading navigation edges so navigation buttons survive round-trips.
-4. **Advanced workflow scenario** – the multi-format pipeline still loses Spanish translations (likely during the Gridset ⇄ Snap steps); trace text propagation and patch the conversion chain.
-5. **Styling suite** – Grid 3 export still lacks `style.xml`; ensure the styling assets are generated alongside the gridset payload.
-6. **Memory comparison suite** – memory delta expectations are still unmet (TouchChat GC + DOT vs others). Either recalibrate the harness or tune the processors before re-enabling the assertions.
-
-Clearing these items will put the test matrix back in the green and unblock the release.
-
 ## More enhancements
 
 - Much more effort put into fixing the layout issues. Grid sizes are not reliably and X, Y positions too. Particularly in the Grid3

package/dist/processors/dotProcessor.js

@@ -17,17 +17,14 @@ class DotProcessor extends baseProcessor_1.BaseProcessor {
         const edges = [];
         // Extract all edge statements using regex to handle single-line DOT files
         const edgeRegex = /"?([^"\s]+)"?\s*->\s*"?([^"\s]+)"?(?:\s*\[label="([^"]+)"\])?/g;
-        const nodeRegex = /"?([^"\s]+)"?\s*\[label="([^"]+)"\]/g;
-        // Find all explicit node definitions
-        let nodeMatch;
-        while ((nodeMatch = nodeRegex.exec(content)) !== null) {
-            const [, id, label] = nodeMatch;
-            nodes.set(id, { id, label });
-        }
-        // Find all edge definitions
+        // We need to find nodes, but avoid matching the target of an edge which might look like a node definition
+        // e.g. A -> B [label="L"]  -- "B [label="L"]" looks like a node def
+        // Strategy: Find all edges, record them, and then "mask" them in the content to avoid false positives for nodes
+        let maskedContent = content;
         let edgeMatch;
+        // Find all edge definitions
         while ((edgeMatch = edgeRegex.exec(content)) !== null) {
-            const [, from, to, label] = edgeMatch;
+            const [fullMatch, from, to, label] = edgeMatch;
             edges.push({ from, to, label });
             // Add nodes if they don't exist (implicit definition)
             if (!nodes.has(from)) {
@@ -36,6 +33,23 @@ class DotProcessor extends baseProcessor_1.BaseProcessor {
             if (!nodes.has(to)) {
                 nodes.set(to, { id: to, label: to });
             }
+            // Mask this edge in the content so we don't match it as a node
+            // We replace it with spaces to preserve indices if needed, but simple replacement is enough here
+            maskedContent = maskedContent.replace(fullMatch, ' '.repeat(fullMatch.length));
+        }
+        // Now find explicit node definitions in the masked content
+        // This regex matches: ID [label="LABEL"]
+        // We use a non-greedy match for the label content to handle escaped quotes if possible,
+        // but the previous regex `[^"]+` was too simple.
+        // Better regex for quoted string content: (?:[^"\\]|\\.)*
+        const nodeRegex = /"?([^"\s]+)"?\s*\[label="((?:[^"\\]|\\.)*)"\]/g;
+        let nodeMatch;
+        while ((nodeMatch = nodeRegex.exec(maskedContent)) !== null) {
+            const [, id, rawLabel] = nodeMatch;
+            // Unescape the label: replace \" with " and \\ with \
+            const label = rawLabel.replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+            // Only update if not already defined or if we want to override the implicit label
+            nodes.set(id, { id, label });
         }
         return { nodes: Array.from(nodes.values()), edges };
     }
@@ -82,7 +96,8 @@ class DotProcessor extends baseProcessor_1.BaseProcessor {
         let hasControl = false;
         for (let i = 0; i < head.length; i++) {
             const code = head.charCodeAt(i);
-            if (code === 0 || (code >= 0 && code <= 8) || (code >= 14 && code <= 31) || code >= 127) {
+            // Allow UTF-8 characters (code >= 127)
+            if (code === 0 || (code >= 0 && code <= 8) || (code >= 14 && code <= 31)) {
                 hasControl = true;
                 break;
             }
@@ -150,10 +165,14 @@ class DotProcessor extends baseProcessor_1.BaseProcessor {
     }
     saveFromTree(tree, _outputPath) {
         let dotContent = 'digraph AACBoard {\n';
+        // Helper to escape DOT string
+        const escapeDotString = (str) => {
+            return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        };
         // Add nodes
         for (const pageId in tree.pages) {
             const page = tree.pages[pageId];
-            dotContent += `  "${page.id}" [label="${page.name}"]\n`;
+            dotContent += `  "${page.id}" [label="${escapeDotString(page.name)}"]\n`;
         }
         // Add edges from navigation buttons (semantic intent or legacy targetPageId)
         for (const pageId in tree.pages) {
@@ -166,7 +185,7 @@ class DotProcessor extends baseProcessor_1.BaseProcessor {
                 .forEach((btn) => {
                 const target = btn.semanticAction?.targetId || btn.targetPageId;
                 if (target) {
-                    dotContent += `  "${page.id}" -> "${target}" [label="${btn.label}"]\n`;
+                    dotContent += `  "${page.id}" -> "${target}" [label="${escapeDotString(btn.label)}"]\n`;
                 }
             });
         }

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

@@ -0,0 +1,69 @@
+/**
+ * Grid3 Color Utilities
+ *
+ * Comprehensive color handling for Grid3 format, including:
+ * - CSS color name lookup (147 named colors)
+ * - Color format conversion (hex, RGB, RGBA, named colors)
+ * - Color manipulation (darkening, normalization)
+ * - Grid3-specific color formatting (8-digit ARGB hex)
+ */
+/**
+ * Get RGB values for a CSS color name
+ * @param name - CSS color name (case-insensitive)
+ * @returns RGB tuple [r, g, b] or undefined if not found
+ */
+export declare function getNamedColor(name: string): [number, number, number] | undefined;
+/**
+ * Convert RGBA values to hex format
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @param a - Alpha channel (0-1)
+ * @returns Hex color string in format #RRGGBBAA
+ */
+export declare function rgbaToHex(r: number, g: number, b: number, a: number): string;
+/**
+ * Convert a single color channel value to hex
+ * @param value - Channel value (0-255)
+ * @returns Two-digit hex string
+ */
+export declare function channelToHex(value: number): string;
+/**
+ * Clamp RGB channel value to valid range
+ * @param value - Channel value
+ * @returns Clamped value (0-255)
+ */
+export declare function clampColorChannel(value: number): number;
+/**
+ * Clamp alpha value to valid range
+ * @param value - Alpha value
+ * @returns Clamped value (0-1)
+ */
+export declare function clampAlpha(value: number): number;
+/**
+ * Convert any color format to hex
+ * Supports: hex (#RGB, #RRGGBB, #RRGGBBAA), RGB/RGBA, and CSS color names
+ * @param value - Color string in any supported format
+ * @returns Hex color string (#RRGGBBAA) or undefined if invalid
+ */
+export declare function toHexColor(value: string): string | undefined;
+/**
+ * Darken a hex color by a specified amount
+ * @param hex - Hex color string
+ * @param amount - Amount to darken (0-255)
+ * @returns Darkened hex color
+ */
+export declare function darkenColor(hex: string, amount: number): string;
+/**
+ * Normalize any color format to Grid3's 8-digit hex format
+ * @param input - Color string in any supported format
+ * @param fallback - Fallback color if input is invalid (default: white)
+ * @returns Normalized color in format #AARRGGBBFF
+ */
+export declare function normalizeColor(input: string, fallback?: string): string;
+/**
+ * Ensure a color has an alpha channel (Grid3 format requires 8-digit ARGB)
+ * @param color - Color string (hex format)
+ * @returns Color with alpha channel in format #AARRGGBBFF
+ */
+export declare function ensureAlphaChannel(color: string | undefined): string;

package/dist/processors/gridset/colorUtils.js

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * Grid3 Color Utilities
+ *
+ * Comprehensive color handling for Grid3 format, including:
+ * - CSS color name lookup (147 named colors)
+ * - Color format conversion (hex, RGB, RGBA, named colors)
+ * - Color manipulation (darkening, normalization)
+ * - Grid3-specific color formatting (8-digit ARGB hex)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNamedColor = getNamedColor;
+exports.rgbaToHex = rgbaToHex;
+exports.channelToHex = channelToHex;
+exports.clampColorChannel = clampColorChannel;
+exports.clampAlpha = clampAlpha;
+exports.toHexColor = toHexColor;
+exports.darkenColor = darkenColor;
+exports.normalizeColor = normalizeColor;
+exports.ensureAlphaChannel = ensureAlphaChannel;
+/**
+ * CSS color names to RGB values
+ * Supports 147 standard CSS color names
+ */
+const CSS_COLORS = {
+    aliceblue: [240, 248, 255],
+    antiquewhite: [250, 235, 215],
+    aqua: [0, 255, 255],
+    aquamarine: [127, 255, 212],
+    azure: [240, 255, 255],
+    beige: [245, 245, 220],
+    bisque: [255, 228, 196],
+    black: [0, 0, 0],
+    blanchedalmond: [255, 235, 205],
+    blue: [0, 0, 255],
+    blueviolet: [138, 43, 226],
+    brown: [165, 42, 42],
+    burlywood: [222, 184, 135],
+    cadetblue: [95, 158, 160],
+    chartreuse: [127, 255, 0],
+    chocolate: [210, 105, 30],
+    coral: [255, 127, 80],
+    cornflowerblue: [100, 149, 237],
+    cornsilk: [255, 248, 220],
+    crimson: [220, 20, 60],
+    cyan: [0, 255, 255],
+    darkblue: [0, 0, 139],
+    darkcyan: [0, 139, 139],
+    darkgoldenrod: [184, 134, 11],
+    darkgray: [169, 169, 169],
+    darkgreen: [0, 100, 0],
+    darkgrey: [169, 169, 169],
+    darkkhaki: [189, 183, 107],
+    darkmagenta: [139, 0, 139],
+    darkolivegreen: [85, 107, 47],
+    darkorange: [255, 140, 0],
+    darkorchid: [153, 50, 204],
+    darkred: [139, 0, 0],
+    darksalmon: [233, 150, 122],
+    darkseagreen: [143, 188, 143],
+    darkslateblue: [72, 61, 139],
+    darkslategray: [47, 79, 79],
+    darkslategrey: [47, 79, 79],
+    darkturquoise: [0, 206, 209],
+    darkviolet: [148, 0, 211],
+    deeppink: [255, 20, 147],
+    deepskyblue: [0, 191, 255],
+    dimgray: [105, 105, 105],
+    dimgrey: [105, 105, 105],
+    dodgerblue: [30, 144, 255],
+    firebrick: [178, 34, 34],
+    floralwhite: [255, 250, 240],
+    forestgreen: [34, 139, 34],
+    fuchsia: [255, 0, 255],
+    gainsboro: [220, 220, 220],
+    ghostwhite: [248, 248, 255],
+    gold: [255, 215, 0],
+    goldenrod: [218, 165, 32],
+    gray: [128, 128, 128],
+    grey: [128, 128, 128],
+    green: [0, 128, 0],
+    greenyellow: [173, 255, 47],
+    honeydew: [240, 255, 240],
+    hotpink: [255, 105, 180],
+    indianred: [205, 92, 92],
+    indigo: [75, 0, 130],
+    ivory: [255, 255, 240],
+    khaki: [240, 230, 140],
+    lavender: [230, 230, 250],
+    lavenderblush: [255, 240, 245],
+    lawngreen: [124, 252, 0],
+    lemonchiffon: [255, 250, 205],
+    lightblue: [173, 216, 230],
+    lightcoral: [240, 128, 128],
+    lightcyan: [224, 255, 255],
+    lightgoldenrodyellow: [250, 250, 210],
+    lightgray: [211, 211, 211],
+    lightgreen: [144, 238, 144],
+    lightgrey: [211, 211, 211],
+    lightpink: [255, 182, 193],
+    lightsalmon: [255, 160, 122],
+    lightseagreen: [32, 178, 170],
+    lightskyblue: [135, 206, 250],
+    lightslategray: [119, 136, 153],
+    lightslategrey: [119, 136, 153],
+    lightsteelblue: [176, 196, 222],
+    lightyellow: [255, 255, 224],
+    lime: [0, 255, 0],
+    limegreen: [50, 205, 50],
+    linen: [250, 240, 230],
+    magenta: [255, 0, 255],
+    maroon: [128, 0, 0],
+    mediumaquamarine: [102, 205, 170],
+    mediumblue: [0, 0, 205],
+    mediumorchid: [186, 85, 211],
+    mediumpurple: [147, 112, 219],
+    mediumseagreen: [60, 179, 113],
+    mediumslateblue: [123, 104, 238],
+    mediumspringgreen: [0, 250, 154],
+    mediumturquoise: [72, 209, 204],
+    mediumvioletred: [199, 21, 133],
+    midnightblue: [25, 25, 112],
+    mintcream: [245, 255, 250],
+    mistyrose: [255, 228, 225],
+    moccasin: [255, 228, 181],
+    navajowhite: [255, 222, 173],
+    navy: [0, 0, 128],
+    oldlace: [253, 245, 230],
+    olive: [128, 128, 0],
+    olivedrab: [107, 142, 35],
+    orange: [255, 165, 0],
+    orangered: [255, 69, 0],
+    orchid: [218, 112, 214],
+    palegoldenrod: [238, 232, 170],
+    palegreen: [152, 251, 152],
+    paleturquoise: [175, 238, 238],
+    palevioletred: [219, 112, 147],
+    papayawhip: [255, 239, 213],
+    peachpuff: [255, 218, 185],
+    peru: [205, 133, 63],
+    pink: [255, 192, 203],
+    plum: [221, 160, 221],
+    powderblue: [176, 224, 230],
+    purple: [128, 0, 128],
+    rebeccapurple: [102, 51, 153],
+    red: [255, 0, 0],
+    rosybrown: [188, 143, 143],
+    royalblue: [65, 105, 225],
+    saddlebrown: [139, 69, 19],
+    salmon: [250, 128, 114],
+    sandybrown: [244, 164, 96],
+    seagreen: [46, 139, 87],
+    seashell: [255, 245, 238],
+    sienna: [160, 82, 45],
+    silver: [192, 192, 192],
+    skyblue: [135, 206, 235],
+    slateblue: [106, 90, 205],
+    slategray: [112, 128, 144],
+    slategrey: [112, 128, 144],
+    snow: [255, 250, 250],
+    springgreen: [0, 255, 127],
+    steelblue: [70, 130, 180],
+    tan: [210, 180, 140],
+    teal: [0, 128, 128],
+    thistle: [216, 191, 216],
+    tomato: [255, 99, 71],
+    turquoise: [64, 224, 208],
+    violet: [238, 130, 238],
+    wheat: [245, 222, 179],
+    white: [255, 255, 255],
+    whitesmoke: [245, 245, 245],
+    yellow: [255, 255, 0],
+    yellowgreen: [154, 205, 50],
+};
+/**
+ * Get RGB values for a CSS color name
+ * @param name - CSS color name (case-insensitive)
+ * @returns RGB tuple [r, g, b] or undefined if not found
+ */
+function getNamedColor(name) {
+    const color = CSS_COLORS[name.toLowerCase()];
+    return color;
+}
+/**
+ * Convert RGBA values to hex format
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @param a - Alpha channel (0-1)
+ * @returns Hex color string in format #RRGGBBAA
+ */
+function rgbaToHex(r, g, b, a) {
+    const red = channelToHex(r);
+    const green = channelToHex(g);
+    const blue = channelToHex(b);
+    const alpha = channelToHex(Math.round(a * 255));
+    return `#${red}${green}${blue}${alpha}`;
+}
+/**
+ * Convert a single color channel value to hex
+ * @param value - Channel value (0-255)
+ * @returns Two-digit hex string
+ */
+function channelToHex(value) {
+    const clamped = Math.max(0, Math.min(255, Math.round(value)));
+    return clamped.toString(16).padStart(2, '0').toUpperCase();
+}
+/**
+ * Clamp RGB channel value to valid range
+ * @param value - Channel value
+ * @returns Clamped value (0-255)
+ */
+function clampColorChannel(value) {
+    if (Number.isNaN(value)) {
+        return 0;
+    }
+    return Math.max(0, Math.min(255, value));
+}
+/**
+ * Clamp alpha value to valid range
+ * @param value - Alpha value
+ * @returns Clamped value (0-1)
+ */
+function clampAlpha(value) {
+    if (Number.isNaN(value)) {
+        return 1;
+    }
+    return Math.max(0, Math.min(1, value));
+}
+/**
+ * Convert any color format to hex
+ * Supports: hex (#RGB, #RRGGBB, #RRGGBBAA), RGB/RGBA, and CSS color names
+ * @param value - Color string in any supported format
+ * @returns Hex color string (#RRGGBBAA) or undefined if invalid
+ */
+function toHexColor(value) {
+    // Try hex format
+    const hexMatch = value.match(/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+    if (hexMatch) {
+        const hex = hexMatch[1];
+        if (hex.length === 3 || hex.length === 4) {
+            return `#${hex
+                .split('')
+                .map((char) => char + char)
+                .join('')}`;
+        }
+        return `#${hex}`;
+    }
+    // Try RGB/RGBA format
+    const rgbMatch = value.match(/^rgba?\((.+)\)$/i);
+    if (rgbMatch) {
+        const parts = rgbMatch[1]
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean);
+        if (parts.length === 3 || parts.length === 4) {
+            const [r, g, b, a] = parts;
+            const red = clampColorChannel(parseFloat(r));
+            const green = clampColorChannel(parseFloat(g));
+            const blue = clampColorChannel(parseFloat(b));
+            const alpha = parts.length === 4 ? clampAlpha(parseFloat(a)) : 1;
+            return rgbaToHex(red, green, blue, alpha);
+        }
+    }
+    // Try CSS color name
+    const rgb = getNamedColor(value);
+    if (rgb) {
+        return rgbaToHex(rgb[0], rgb[1], rgb[2], 1);
+    }
+    return undefined;
+}
+/**
+ * Darken a hex color by a specified amount
+ * @param hex - Hex color string
+ * @param amount - Amount to darken (0-255)
+ * @returns Darkened hex color
+ */
+function darkenColor(hex, amount) {
+    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) => 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()}`;
+}
+/**
+ * Normalize any color format to Grid3's 8-digit hex format
+ * @param input - Color string in any supported format
+ * @param fallback - Fallback color if input is invalid (default: white)
+ * @returns Normalized color in format #AARRGGBBFF
+ */
+function normalizeColor(input, fallback = '#FFFFFFFF') {
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return fallback;
+    }
+    const hex = toHexColor(trimmed);
+    if (hex) {
+        return ensureAlphaChannel(hex).toUpperCase();
+    }
+    return fallback;
+}
+/**
+ * Ensure a color has an alpha channel (Grid3 format requires 8-digit ARGB)
+ * @param color - Color string (hex format)
+ * @returns Color with alpha channel in format #AARRGGBBFF
+ */
+function ensureAlphaChannel(color) {
+    if (!color)
+        return '#FFFFFFFF';
+    // If already 8 digits (with alpha), return as is
+    if (color.match(/^#[0-9A-Fa-f]{8}$/))
+        return color;
+    // If 6 digits (no alpha), add FF for fully opaque
+    if (color.match(/^#[0-9A-Fa-f]{6}$/))
+        return color + 'FF';
+    // If 3 digits (shorthand), expand to 8
+    if (color.match(/^#[0-9A-Fa-f]{3}$/)) {
+        const r = color[1];
+        const g = color[2];
+        const b = color[3];
+        return `#${r}${r}${g}${g}${b}${b}FF`;
+    }
+    // Invalid or unknown format, return white
+    return '#FFFFFFFF';
+}

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

@@ -2,3 +2,33 @@ import { AACTree } from '../../core/treeStructure';
 export declare function getPageTokenImageMap(tree: AACTree, pageId: string): Map<string, string>;
 export declare function getAllowedImageEntries(tree: AACTree): Set<string>;
 export declare function openImage(gridsetBuffer: Buffer, entryPath: string): Buffer | null;
+/**
+ * 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 declare function generateGrid3Guid(): string;
+/**
+ * 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 declare function createSettingsXml(startGrid: string, options?: {
+    scanEnabled?: boolean;
+    scanTimeoutMs?: number;
+    hoverEnabled?: boolean;
+    hoverTimeoutMs?: number;
+    mouseclickEnabled?: boolean;
+    language?: string;
+}): string;
+/**
+ * Create Grid3 FileMap.xml content
+ * @param grids - Array of grid configurations with name and path
+ * @returns XML string for FileMap.xml
+ */
+export declare function createFileMapXml(grids: Array<{
+    name: string;
+    path: string;
+    dynamicFiles?: string[];
+}>): string;

package/dist/processors/gridset/helpers.js

@@ -6,7 +6,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPageTokenImageMap = getPageTokenImageMap;
 exports.getAllowedImageEntries = getAllowedImageEntries;
 exports.openImage = openImage;
+exports.generateGrid3Guid = generateGrid3Guid;
+exports.createSettingsXml = createSettingsXml;
+exports.createFileMapXml = createFileMapXml;
 const adm_zip_1 = __importDefault(require("adm-zip"));
+const fast_xml_parser_1 = require("fast-xml-parser");
 function normalizeZipPath(p) {
     const unified = p.replace(/\\/g, '/');
     try {
@@ -46,3 +50,68 @@ function openImage(gridsetBuffer, entryPath) {
         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
+ */
+function generateGrid3Guid() {
+    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
+ */
+function createSettingsXml(startGrid, options) {
+    const builder = new fast_xml_parser_1.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
+ */
+function createFileMapXml(grids) {
+    const builder = new fast_xml_parser_1.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);
+}

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

@@ -25,11 +25,10 @@ export declare const DEFAULT_GRID3_STYLES: Record<string, Grid3Style>;
  */
 export declare const CATEGORY_STYLES: Record<string, Grid3Style>;
 /**
- * Ensure a color has an alpha channel (Grid3 format requires 8-digit ARGB)
- * @param color - Color string (hex format)
- * @returns Color with alpha channel in format #AARRGGBBFF
+ * Re-export ensureAlphaChannel from colorUtils for backward compatibility
+ * @deprecated Use ensureAlphaChannel from colorUtils instead
  */
-export declare function ensureAlphaChannel(color: string | undefined): string;
+export { ensureAlphaChannel } from './colorUtils';
 /**
  * Create a Grid3 style XML string with default and category styles
  * @param includeCategories - Whether to include category-specific styles (default: true)

package/dist/processors/gridset/styleHelpers.js

@@ -6,11 +6,11 @@
  * style XML generation, and style conversion utilities.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = void 0;
-exports.ensureAlphaChannel = ensureAlphaChannel;
+exports.ensureAlphaChannel = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = void 0;
 exports.createDefaultStylesXml = createDefaultStylesXml;
 exports.createCategoryStyle = createCategoryStyle;
 const fast_xml_parser_1 = require("fast-xml-parser");
+const colorUtils_1 = require("./colorUtils");
 /**
  * Default Grid3 styles for common use cases
  * Colors are in 8-digit ARGB hex format (#AARRGGBBFF)
@@ -119,29 +119,11 @@ exports.CATEGORY_STYLES = {
     },
 };
 /**
- * Ensure a color has an alpha channel (Grid3 format requires 8-digit ARGB)
- * @param color - Color string (hex format)
- * @returns Color with alpha channel in format #AARRGGBBFF
+ * Re-export ensureAlphaChannel from colorUtils for backward compatibility
+ * @deprecated Use ensureAlphaChannel from colorUtils instead
  */
-function ensureAlphaChannel(color) {
-    if (!color)
-        return '#FFFFFFFF';
-    // If already 8 digits (with alpha), return as is
-    if (color.match(/^#[0-9A-Fa-f]{8}$/))
-        return color;
-    // If 6 digits (no alpha), add FF for fully opaque
-    if (color.match(/^#[0-9A-Fa-f]{6}$/))
-        return color + 'FF';
-    // If 3 digits (shorthand), expand to 8
-    if (color.match(/^#[0-9A-Fa-f]{3}$/)) {
-        const r = color[1];
-        const g = color[2];
-        const b = color[3];
-        return `#${r}${r}${g}${g}${b}${b}FF`;
-    }
-    // Invalid or unknown format, return white
-    return '#FFFFFFFF';
-}
+var colorUtils_2 = require("./colorUtils");
+Object.defineProperty(exports, "ensureAlphaChannel", { enumerable: true, get: function () { return colorUtils_2.ensureAlphaChannel; } });
 /**
  * Create a Grid3 style XML string with default and category styles
  * @param includeCategories - Whether to include category-specific styles (default: true)
@@ -185,27 +167,11 @@ function createDefaultStylesXml(includeCategories = true) {
  */
 function createCategoryStyle(categoryName, backgroundColor, fontColor = '#FFFFFFFF') {
     return {
-        BackColour: ensureAlphaChannel(backgroundColor),
-        TileColour: ensureAlphaChannel(backgroundColor),
-        BorderColour: ensureAlphaChannel(darkenColor(backgroundColor, 30)),
-        FontColour: ensureAlphaChannel(fontColor),
+        BackColour: (0, colorUtils_1.ensureAlphaChannel)(backgroundColor),
+        TileColour: (0, colorUtils_1.ensureAlphaChannel)(backgroundColor),
+        BorderColour: (0, colorUtils_1.ensureAlphaChannel)((0, colorUtils_1.darkenColor)(backgroundColor, 30)),
+        FontColour: (0, colorUtils_1.ensureAlphaChannel)(fontColor),
         FontName: 'Arial',
         FontSize: '16',
     };
 }
-/**
- * Darken a hex color by a given amount
- * @param hexColor - Hex color string
- * @param amount - Amount to darken (0-255)
- * @returns Darkened hex color
- */
-function darkenColor(hexColor, amount) {
-    const normalized = ensureAlphaChannel(hexColor);
-    const hex = normalized.slice(1, 7); // Extract RGB part (skip # and alpha)
-    const num = parseInt(hex, 16);
-    const clamp = (value) => Math.max(0, Math.min(255, value));
-    const r = clamp(((num >> 16) & 0xff) - amount);
-    const g = clamp(((num >> 8) & 0xff) - amount);
-    const b = clamp((num & 0xff) - amount);
-    return `#${((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1)}`;
-}

package/dist/processors/index.d.ts

@@ -7,10 +7,12 @@ export { OpmlProcessor } from './opmlProcessor';
 export { SnapProcessor } from './snapProcessor';
 export { TouchChatProcessor } from './touchchatProcessor';
 export { AstericsGridProcessor } from './astericsGridProcessor';
-export { getPageTokenImageMap, getAllowedImageEntries, openImage } from './gridset/helpers';
-export { getPageTokenImageMap as getGridsetPageTokenImageMap, getAllowedImageEntries as getGridsetAllowedImageEntries, openImage as openGridsetImage, } 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';
 export { createWordlist, extractWordlists, updateWordlist, wordlistToXml, type WordList, type WordListItem, } from './gridset/wordlistHelpers';
-export { DEFAULT_GRID3_STYLES, CATEGORY_STYLES, ensureAlphaChannel, createDefaultStylesXml, createCategoryStyle, type Grid3Style, } from './gridset/styleHelpers';
+export { getNamedColor, rgbaToHex, channelToHex, clampColorChannel, clampAlpha, toHexColor, darkenColor, normalizeColor, ensureAlphaChannel, } from './gridset/colorUtils';
+export { DEFAULT_GRID3_STYLES, CATEGORY_STYLES, createDefaultStylesXml, createCategoryStyle, } from './gridset/styleHelpers';
+export { ensureAlphaChannel as ensureAlphaChannelFromStyles } from './gridset/styleHelpers';
 export { getPageTokenImageMap as getSnapPageTokenImageMap, getAllowedImageEntries as getSnapAllowedImageEntries, openImage as openSnapImage, } from './snap/helpers';
 export { getPageTokenImageMap as getTouchChatPageTokenImageMap, getAllowedImageEntries as getTouchChatAllowedImageEntries, openImage as openTouchChatImage, } from './touchchat/helpers';

package/dist/processors/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openTouchChatImage = exports.getTouchChatAllowedImageEntries = exports.getTouchChatPageTokenImageMap = exports.openSnapImage = exports.getSnapAllowedImageEntries = exports.getSnapPageTokenImageMap = exports.createCategoryStyle = exports.createDefaultStylesXml = exports.ensureAlphaChannel = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = exports.wordlistToXml = exports.updateWordlist = exports.extractWordlists = exports.createWordlist = exports.resolveGrid3CellImage = exports.openGridsetImage = exports.getGridsetAllowedImageEntries = exports.getGridsetPageTokenImageMap = exports.openImage = exports.getAllowedImageEntries = exports.getPageTokenImageMap = exports.AstericsGridProcessor = exports.TouchChatProcessor = exports.SnapProcessor = exports.OpmlProcessor = exports.ObfProcessor = exports.GridsetProcessor = exports.ExcelProcessor = exports.DotProcessor = exports.ApplePanelsProcessor = void 0;
+exports.openTouchChatImage = exports.getTouchChatAllowedImageEntries = exports.getTouchChatPageTokenImageMap = exports.openSnapImage = exports.getSnapAllowedImageEntries = exports.getSnapPageTokenImageMap = exports.ensureAlphaChannelFromStyles = 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.resolveGrid3CellImage = exports.createGridsetFileMapXml = exports.createGridsetSettingsXml = exports.generateGridsetGuid = exports.openGridsetImage = exports.getGridsetAllowedImageEntries = exports.getGridsetPageTokenImageMap = exports.createFileMapXml = exports.createSettingsXml = exports.generateGrid3Guid = exports.openImage = exports.getAllowedImageEntries = exports.getPageTokenImageMap = exports.AstericsGridProcessor = exports.TouchChatProcessor = exports.SnapProcessor = exports.OpmlProcessor = exports.ObfProcessor = exports.GridsetProcessor = exports.ExcelProcessor = exports.DotProcessor = exports.ApplePanelsProcessor = void 0;
 var applePanelsProcessor_1 = require("./applePanelsProcessor");
 Object.defineProperty(exports, "ApplePanelsProcessor", { enumerable: true, get: function () { return applePanelsProcessor_1.ApplePanelsProcessor; } });
 var dotProcessor_1 = require("./dotProcessor");
@@ -24,10 +24,16 @@ var helpers_1 = require("./gridset/helpers");
 Object.defineProperty(exports, "getPageTokenImageMap", { enumerable: true, get: function () { return helpers_1.getPageTokenImageMap; } });
 Object.defineProperty(exports, "getAllowedImageEntries", { enumerable: true, get: function () { return helpers_1.getAllowedImageEntries; } });
 Object.defineProperty(exports, "openImage", { enumerable: true, get: function () { return helpers_1.openImage; } });
+Object.defineProperty(exports, "generateGrid3Guid", { enumerable: true, get: function () { return helpers_1.generateGrid3Guid; } });
+Object.defineProperty(exports, "createSettingsXml", { enumerable: true, get: function () { return helpers_1.createSettingsXml; } });
+Object.defineProperty(exports, "createFileMapXml", { enumerable: true, get: function () { return helpers_1.createFileMapXml; } });
 var helpers_2 = require("./gridset/helpers");
 Object.defineProperty(exports, "getGridsetPageTokenImageMap", { enumerable: true, get: function () { return helpers_2.getPageTokenImageMap; } });
 Object.defineProperty(exports, "getGridsetAllowedImageEntries", { enumerable: true, get: function () { return helpers_2.getAllowedImageEntries; } });
 Object.defineProperty(exports, "openGridsetImage", { enumerable: true, get: function () { return helpers_2.openImage; } });
+Object.defineProperty(exports, "generateGridsetGuid", { enumerable: true, get: function () { return helpers_2.generateGrid3Guid; } });
+Object.defineProperty(exports, "createGridsetSettingsXml", { enumerable: true, get: function () { return helpers_2.createSettingsXml; } });
+Object.defineProperty(exports, "createGridsetFileMapXml", { enumerable: true, get: function () { return helpers_2.createFileMapXml; } });
 var resolver_1 = require("./gridset/resolver");
 Object.defineProperty(exports, "resolveGrid3CellImage", { enumerable: true, get: function () { return resolver_1.resolveGrid3CellImage; } });
 // Gridset (Grid 3) wordlist helpers
@@ -36,13 +42,26 @@ Object.defineProperty(exports, "createWordlist", { enumerable: true, get: functi
 Object.defineProperty(exports, "extractWordlists", { enumerable: true, get: function () { return wordlistHelpers_1.extractWordlists; } });
 Object.defineProperty(exports, "updateWordlist", { enumerable: true, get: function () { return wordlistHelpers_1.updateWordlist; } });
 Object.defineProperty(exports, "wordlistToXml", { enumerable: true, get: function () { return wordlistHelpers_1.wordlistToXml; } });
+// Gridset (Grid 3) color utilities
+var colorUtils_1 = require("./gridset/colorUtils");
+Object.defineProperty(exports, "getNamedColor", { enumerable: true, get: function () { return colorUtils_1.getNamedColor; } });
+Object.defineProperty(exports, "rgbaToHex", { enumerable: true, get: function () { return colorUtils_1.rgbaToHex; } });
+Object.defineProperty(exports, "channelToHex", { enumerable: true, get: function () { return colorUtils_1.channelToHex; } });
+Object.defineProperty(exports, "clampColorChannel", { enumerable: true, get: function () { return colorUtils_1.clampColorChannel; } });
+Object.defineProperty(exports, "clampAlpha", { enumerable: true, get: function () { return colorUtils_1.clampAlpha; } });
+Object.defineProperty(exports, "toHexColor", { enumerable: true, get: function () { return colorUtils_1.toHexColor; } });
+Object.defineProperty(exports, "darkenColor", { enumerable: true, get: function () { return colorUtils_1.darkenColor; } });
+Object.defineProperty(exports, "normalizeColor", { enumerable: true, get: function () { return colorUtils_1.normalizeColor; } });
+Object.defineProperty(exports, "ensureAlphaChannel", { enumerable: true, get: function () { return colorUtils_1.ensureAlphaChannel; } });
 // Gridset (Grid 3) style helpers
 var styleHelpers_1 = require("./gridset/styleHelpers");
 Object.defineProperty(exports, "DEFAULT_GRID3_STYLES", { enumerable: true, get: function () { return styleHelpers_1.DEFAULT_GRID3_STYLES; } });
 Object.defineProperty(exports, "CATEGORY_STYLES", { enumerable: true, get: function () { return styleHelpers_1.CATEGORY_STYLES; } });
-Object.defineProperty(exports, "ensureAlphaChannel", { enumerable: true, get: function () { return styleHelpers_1.ensureAlphaChannel; } });
 Object.defineProperty(exports, "createDefaultStylesXml", { enumerable: true, get: function () { return styleHelpers_1.createDefaultStylesXml; } });
 Object.defineProperty(exports, "createCategoryStyle", { enumerable: true, get: function () { return styleHelpers_1.createCategoryStyle; } });
+// Re-export ensureAlphaChannel from styleHelpers for backward compatibility
+var styleHelpers_2 = require("./gridset/styleHelpers");
+Object.defineProperty(exports, "ensureAlphaChannelFromStyles", { enumerable: true, get: function () { return styleHelpers_2.ensureAlphaChannel; } });
 // Snap helpers (stubs)
 var helpers_3 = require("./snap/helpers");
 Object.defineProperty(exports, "getSnapPageTokenImageMap", { enumerable: true, get: function () { return helpers_3.getPageTokenImageMap; } });

package/dist/processors/obfProcessor.js

@@ -144,12 +144,15 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 }
                 const obj = JSON.parse(str);
                 if (obj && typeof obj === 'object' && 'id' in obj && 'buttons' in obj) {
+                    // Validate buttons is an array
+                    if (!Array.isArray(obj.buttons)) {
+                        throw new Error('Invalid OBF: buttons must be an array');
+                    }
                     return obj;
                 }
             }
             catch (error) {
                 // Log parsing errors for debugging but don't throw
-                console.warn(`Failed to parse OBF JSON: ${error.message}`);
             }
             return null;
         }

package/dist/processors/snapProcessor.js

@@ -476,11 +476,33 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                         serializedMetadata = audio.metadata || null;
                         useMessageRecording = 1;
                     }
-                    insertButton.run(buttonIdCounter++, button.label || '', button.message || button.label || '', navigatePageId, elementRefId, null, null, messageRecordingId, serializedMetadata, useMessageRecording, button.style?.fontColor ? parseInt(button.style.fontColor.replace('#', ''), 16) : null, button.style?.backgroundColor
-                        ? parseInt(button.style.backgroundColor.replace('#', ''), 16)
-                        : null, button.style?.borderColor
-                        ? parseInt(button.style.borderColor.replace('#', ''), 16)
-                        : null, button.style?.borderWidth, button.style?.fontSize, button.style?.fontFamily, button.style?.fontStyle ? parseInt(button.style.fontStyle) : null);
+                    // Retry logic for SQLite operations
+                    let retries = 3;
+                    while (retries > 0) {
+                        try {
+                            insertButton.run(buttonIdCounter++, button.label || '', button.message || button.label || '', navigatePageId, elementRefId, null, null, messageRecordingId, serializedMetadata, useMessageRecording, button.style?.fontColor
+                                ? parseInt(button.style.fontColor.replace('#', ''), 16)
+                                : null, button.style?.backgroundColor
+                                ? parseInt(button.style.backgroundColor.replace('#', ''), 16)
+                                : null, button.style?.borderColor
+                                ? parseInt(button.style.borderColor.replace('#', ''), 16)
+                                : null, button.style?.borderWidth, button.style?.fontSize, button.style?.fontFamily, button.style?.fontStyle ? parseInt(button.style.fontStyle) : null);
+                            break; // Success
+                        }
+                        catch (err) {
+                            if (err.code === 'SQLITE_IOERR' && retries > 1) {
+                                retries--;
+                                // Wait a bit before retrying
+                                const now = Date.now();
+                                while (Date.now() - now < 100) {
+                                    /* busy wait */
+                                }
+                            }
+                            else {
+                                throw err;
+                            }
+                        }
+                    }
                     // Insert ElementPlacement
                     const insertPlacement = db.prepare('INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition) VALUES (?, ?, ?)');
                     insertPlacement.run(placementIdCounter++, elementRefId, gridPosition);

package/package.json

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