@willwade/aac-processors 0.0.9 → 0.0.11

package/dist/processors/gridset/pluginTypes.js

@@ -0,0 +1,285 @@
+"use strict";
+/**
+ * Grid 3 Plugin Cell Type Detection
+ *
+ * Grid 3 uses three special cell types for different plugin functionalities:
+ * - Workspace: Full editing workspaces (Email, Chat, WordProcessor, etc.)
+ * - LiveCell: Dynamic content displays (Clock, Volume indicators, etc.)
+ * - AutoContent: Dynamic word/content suggestions
+ *
+ * This module provides detection and metadata extraction for these cell types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTOCONTENT_TYPES = exports.LIVECELL_TYPES = exports.WORKSPACE_TYPES = exports.Grid3CellType = void 0;
+exports.getCellTypeDisplayName = getCellTypeDisplayName;
+exports.detectPluginCellType = detectPluginCellType;
+exports.isWorkspaceCell = isWorkspaceCell;
+exports.isLiveCell = isLiveCell;
+exports.isAutoContentCell = isAutoContentCell;
+exports.isRegularCell = isRegularCell;
+/**
+ * Cell types in Grid 3
+ */
+var Grid3CellType;
+(function (Grid3CellType) {
+    Grid3CellType["Regular"] = "regular";
+    Grid3CellType["Workspace"] = "workspace";
+    Grid3CellType["LiveCell"] = "livecell";
+    Grid3CellType["AutoContent"] = "autocontent";
+})(Grid3CellType || (exports.Grid3CellType = Grid3CellType = {}));
+/**
+ * Known workspace types in Grid 3
+ */
+exports.WORKSPACE_TYPES = {
+    CHAT: 'Chat',
+    EMAIL: 'Email',
+    WORD_PROCESSOR: 'WordProcessor',
+    PHONE: 'Phone',
+    SMS: 'Sms',
+    WEB_BROWSER: 'WebBrowser',
+    COMPUTER_CONTROL: 'ComputerControl',
+    CALCULATOR: 'Calculator',
+    TIMER: 'Timer',
+    MUSIC_VIDEO: 'MusicVideo',
+    PHOTOS: 'Photos',
+    CONTACTS: 'Contacts',
+    INTERACTIVE_LEARNING: 'InteractiveLearning',
+    MESSAGE_BANKING: 'MessageBanking',
+    ENVIRONMENT_CONTROL: 'EnvironmentControl',
+    SETTINGS: 'Settings',
+};
+/**
+ * Known live cell types in Grid 3
+ */
+exports.LIVECELL_TYPES = {
+    DIGITAL_CLOCK: 'DigitalClock',
+    ANALOG_CLOCK: 'AnalogClock',
+    DATE_DISPLAY: 'DateDisplay',
+    PUBLIC_VOLUME: 'PublicVolume',
+    PUBLIC_SPEED: 'PublicSpeed',
+    PUBLIC_VOICE: 'PublicVoice',
+    MESSAGES: 'Messages',
+    BATTERY: 'Battery',
+    WIFI_STRENGTH: 'WifiStrength',
+    BLUETOOTH_STATUS: 'BluetoothStatus',
+};
+/**
+ * Known auto content types in Grid 3
+ */
+exports.AUTOCONTENT_TYPES = {
+    CHANGE_PUBLIC_VOICE: 'ChangePublicVoice',
+    CHANGE_PUBLIC_SPEED: 'ChangePublicSpeed',
+    EMAIL_CONTACTS: 'EmailContacts',
+    EMAIL_RECIPIENTS: 'EmailRecipients',
+    PHONE_CONTACTS: 'PhoneContacts',
+    SMS_CONTACTS: 'SmsContacts',
+    WEB_FAVORITES: 'WebFavorites',
+    WEB_HISTORY: 'WebHistory',
+    PREDICTION: 'Prediction',
+    GRAMMAR: 'Grammar',
+    CONTEXTUAL: 'Contextual',
+};
+/**
+ * Human-readable names for cell types
+ */
+function getCellTypeDisplayName(cellType) {
+    switch (cellType) {
+        case Grid3CellType.Workspace:
+            return 'Workspace';
+        case Grid3CellType.LiveCell:
+            return 'Live Cell';
+        case Grid3CellType.AutoContent:
+            return 'Auto Content';
+        case Grid3CellType.Regular:
+            return 'Regular';
+        default:
+            return 'Unknown';
+    }
+}
+/**
+ * Detect plugin cell type from Grid 3 cell content
+ *
+ * @param content - Grid 3 cell content object
+ * @returns Plugin metadata with detected type
+ */
+function detectPluginCellType(content) {
+    if (!content) {
+        return { cellType: Grid3CellType.Regular };
+    }
+    const contentType = content.ContentType || content.contenttype || content.ContentType;
+    const contentSubType = content.ContentSubType || content.contentsubtype || content.ContentSubType;
+    // Workspace cells - full editing workspaces
+    if (contentType === 'Workspace') {
+        return {
+            cellType: Grid3CellType.Workspace,
+            subType: contentSubType || undefined,
+            pluginId: inferWorkspacePlugin(String(contentSubType || '')),
+            displayName: contentSubType ? `${contentSubType} Workspace` : 'Workspace',
+        };
+    }
+    // LiveCell detection - dynamic content displays
+    if (contentType === 'LiveCell') {
+        return {
+            cellType: Grid3CellType.LiveCell,
+            liveCellType: contentSubType || undefined,
+            pluginId: inferLiveCellPlugin(String(contentSubType || '')),
+            displayName: contentSubType || 'Live Cell',
+        };
+    }
+    // AutoContent detection - dynamic word/content suggestions
+    if (contentType === 'AutoContent') {
+        const autoContentType = extractAutoContentType(content);
+        return {
+            cellType: Grid3CellType.AutoContent,
+            autoContentType: autoContentType || undefined,
+            pluginId: inferAutoContentPlugin(autoContentType),
+            displayName: autoContentType || 'Auto Content',
+        };
+    }
+    // Regular cell
+    return {
+        cellType: Grid3CellType.Regular,
+    };
+}
+/**
+ * Extract auto content type from AutoContent.Activate command
+ */
+function extractAutoContentType(content) {
+    const commands = content.Commands?.Command || content.commands?.command;
+    if (!commands)
+        return undefined;
+    const commandArr = Array.isArray(commands) ? commands : [commands];
+    for (const command of commandArr) {
+        const commandId = command['@_ID'] || command.ID || command.id;
+        if (commandId === 'AutoContent.Activate') {
+            const parameters = command.Parameter || command.parameter;
+            const paramArr = Array.isArray(parameters) ? parameters : parameters ? [parameters] : [];
+            for (const param of paramArr) {
+                const key = param['@_Key'] || param.Key || param.key;
+                if (key === 'autocontenttype') {
+                    return String(param['#text'] || param.text || param.value || '');
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Infer plugin ID from workspace subtype
+ */
+function inferWorkspacePlugin(subType) {
+    if (!subType)
+        return undefined;
+    const normalized = subType.toLowerCase();
+    if (normalized.includes('chat'))
+        return 'chat';
+    if (normalized.includes('email') || normalized.includes('mail'))
+        return 'email';
+    if (normalized.includes('word') || normalized.includes('processor'))
+        return 'wordprocessor';
+    if (normalized.includes('phone'))
+        return 'phone';
+    if (normalized.includes('sms') || normalized.includes('text'))
+        return 'sms';
+    if (normalized.includes('web') || normalized.includes('browser'))
+        return 'webbrowser';
+    if (normalized.includes('computer') || normalized.includes('control'))
+        return 'computercontrol';
+    if (normalized.includes('calculator') || normalized.includes('calc'))
+        return 'calculator';
+    if (normalized.includes('timer') || normalized.includes('stopwatch'))
+        return 'timer';
+    if (normalized.includes('music') || normalized.includes('video'))
+        return 'musicvideo';
+    if (normalized.includes('photo') || normalized.includes('image'))
+        return 'photos';
+    if (normalized.includes('contact'))
+        return 'contacts';
+    if (normalized.includes('learning'))
+        return 'interactivelearning';
+    if (normalized.includes('message') && normalized.includes('bank'))
+        return 'messagebanking';
+    if (normalized.includes('env') || normalized.includes('ir'))
+        return 'environmentcontrol';
+    if (normalized.includes('setting'))
+        return 'settings';
+    return undefined;
+}
+/**
+ * Infer plugin ID from live cell type
+ */
+function inferLiveCellPlugin(liveCellType) {
+    if (!liveCellType)
+        return undefined;
+    const normalized = liveCellType.toLowerCase();
+    if (normalized.includes('clock') || normalized.includes('time') || normalized.includes('date')) {
+        return 'clock';
+    }
+    if (normalized.includes('volume'))
+        return 'speech';
+    if (normalized.includes('speed'))
+        return 'speech';
+    if (normalized.includes('voice'))
+        return 'speech';
+    if (normalized.includes('message'))
+        return 'chat';
+    if (normalized.includes('battery'))
+        return 'settings';
+    if (normalized.includes('wifi') || normalized.includes('network'))
+        return 'settings';
+    if (normalized.includes('bluetooth'))
+        return 'settings';
+    return undefined;
+}
+/**
+ * Infer plugin ID from auto content type
+ */
+function inferAutoContentPlugin(autoContentType) {
+    if (!autoContentType)
+        return undefined;
+    const normalized = autoContentType.toLowerCase();
+    if (normalized.includes('voice') || normalized.includes('speed'))
+        return 'speech';
+    if (normalized.includes('email') || normalized.includes('mail'))
+        return 'email';
+    if (normalized.includes('phone'))
+        return 'phone';
+    if (normalized.includes('sms') || normalized.includes('text'))
+        return 'sms';
+    if (normalized.includes('web') ||
+        normalized.includes('favorite') ||
+        normalized.includes('history')) {
+        return 'webbrowser';
+    }
+    if (normalized.includes('prediction'))
+        return 'prediction';
+    if (normalized.includes('grammar'))
+        return 'grammar';
+    if (normalized.includes('context'))
+        return 'autocontent';
+    return undefined;
+}
+/**
+ * Check if a cell is a workspace cell
+ */
+function isWorkspaceCell(metadata) {
+    return metadata.cellType === Grid3CellType.Workspace;
+}
+/**
+ * Check if a cell is a live cell
+ */
+function isLiveCell(metadata) {
+    return metadata.cellType === Grid3CellType.LiveCell;
+}
+/**
+ * Check if a cell is an auto content cell
+ */
+function isAutoContentCell(metadata) {
+    return metadata.cellType === Grid3CellType.AutoContent;
+}
+/**
+ * Check if a cell is a regular (non-plugin) cell
+ */
+function isRegularCell(metadata) {
+    return metadata.cellType === Grid3CellType.Regular;
+}

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

@@ -1,3 +1,4 @@
+import { parseSymbolReference } from './symbols';
 export declare function resolveGrid3CellImage(zip: any, args: {
     baseDir: string;
     imageName?: string;
@@ -5,4 +6,16 @@ export declare function resolveGrid3CellImage(zip: any, args: {
     y?: number;
     dynamicFiles?: string[];
     builtinHandler?: (name: string) => string | null;
-}): string | null;
+}, zipEntries?: any[]): string | null;
+/**
+ * Check if an image reference is a symbol library reference
+ * @param imageName - Image reference from Grid 3
+ * @returns True if it's a symbol library reference
+ */
+export declare function isSymbolLibraryReference(imageName?: string): boolean;
+/**
+ * Parse a symbol library reference from an image name
+ * @param imageName - Image reference from Grid 3
+ * @returns Parsed reference or null if not a symbol reference
+ */
+export declare function parseImageSymbolReference(imageName: string): ReturnType<typeof parseSymbolReference> | null;

package/dist/processors/gridset/resolver.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveGrid3CellImage = resolveGrid3CellImage;
+exports.isSymbolLibraryReference = isSymbolLibraryReference;
+exports.parseImageSymbolReference = parseImageSymbolReference;
+const symbols_1 = require("./symbols");
 function normalizeZipPathLocal(p) {
     const unified = p.replace(/\\/g, '/');
     try {
@@ -10,9 +13,13 @@ function normalizeZipPathLocal(p) {
         return unified;
     }
 }
-function listZipEntries(zip) {
+function listZipEntries(zip, zipEntries) {
     try {
-        const raw = typeof zip?.getEntries === 'function' ? zip.getEntries() : [];
+        const raw = Array.isArray(zipEntries) && zipEntries.length > 0
+            ? zipEntries
+            : typeof zip?.getEntries === 'function'
+                ? zip.getEntries()
+                : [];
         let entries = [];
         if (Array.isArray(raw))
             entries = raw;
@@ -33,15 +40,29 @@ function joinBaseDir(baseDir, leaf) {
     const base = normalizeZipPathLocal(baseDir).replace(/\/?$/, '/');
     return normalizeZipPathLocal(base + leaf.replace(/^\//, ''));
 }
-function resolveGrid3CellImage(zip, args) {
+function resolveGrid3CellImage(zip, args, zipEntries) {
     const { baseDir, dynamicFiles } = args;
     const imageName = args.imageName?.trim();
     const x = args.x;
     const y = args.y;
-    const entries = new Set(listZipEntries(zip));
+    const entries = new Set(listZipEntries(zip, zipEntries));
     const has = (p) => entries.has(normalizeZipPathLocal(p));
-    // Built-in resource like [grid3x]...
+    // 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 ((0, symbols_1.isSymbolReference)(imageName)) {
+            const parsed = (0, symbols_1.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)
@@ -98,3 +119,24 @@ function resolveGrid3CellImage(zip, args) {
     }
     return null;
 }
+/**
+ * Check if an image reference is a symbol library reference
+ * @param imageName - Image reference from Grid 3
+ * @returns True if it's a symbol library reference
+ */
+function isSymbolLibraryReference(imageName) {
+    if (!imageName)
+        return false;
+    return (0, symbols_1.isSymbolReference)(imageName.trim());
+}
+/**
+ * Parse a symbol library reference from an image name
+ * @param imageName - Image reference from Grid 3
+ * @returns Parsed reference or null if not a symbol reference
+ */
+function parseImageSymbolReference(imageName) {
+    if (!isSymbolLibraryReference(imageName)) {
+        return null;
+    }
+    return (0, symbols_1.parseSymbolReference)(imageName.trim());
+}

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

@@ -4,6 +4,27 @@
  * Utilities for creating and managing Grid3 styles, including default styles,
  * style XML generation, and style conversion utilities.
  */
+/**
+ * Cell background shapes supported by Grid 3
+ * Maps to Grid 3's CellBackgroundShape enum
+ */
+export declare enum CellBackgroundShape {
+    Rectangle = 0,
+    RoundedRectangle = 1,
+    FoldedCorner = 2,
+    Octagon = 3,
+    Folder = 4,
+    Ellipse = 5,
+    SpeechBubble = 6,
+    ThoughtBubble = 7,
+    Star = 8,
+    Circle = 9,
+    ColouredCorner = 10
+}
+/**
+ * Human-readable shape names
+ */
+export declare const SHAPE_NAMES: Record<CellBackgroundShape, string>;
 /**
  * Grid3 Style object structure
  */
@@ -14,6 +35,7 @@ export interface Grid3Style {
     FontColour?: string;
     FontName?: string;
     FontSize?: string | number;
+    BackgroundShape?: CellBackgroundShape;
 }
 /**
  * Default Grid3 styles for common use cases

package/dist/processors/gridset/styleHelpers.js

@@ -6,11 +6,45 @@
  * style XML generation, and style conversion utilities.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ensureAlphaChannel = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = void 0;
+exports.ensureAlphaChannel = exports.CATEGORY_STYLES = exports.DEFAULT_GRID3_STYLES = exports.SHAPE_NAMES = exports.CellBackgroundShape = void 0;
 exports.createDefaultStylesXml = createDefaultStylesXml;
 exports.createCategoryStyle = createCategoryStyle;
 const fast_xml_parser_1 = require("fast-xml-parser");
 const colorUtils_1 = require("./colorUtils");
+/**
+ * Cell background shapes supported by Grid 3
+ * Maps to Grid 3's CellBackgroundShape enum
+ */
+var CellBackgroundShape;
+(function (CellBackgroundShape) {
+    CellBackgroundShape[CellBackgroundShape["Rectangle"] = 0] = "Rectangle";
+    CellBackgroundShape[CellBackgroundShape["RoundedRectangle"] = 1] = "RoundedRectangle";
+    CellBackgroundShape[CellBackgroundShape["FoldedCorner"] = 2] = "FoldedCorner";
+    CellBackgroundShape[CellBackgroundShape["Octagon"] = 3] = "Octagon";
+    CellBackgroundShape[CellBackgroundShape["Folder"] = 4] = "Folder";
+    CellBackgroundShape[CellBackgroundShape["Ellipse"] = 5] = "Ellipse";
+    CellBackgroundShape[CellBackgroundShape["SpeechBubble"] = 6] = "SpeechBubble";
+    CellBackgroundShape[CellBackgroundShape["ThoughtBubble"] = 7] = "ThoughtBubble";
+    CellBackgroundShape[CellBackgroundShape["Star"] = 8] = "Star";
+    CellBackgroundShape[CellBackgroundShape["Circle"] = 9] = "Circle";
+    CellBackgroundShape[CellBackgroundShape["ColouredCorner"] = 10] = "ColouredCorner";
+})(CellBackgroundShape || (exports.CellBackgroundShape = CellBackgroundShape = {}));
+/**
+ * Human-readable shape names
+ */
+exports.SHAPE_NAMES = {
+    [CellBackgroundShape.Rectangle]: 'Rectangle',
+    [CellBackgroundShape.RoundedRectangle]: 'Rounded Rectangle',
+    [CellBackgroundShape.FoldedCorner]: 'Folded Corner',
+    [CellBackgroundShape.Octagon]: 'Octagon',
+    [CellBackgroundShape.Folder]: 'Folder',
+    [CellBackgroundShape.Ellipse]: 'Ellipse',
+    [CellBackgroundShape.SpeechBubble]: 'Speech Bubble',
+    [CellBackgroundShape.ThoughtBubble]: 'Thought Bubble',
+    [CellBackgroundShape.Star]: 'Star',
+    [CellBackgroundShape.Circle]: 'Circle',
+    [CellBackgroundShape.ColouredCorner]: 'Coloured Corner',
+};
 /**
  * Default Grid3 styles for common use cases
  * Colors are in 8-digit ARGB hex format (#AARRGGBBFF)

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

@@ -0,0 +1,121 @@
+/**
+ * Grid 3 Symbol Extraction Strategy
+ *
+ * For converting Grid 3 gridsets to other formats (like Asterics),
+ * we need to handle symbol library references properly.
+ *
+ * Strategy:
+ * 1. Check if image is embedded in gridset (extract directly)
+ * 2. If symbol library reference:
+ *    a. Check if we can extract from .pix file (limited support)
+ *    b. Provide reference/URL for manual resolution
+ *    c. For Tawasol: provide alternative sources
+ */
+import { type SymbolReference } from './symbols';
+/**
+ * Image extraction result
+ */
+export interface ExtractedImage {
+    found: boolean;
+    data?: Buffer;
+    format?: 'png' | 'jpg' | 'jpeg' | 'gif' | 'svg' | 'unknown';
+    source: 'embedded' | 'symbol-library' | 'external-file' | 'not-found';
+    reference?: string;
+    error?: string;
+    metadata?: {
+        library?: string;
+        symbolPath?: string;
+        attribution?: string;
+        license?: string;
+    };
+}
+/**
+ * Symbol extraction options
+ */
+export interface SymbolExtractionOptions {
+    grid3Path?: string;
+    locale?: string;
+    preferEmbedded?: boolean;
+    includeAttribution?: boolean;
+    /** For Tawasol: try to find alternative sources */
+    tryAlternativeSources?: boolean;
+    /** Callback for when symbol needs manual extraction */
+    onMissingSymbol?: (ref: SymbolReference) => void;
+}
+/**
+ * Extract image data for a button
+ * @param gridsetBuffer - Gridset ZIP buffer
+ * @param resolvedImageEntry - Path to embedded image in gridset
+ * @param symbolReference - Symbol library reference
+ * @param options - Extraction options
+ * @returns Extracted image data
+ */
+export declare function extractButtonImage(gridsetBuffer: Buffer, resolvedImageEntry: string | undefined, symbolReference: string | undefined, options?: SymbolExtractionOptions): ExtractedImage;
+/**
+ * Extract image from symbol library
+ * @param reference - Symbol reference like "[tawasl]/food/apple.png"
+ * @param options - Extraction options
+ * @returns Extracted image or reference info
+ */
+export declare function extractSymbolLibraryImage(reference: string, options?: SymbolExtractionOptions): ExtractedImage;
+/**
+ * Convert extracted image to Asterics Grid format
+ * @param extracted - Extracted image
+ * @returns GridImage object for Asterics
+ */
+export declare function convertToAstericsImage(extracted: ExtractedImage): any;
+/**
+ * Generate a symbol extraction report
+ * Useful for identifying which symbols need manual extraction
+ */
+export interface SymbolReport {
+    total: number;
+    embedded: number;
+    symbolLibraries: number;
+    notFound: number;
+    byLibrary: Record<string, number>;
+    missingSymbols: Array<{
+        reference: string;
+        library: string;
+        path: string;
+        attribution?: string;
+        license?: string;
+    }>;
+}
+/**
+ * Analyze symbol usage for a gridset
+ * @param tree - AAC tree
+ * @returns Symbol usage report
+ */
+export declare function analyzeSymbolExtraction(tree: any): SymbolReport;
+/**
+ * Suggest extraction strategy based on report
+ */
+export declare function suggestExtractionStrategy(report: SymbolReport): string;
+/**
+ * Export symbol references to CSV for manual extraction
+ */
+export declare function exportSymbolReferencesToCsv(report: SymbolReport, outputPath: string): void;
+/**
+ * Create a manifest file for missing symbols
+ */
+export interface SymbolManifest {
+    generatedAt: string;
+    gridset: string;
+    totalSymbols: number;
+    embedded: number;
+    fromLibraries: number;
+    libraries: Record<string, {
+        count: number;
+        attribution?: string;
+        license?: string;
+        url?: string;
+    }>;
+    symbols: Array<{
+        pageId: string;
+        buttonId: string;
+        reference: string;
+        label?: string;
+    }>;
+}
+export declare function createSymbolManifest(tree: any, gridsetName: string): SymbolManifest;