@willwade/aac-processors 0.0.3

package/dist/processors/index.d.ts

@@ -0,0 +1,14 @@
+export { ApplePanelsProcessor } from './applePanelsProcessor';
+export { DotProcessor } from './dotProcessor';
+export { ExcelProcessor } from './excelProcessor';
+export { GridsetProcessor } from './gridsetProcessor';
+export { ObfProcessor } from './obfProcessor';
+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 { resolveGrid3CellImage } from './gridset/resolver';
+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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openTouchChatImage = exports.getTouchChatAllowedImageEntries = exports.getTouchChatPageTokenImageMap = exports.openSnapImage = exports.getSnapAllowedImageEntries = exports.getSnapPageTokenImageMap = 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;
+var applePanelsProcessor_1 = require("./applePanelsProcessor");
+Object.defineProperty(exports, "ApplePanelsProcessor", { enumerable: true, get: function () { return applePanelsProcessor_1.ApplePanelsProcessor; } });
+var dotProcessor_1 = require("./dotProcessor");
+Object.defineProperty(exports, "DotProcessor", { enumerable: true, get: function () { return dotProcessor_1.DotProcessor; } });
+var excelProcessor_1 = require("./excelProcessor");
+Object.defineProperty(exports, "ExcelProcessor", { enumerable: true, get: function () { return excelProcessor_1.ExcelProcessor; } });
+var gridsetProcessor_1 = require("./gridsetProcessor");
+Object.defineProperty(exports, "GridsetProcessor", { enumerable: true, get: function () { return gridsetProcessor_1.GridsetProcessor; } });
+var obfProcessor_1 = require("./obfProcessor");
+Object.defineProperty(exports, "ObfProcessor", { enumerable: true, get: function () { return obfProcessor_1.ObfProcessor; } });
+var opmlProcessor_1 = require("./opmlProcessor");
+Object.defineProperty(exports, "OpmlProcessor", { enumerable: true, get: function () { return opmlProcessor_1.OpmlProcessor; } });
+var snapProcessor_1 = require("./snapProcessor");
+Object.defineProperty(exports, "SnapProcessor", { enumerable: true, get: function () { return snapProcessor_1.SnapProcessor; } });
+var touchchatProcessor_1 = require("./touchchatProcessor");
+Object.defineProperty(exports, "TouchChatProcessor", { enumerable: true, get: function () { return touchchatProcessor_1.TouchChatProcessor; } });
+var astericsGridProcessor_1 = require("./astericsGridProcessor");
+Object.defineProperty(exports, "AstericsGridProcessor", { enumerable: true, get: function () { return astericsGridProcessor_1.AstericsGridProcessor; } });
+// Gridset (Grid 3) helpers
+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; } });
+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; } });
+var resolver_1 = require("./gridset/resolver");
+Object.defineProperty(exports, "resolveGrid3CellImage", { enumerable: true, get: function () { return resolver_1.resolveGrid3CellImage; } });
+// Snap helpers (stubs)
+var helpers_3 = require("./snap/helpers");
+Object.defineProperty(exports, "getSnapPageTokenImageMap", { enumerable: true, get: function () { return helpers_3.getPageTokenImageMap; } });
+Object.defineProperty(exports, "getSnapAllowedImageEntries", { enumerable: true, get: function () { return helpers_3.getAllowedImageEntries; } });
+Object.defineProperty(exports, "openSnapImage", { enumerable: true, get: function () { return helpers_3.openImage; } });
+// TouchChat helpers (stubs)
+var helpers_4 = require("./touchchat/helpers");
+Object.defineProperty(exports, "getTouchChatPageTokenImageMap", { enumerable: true, get: function () { return helpers_4.getPageTokenImageMap; } });
+Object.defineProperty(exports, "getTouchChatAllowedImageEntries", { enumerable: true, get: function () { return helpers_4.getAllowedImageEntries; } });
+Object.defineProperty(exports, "openTouchChatImage", { enumerable: true, get: function () { return helpers_4.openImage; } });

package/dist/processors/obfProcessor.d.ts

@@ -0,0 +1,21 @@
+import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
+import { AACTree } from '../core/treeStructure';
+declare class ObfProcessor extends BaseProcessor {
+    constructor(options?: ProcessorOptions);
+    private processBoard;
+    extractTexts(filePathOrBuffer: string | Buffer): string[];
+    loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;
+    processTexts(filePathOrBuffer: string | Buffer, translations: Map<string, string>, outputPath: string): Buffer;
+    saveFromTree(tree: AACTree, outputPath: string): void;
+    /**
+     * Extract strings with metadata for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    extractStringsWithMetadata(filePath: string): Promise<ExtractStringsResult>;
+    /**
+     * Generate translated download for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    generateTranslatedDownload(filePath: string, translatedStrings: TranslatedString[], sourceStrings: SourceString[]): Promise<string>;
+}
+export { ObfProcessor };

package/dist/processors/obfProcessor.js

@@ -0,0 +1,278 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObfProcessor = void 0;
+const baseProcessor_1 = require("../core/baseProcessor");
+const treeStructure_1 = require("../core/treeStructure");
+// Removed unused import: FileProcessor
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const fs_1 = __importDefault(require("fs"));
+class ObfProcessor extends baseProcessor_1.BaseProcessor {
+    constructor(options) {
+        super(options);
+    }
+    processBoard(boardData, _boardPath) {
+        const buttons = (boardData.buttons || []).map((btn) => {
+            const semanticAction = btn.load_board
+                ? {
+                    category: treeStructure_1.AACSemanticCategory.NAVIGATION,
+                    intent: treeStructure_1.AACSemanticIntent.NAVIGATE_TO,
+                    targetId: btn.load_board.path,
+                    fallback: {
+                        type: 'NAVIGATE',
+                        targetPageId: btn.load_board.path,
+                    },
+                }
+                : {
+                    category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
+                    intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+                    text: String(btn?.vocalization || btn?.label || ''),
+                    fallback: {
+                        type: 'SPEAK',
+                        message: String(btn?.vocalization || btn?.label || ''),
+                    },
+                };
+            return new treeStructure_1.AACButton({
+                id: String(btn?.id || ''),
+                label: String(btn?.label || ''),
+                message: String(btn?.vocalization || btn?.label || ''),
+                style: {
+                    backgroundColor: btn.background_color,
+                    borderColor: btn.border_color,
+                },
+                semanticAction,
+                targetPageId: btn.load_board?.path,
+            });
+        });
+        const page = new treeStructure_1.AACPage({
+            id: String(boardData?.id || ''),
+            name: String(boardData?.name || ''),
+            grid: [],
+            buttons,
+            parentId: null,
+        });
+        // Process grid layout if available
+        if (boardData.grid) {
+            const rows = boardData.grid.rows;
+            const cols = boardData.grid.columns;
+            const grid = Array(rows)
+                .fill(null)
+                .map(() => Array(cols).fill(null));
+            for (const btn of boardData.buttons) {
+                if (typeof btn.box_id === 'number') {
+                    const row = Math.floor(btn.box_id / cols);
+                    const col = btn.box_id % cols;
+                    if (row < rows && col < cols) {
+                        const aacBtn = buttons.find((b) => b.id === btn.id);
+                        if (aacBtn) {
+                            grid[row][col] = aacBtn;
+                        }
+                    }
+                }
+            }
+            page.grid = grid;
+        }
+        return page;
+    }
+    extractTexts(filePathOrBuffer) {
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        const texts = [];
+        for (const pageId in tree.pages) {
+            const page = tree.pages[pageId];
+            if (page.name)
+                texts.push(page.name);
+            page.buttons.forEach((btn) => {
+                if (typeof btn.label === 'string')
+                    texts.push(btn.label);
+                if (typeof btn.message === 'string' && btn.message !== btn.label)
+                    texts.push(btn.message);
+            });
+        }
+        return texts;
+    }
+    loadIntoTree(filePathOrBuffer) {
+        // Detailed logging for debugging input
+        console.log('[OBF] loadIntoTree called with:', {
+            type: typeof filePathOrBuffer,
+            isBuffer: Buffer.isBuffer(filePathOrBuffer),
+            value: typeof filePathOrBuffer === 'string'
+                ? filePathOrBuffer
+                : '[Buffer of length ' + filePathOrBuffer.length + ']',
+        });
+        const tree = new treeStructure_1.AACTree();
+        // Helper: try to parse JSON OBF
+        function tryParseObfJson(data) {
+            try {
+                const str = typeof data === 'string' ? data : data.toString('utf8');
+                // Check for empty or whitespace-only content
+                if (!str.trim()) {
+                    return null;
+                }
+                const obj = JSON.parse(str);
+                if (obj && typeof obj === 'object' && 'id' in obj && 'buttons' in obj) {
+                    return obj;
+                }
+            }
+            catch (error) {
+                // Log parsing errors for debugging but don't throw
+                console.warn(`Failed to parse OBF JSON: ${error.message}`);
+            }
+            return null;
+        }
+        // If input is a string path and ends with .obf, treat as JSON
+        if (typeof filePathOrBuffer === 'string' && filePathOrBuffer.endsWith('.obf')) {
+            const fs = require('fs');
+            try {
+                const content = fs.readFileSync(filePathOrBuffer, 'utf8');
+                const boardData = tryParseObfJson(content);
+                if (boardData) {
+                    console.log('[OBF] Detected .obf file, parsed as JSON');
+                    const page = this.processBoard(boardData, filePathOrBuffer);
+                    tree.addPage(page);
+                    return tree;
+                }
+                else {
+                    throw new Error('Invalid OBF JSON content');
+                }
+            }
+            catch (err) {
+                console.error('[OBF] Error reading .obf file:', err);
+                throw err;
+            }
+        }
+        // If input is a buffer or string that parses as OBF JSON
+        const asJson = tryParseObfJson(filePathOrBuffer);
+        if (asJson) {
+            console.log('[OBF] Detected buffer/string as OBF JSON');
+            const page = this.processBoard(asJson, '[bufferOrString]');
+            tree.addPage(page);
+            return tree;
+        }
+        // Otherwise, try as ZIP (.obz). Detect likely zip signature first; throw if neither JSON nor ZIP
+        function isLikelyZip(input) {
+            if (typeof input === 'string')
+                return input.endsWith('.zip') || input.endsWith('.obz');
+            if (Buffer.isBuffer(input) && input.length >= 2) {
+                return input[0] === 0x50 && input[1] === 0x4b; // 'PK'
+            }
+            return false;
+        }
+        if (!isLikelyZip(filePathOrBuffer)) {
+            throw new Error('Invalid OBF content: not JSON and not ZIP');
+        }
+        let zip;
+        try {
+            zip = new adm_zip_1.default(filePathOrBuffer);
+        }
+        catch (err) {
+            console.error('[OBF] Error instantiating AdmZip with input:', err);
+            throw err;
+        }
+        console.log('[OBF] Detected zip archive, extracting .obf files');
+        zip.getEntries().forEach((entry) => {
+            if (entry.entryName.endsWith('.obf')) {
+                const content = entry.getData().toString('utf8');
+                const boardData = tryParseObfJson(content);
+                if (boardData) {
+                    const page = this.processBoard(boardData, entry.entryName);
+                    tree.addPage(page);
+                }
+                else {
+                    console.warn('[OBF] Skipped entry (not valid OBF JSON):', entry.entryName);
+                }
+            }
+        });
+        return tree;
+    }
+    processTexts(filePathOrBuffer, translations, outputPath) {
+        // Load the tree, apply translations, and save to new file
+        const tree = this.loadIntoTree(filePathOrBuffer);
+        // Apply translations to all text content
+        Object.values(tree.pages).forEach((page) => {
+            // Translate page names
+            if (page.name && translations.has(page.name)) {
+                page.name = translations.get(page.name);
+            }
+            // Translate button labels and messages
+            page.buttons.forEach((button) => {
+                if (button.label && translations.has(button.label)) {
+                    button.label = translations.get(button.label);
+                }
+                if (button.message && translations.has(button.message)) {
+                    button.message = translations.get(button.message);
+                }
+            });
+        });
+        // Save the translated tree and return its content
+        this.saveFromTree(tree, outputPath);
+        return fs_1.default.readFileSync(outputPath);
+    }
+    saveFromTree(tree, outputPath) {
+        if (outputPath.endsWith('.obf')) {
+            // Save as single OBF JSON file
+            const rootPage = tree.rootId ? tree.getPage(tree.rootId) : Object.values(tree.pages)[0];
+            if (!rootPage) {
+                throw new Error('No pages to save');
+            }
+            const obfBoard = {
+                id: rootPage.id,
+                name: rootPage.name || 'Exported Board',
+                buttons: rootPage.buttons.map((button) => ({
+                    id: button.id,
+                    label: button.label,
+                    vocalization: button.message || button.label,
+                    load_board: button.semanticAction?.intent === treeStructure_1.AACSemanticIntent.NAVIGATE_TO && button.targetPageId
+                        ? {
+                            path: button.targetPageId,
+                        }
+                        : undefined,
+                    background_color: button.style?.backgroundColor,
+                    border_color: button.style?.borderColor,
+                })),
+            };
+            fs_1.default.writeFileSync(outputPath, JSON.stringify(obfBoard, null, 2));
+        }
+        else {
+            // Save as OBZ (zip with multiple OBF files)
+            const zip = new adm_zip_1.default();
+            Object.values(tree.pages).forEach((page) => {
+                const obfBoard = {
+                    id: page.id,
+                    name: page.name || 'Board',
+                    buttons: page.buttons.map((button) => ({
+                        id: button.id,
+                        label: button.label,
+                        vocalization: button.message || button.label,
+                        load_board: button.semanticAction?.intent === treeStructure_1.AACSemanticIntent.NAVIGATE_TO && button.targetPageId
+                            ? {
+                                path: button.targetPageId,
+                            }
+                            : undefined,
+                        background_color: button.style?.backgroundColor,
+                        border_color: button.style?.borderColor,
+                    })),
+                };
+                const obfContent = JSON.stringify(obfBoard, null, 2);
+                zip.addFile(`${page.id}.obf`, Buffer.from(obfContent, 'utf8'));
+            });
+            zip.writeZip(outputPath);
+        }
+    }
+    /**
+     * Extract strings with metadata for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    async extractStringsWithMetadata(filePath) {
+        return this.extractStringsWithMetadataGeneric(filePath);
+    }
+    /**
+     * Generate translated download for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    async generateTranslatedDownload(filePath, translatedStrings, sourceStrings) {
+        return this.generateTranslatedDownloadGeneric(filePath, translatedStrings, sourceStrings);
+    }
+}
+exports.ObfProcessor = ObfProcessor;

package/dist/processors/opmlProcessor.d.ts

@@ -0,0 +1,21 @@
+import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
+import { AACTree } from '../core/treeStructure';
+declare class OpmlProcessor extends BaseProcessor {
+    constructor(options?: ProcessorOptions);
+    private processOutline;
+    extractTexts(filePathOrBuffer: string | Buffer): string[];
+    loadIntoTree(filePathOrBuffer: string | Buffer): AACTree;
+    processTexts(filePathOrBuffer: string | Buffer, translations: Map<string, string>, outputPath: string): Buffer;
+    saveFromTree(tree: AACTree, outputPath: string): void;
+    /**
+     * Extract strings with metadata for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    extractStringsWithMetadata(filePath: string): Promise<ExtractStringsResult>;
+    /**
+     * Generate translated download for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    generateTranslatedDownload(filePath: string, translatedStrings: TranslatedString[], sourceStrings: SourceString[]): Promise<string>;
+}
+export { OpmlProcessor };

package/dist/processors/opmlProcessor.js

@@ -0,0 +1,235 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpmlProcessor = void 0;
+const baseProcessor_1 = require("../core/baseProcessor");
+const treeStructure_1 = require("../core/treeStructure");
+// Removed unused import: FileProcessor
+const fast_xml_parser_1 = require("fast-xml-parser");
+const fs_1 = __importDefault(require("fs"));
+class OpmlProcessor extends baseProcessor_1.BaseProcessor {
+    constructor(options) {
+        super(options);
+    }
+    processOutline(outline, parentId = null) {
+        if (!outline || typeof outline !== 'object') {
+            return { page: null, childPages: [] };
+        }
+        const text = outline['@_text'] ||
+            (outline._attributes && outline._attributes.text) ||
+            outline.text;
+        if (!text || typeof text !== 'string') {
+            // Skip invalid outlines
+            return { page: null, childPages: [] };
+        }
+        const page = new treeStructure_1.AACPage({
+            id: text.replace(/[^a-zA-Z0-9]/g, '_'),
+            name: text,
+            grid: [],
+            buttons: [],
+            parentId,
+        });
+        const childPages = [];
+        if (outline.outline) {
+            const children = Array.isArray(outline.outline) ? outline.outline : [outline.outline];
+            children.forEach((child) => {
+                const childText = child['@_text'] || (child._attributes && child._attributes.text) || child.text;
+                if (childText && typeof childText === 'string') {
+                    const button = new treeStructure_1.AACButton({
+                        id: `nav_${page.id}_${childText}`,
+                        label: childText,
+                        message: '',
+                        targetPageId: childText.replace(/[^a-zA-Z0-9]/g, '_'),
+                    });
+                    page.addButton(button);
+                    const { page: childPage, childPages: grandChildren } = this.processOutline(child, page.id);
+                    if (childPage && childPage.id)
+                        childPages.push(childPage, ...grandChildren);
+                }
+            });
+        }
+        if (!page || !page.id)
+            return { page: null, childPages: [] };
+        return { page, childPages };
+    }
+    extractTexts(filePathOrBuffer) {
+        const content = typeof filePathOrBuffer === 'string'
+            ? fs_1.default.readFileSync(filePathOrBuffer, 'utf8')
+            : filePathOrBuffer.toString('utf8');
+        const parser = new fast_xml_parser_1.XMLParser({ ignoreAttributes: false });
+        const data = parser.parse(content);
+        const texts = [];
+        function processNode(node) {
+            // Handle different attribute formats
+            let textValue;
+            if (node && node._attributes && typeof node._attributes.text === 'string') {
+                textValue = node._attributes.text;
+            }
+            else if (node && typeof node['@_text'] === 'string') {
+                textValue = node['@_text'];
+            }
+            else if (node && typeof node.text === 'string') {
+                textValue = node.text;
+            }
+            if (textValue) {
+                texts.push(textValue);
+            }
+            if (node && node.outline) {
+                const children = Array.isArray(node.outline) ? node.outline : [node.outline];
+                children.forEach(processNode);
+            }
+        }
+        const outlines = Array.isArray(data.opml.body.outline)
+            ? data.opml.body.outline
+            : [data.opml.body.outline];
+        outlines.forEach(processNode);
+        return texts;
+    }
+    loadIntoTree(filePathOrBuffer) {
+        const content = typeof filePathOrBuffer === 'string'
+            ? fs_1.default.readFileSync(filePathOrBuffer, 'utf8')
+            : filePathOrBuffer.toString('utf8');
+        if (!content || !content.trim()) {
+            throw new Error('Empty OPML content');
+        }
+        // Validate XML before parsing, fast-xml-parser is permissive by default
+        const validationResult = fast_xml_parser_1.XMLValidator.validate(content);
+        if (validationResult !== true) {
+            const reason = validationResult?.err?.msg || JSON.stringify(validationResult);
+            throw new Error(`Invalid OPML XML: ${reason}`);
+        }
+        const parser = new fast_xml_parser_1.XMLParser({ ignoreAttributes: false });
+        let data;
+        try {
+            data = parser.parse(content);
+        }
+        catch (e) {
+            throw new Error(`Invalid OPML XML: ${e?.message || String(e)}`);
+        }
+        const tree = new treeStructure_1.AACTree();
+        // Handle case where body.outline might not exist or be in different formats
+        const bodyOutline = data.opml?.body?.outline;
+        if (!bodyOutline) {
+            return tree; // Return empty tree if no outline data
+        }
+        const outlines = Array.isArray(bodyOutline) ? bodyOutline : [bodyOutline];
+        let firstRootId = null;
+        outlines.forEach((outline) => {
+            const { page, childPages } = this.processOutline(outline);
+            if (page && page.id) {
+                tree.addPage(page);
+                if (!firstRootId)
+                    firstRootId = page.id;
+            }
+            childPages.forEach((childPage) => {
+                if (childPage && childPage.id)
+                    tree.addPage(childPage);
+            });
+        });
+        // Set rootId to first root page, or fallback to first page if any exist
+        if (firstRootId) {
+            tree.rootId = firstRootId;
+        }
+        else if (Object.keys(tree.pages).length > 0) {
+            tree.rootId = Object.keys(tree.pages)[0];
+        }
+        return tree;
+    }
+    processTexts(filePathOrBuffer, translations, outputPath) {
+        const content = typeof filePathOrBuffer === 'string'
+            ? fs_1.default.readFileSync(filePathOrBuffer, 'utf8')
+            : filePathOrBuffer.toString('utf8');
+        let translatedContent = content;
+        // Apply translations to text attributes in OPML outline elements
+        translations.forEach((translation, originalText) => {
+            if (typeof originalText === 'string' && typeof translation === 'string') {
+                // Replace text attributes in outline elements
+                const textAttrRegex = new RegExp(`text="${originalText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"`, 'g');
+                translatedContent = translatedContent.replace(textAttrRegex, `text="${translation}"`);
+            }
+        });
+        const resultBuffer = Buffer.from(translatedContent, 'utf8');
+        // Save to output path
+        fs_1.default.writeFileSync(outputPath, resultBuffer);
+        return resultBuffer;
+    }
+    saveFromTree(tree, outputPath) {
+        // Helper to recursively build outline nodes with cycle detection
+        function buildOutline(page, visited = new Set()) {
+            // Prevent infinite recursion by tracking visited pages
+            if (visited.has(page.id)) {
+                return {
+                    '@_text': `${page.name || page.id} (circular reference)`,
+                };
+            }
+            visited.add(page.id);
+            const outline = {
+                '@_text': page.name || page.id,
+            };
+            // Find child pages (by NAVIGATE buttons)
+            const childOutlines = page.buttons
+                .filter((b) => b.semanticAction?.intent === treeStructure_1.AACSemanticIntent.NAVIGATE_TO &&
+                !!b.targetPageId &&
+                !!tree.pages[b.targetPageId])
+                .map((b) => buildOutline(tree.pages[b.targetPageId], new Set(visited))); // Pass copy of visited set
+            if (childOutlines.length)
+                outline.outline = childOutlines;
+            return outline;
+        }
+        // Find root pages (no parentId or not navigated to by any button)
+        const navigatedIds = new Set();
+        Object.values(tree.pages).forEach((page) => {
+            page.buttons.forEach((b) => {
+                if (b.semanticAction?.intent === treeStructure_1.AACSemanticIntent.NAVIGATE_TO && b.targetPageId)
+                    navigatedIds.add(b.targetPageId);
+            });
+        });
+        let rootPages = Object.values(tree.pages).filter((page) => !navigatedIds.has(page.id));
+        // If no rootPages, fall back to tree.rootId
+        const treeRootId = tree.rootId;
+        if ((!rootPages || rootPages.length === 0) && treeRootId && tree.pages[treeRootId]) {
+            rootPages = [tree.pages[treeRootId]];
+        }
+        else if (treeRootId) {
+            rootPages = rootPages.sort((a, b) => a.id === treeRootId ? -1 : b.id === treeRootId ? 1 : 0);
+        }
+        // Build outlines
+        const outlines = rootPages.map((page) => buildOutline(page));
+        // Compose OPML document
+        const opmlObj = {
+            opml: {
+                '@_version': '2.0',
+                head: { title: 'Exported OPML' },
+                body: { outline: outlines },
+            },
+        };
+        // Convert to XML
+        const { XMLBuilder } = require('fast-xml-parser');
+        const builder = new XMLBuilder({
+            ignoreAttributes: false,
+            format: true,
+            indentBy: '    ',
+            suppressEmptyNode: false,
+            attributeNamePrefix: '@_',
+        });
+        const xml = '<?xml version="1.0" encoding="UTF-8"?>\n' + builder.build(opmlObj);
+        fs_1.default.writeFileSync(outputPath, xml, 'utf8');
+    }
+    /**
+     * Extract strings with metadata for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    extractStringsWithMetadata(filePath) {
+        return this.extractStringsWithMetadataGeneric(filePath);
+    }
+    /**
+     * Generate translated download for aac-tools-platform compatibility
+     * Uses the generic implementation from BaseProcessor
+     */
+    generateTranslatedDownload(filePath, translatedStrings, sourceStrings) {
+        return this.generateTranslatedDownloadGeneric(filePath, translatedStrings, sourceStrings);
+    }
+}
+exports.OpmlProcessor = OpmlProcessor;

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

@@ -0,0 +1,4 @@
+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(_dbOrFile: string | Buffer, _entryPath: string): Buffer | null;

package/dist/processors/snap/helpers.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPageTokenImageMap = getPageTokenImageMap;
+exports.getAllowedImageEntries = getAllowedImageEntries;
+exports.openImage = openImage;
+// Minimal Snap helpers (stubs) to align with processors/<engine>/helpers pattern
+// NOTE: Snap buttons currently do not populate resolvedImageEntry; these helpers
+// therefore return empty collections until image resolution is implemented.
+function getPageTokenImageMap(tree, pageId) {
+    const map = new Map();
+    const page = tree.getPage(pageId);
+    if (!page)
+        return map;
+    for (const btn of page.buttons) {
+        if (btn.resolvedImageEntry)
+            map.set(btn.id, String(btn.resolvedImageEntry));
+    }
+    return map;
+}
+function getAllowedImageEntries(_tree) {
+    // No known image entry paths for Snap yet
+    return new Set();
+}
+function openImage(_dbOrFile, _entryPath) {
+    // Not implemented for Snap yet
+    return null;
+}