@willwade/aac-processors 0.2.11 → 0.2.13

package/dist/processors/dotProcessor.d.ts

@@ -2,6 +2,11 @@ import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString
 import { AACTree } from '../core/treeStructure';
 import { ProcessorInput } from '../utils/io';
 declare class DotProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "none";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "allowed";
+    };
     constructor(options?: ProcessorOptions);
     private parseDotFile;
     extractTexts(filePathOrBuffer: ProcessorInput): Promise<string[]>;

package/dist/processors/dotProcessor.js

@@ -8,6 +8,11 @@ const io_1 = require("../utils/io");
 class DotProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
     }
     parseDotFile(content) {
         const nodes = new Map();

package/dist/processors/excelProcessor.d.ts

@@ -7,6 +7,11 @@ import { AACTree } from '../core/treeStructure';
  * Supports visual styling, navigation links, and vocabulary analysis workflows
  */
 export declare class ExcelProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "none";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "allowed";
+    };
     private static readonly NAVIGATION_BUTTONS;
     /**
      * Extract all text content from an Excel file

package/dist/processors/excelProcessor.js

@@ -33,6 +33,14 @@ const treeStructure_1 = require("../core/treeStructure");
  * Supports visual styling, navigation links, and vocabulary analysis workflows
  */
 class ExcelProcessor extends baseProcessor_1.BaseProcessor {
+    constructor() {
+        super(...arguments);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
+    }
     /**
      * Extract all text content from an Excel file
      * @param filePathOrBuffer - Path to Excel file or Buffer containing Excel data

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

@@ -0,0 +1,39 @@
+/**
+ * Gridset Save Mutations Module
+ *
+ * Handles saving AACTree mutations back to Gridset files.
+ * This module extracts the save logic from gridsetProcessor for better modularity.
+ */
+import { AACTree, AACPage } from '../../core/treeStructure';
+import type { AACButton } from '../../types/aac';
+export declare class GridsetSaveHandler {
+    private AdmZip;
+    private XMLParser;
+    private XMLBuilder;
+    constructor();
+    /**
+     * Show deprecation warning for legacy save path
+     */
+    static warnLegacySave(): void;
+    /**
+     * Save using mutation-based logic
+     * Fixes bugs A, B, C by processing explicit mutations
+     */
+    static saveWithMutations(tree: AACTree, originalZip: any, outputZip: any, parser: any, gridBuilder: any, createBasicGridXml: (page: AACPage) => string): void;
+    /**
+     * Apply button changes to a cell
+     */
+    static applyButtonToCell(cell: any, button: AACButton, patch?: Partial<AACButton>): void;
+    /**
+     * Add an item to the WordList with de-duplication (Bug A fix)
+     */
+    static addWordListItemToGrid(grid: any, item: {
+        text: string;
+        image?: string;
+        partOfSpeech?: string;
+    }): void;
+    /**
+     * Remove items from the WordList
+     */
+    static removeWordListItemFromGrid(grid: any, match: string | ((item: any) => boolean)): void;
+}

package/dist/processors/gridset/saveMutations.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Gridset Save Mutations Module
+ *
+ * Handles saving AACTree mutations back to Gridset files.
+ * This module extracts the save logic from gridsetProcessor for better modularity.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GridsetSaveHandler = void 0;
+const xmlFormatter_1 = require("./xmlFormatter");
+class GridsetSaveHandler {
+    constructor() {
+        // Dynamic imports for browser compatibility
+    }
+    /**
+     * Show deprecation warning for legacy save path
+     */
+    static warnLegacySave() {
+        const key = 'gridset_legacy_save_warned';
+        if (!global[key]) {
+            console.warn('saveModifiedTree: detected button changes without recorded mutations. ' +
+                'This will continue to work in 0.x but is deprecated. ' +
+                'Use page.addButton / page.addWordListItem to make changes explicit.');
+            global[key] = true;
+        }
+    }
+    /**
+     * Save using mutation-based logic
+     * Fixes bugs A, B, C by processing explicit mutations
+     */
+    static saveWithMutations(tree, originalZip, outputZip, parser, gridBuilder, createBasicGridXml) {
+        for (const page of Object.values(tree.pages)) {
+            // Skip pages with no mutations
+            if (page.pendingMutations.length === 0) {
+                continue;
+            }
+            const gridPath = `Grids/${page.name}/grid.xml`;
+            // Load or create grid.xml
+            const originalEntry = originalZip.getEntry(gridPath);
+            let originalGrid;
+            if (originalEntry) {
+                const originalContent = originalEntry.getData().toString('utf-8');
+                originalGrid = parser.parse(originalContent);
+                if (!originalGrid.Grid) {
+                    originalGrid = null;
+                }
+            }
+            if (!originalGrid || !originalGrid.Grid) {
+                const basicGrid = createBasicGridXml(page);
+                const buffer = Buffer.from(basicGrid, 'utf8');
+                outputZip.addFile(gridPath, buffer);
+                continue;
+            }
+            // Index original cells by position
+            const cellsByPosition = new Map();
+            const cellArray = Array.isArray(originalGrid.Grid.Cells?.Cell)
+                ? originalGrid.Grid.Cells.Cell
+                : originalGrid.Grid.Cells?.Cell
+                    ? [originalGrid.Grid.Cells.Cell]
+                    : [];
+            for (const cell of cellArray) {
+                const x = cell['@_X'] !== undefined ? parseInt(String(cell['@_X']), 10) : undefined;
+                const y = parseInt(String(cell['@_Y'] || cell['@_Row'] || '0'), 10);
+                if (x !== undefined) {
+                    cellsByPosition.set(`${x},${y}`, cell);
+                }
+            }
+            // Process mutations in order
+            for (const mutation of page.pendingMutations) {
+                switch (mutation.type) {
+                    case 'addButton': {
+                        const button = mutation.button;
+                        const x = button.x ?? 0;
+                        const y = button.y ?? 0;
+                        const cell = cellsByPosition.get(`${x},${y}`);
+                        if (cell && cell.Content) {
+                            GridsetSaveHandler.applyButtonToCell(cell, button);
+                        }
+                        else {
+                            // Bug C fix: warn instead of silently dropping
+                            console.warn(`[Gridset] Cannot add button at (${x},${y}) - cell does not exist. ` +
+                                `Use addWordListItem for dynamic content.`);
+                        }
+                        break;
+                    }
+                    case 'removeButton': {
+                        const button = page.buttons.find((b) => b.id === mutation.buttonId);
+                        if (button) {
+                            const x = button.x ?? 0;
+                            const y = button.y ?? 0;
+                            const cell = cellsByPosition.get(`${x},${y}`);
+                            if (cell && cell.Content) {
+                                cell.Content.Visibility = 'Hidden';
+                            }
+                        }
+                        break;
+                    }
+                    case 'updateButton': {
+                        const button = page.buttons.find((b) => b.id === mutation.buttonId);
+                        if (button) {
+                            const x = button.x ?? 0;
+                            const y = button.y ?? 0;
+                            const cell = cellsByPosition.get(`${x},${y}`);
+                            if (cell && cell.Content) {
+                                GridsetSaveHandler.applyButtonToCell(cell, button, mutation.patch);
+                            }
+                        }
+                        break;
+                    }
+                    case 'addWordListItem': {
+                        GridsetSaveHandler.addWordListItemToGrid(originalGrid.Grid, mutation.item);
+                        break;
+                    }
+                    case 'removeWordListItem': {
+                        GridsetSaveHandler.removeWordListItemFromGrid(originalGrid.Grid, mutation.match);
+                        break;
+                    }
+                    case 'clearWordList': {
+                        if (originalGrid.Grid.WordList && originalGrid.Grid.WordList.Items) {
+                            originalGrid.Grid.WordList.Items.WordListItem = [];
+                        }
+                        break;
+                    }
+                }
+            }
+            // Build and write the updated grid XML
+            let builtXml = gridBuilder.build(originalGrid);
+            builtXml = (0, xmlFormatter_1.formatGrid3XmlComplete)(builtXml);
+            outputZip.addFile(gridPath, Buffer.from(builtXml, 'utf8'));
+        }
+    }
+    /**
+     * Apply button changes to a cell
+     */
+    static applyButtonToCell(cell, button, patch) {
+        const updates = patch ? { ...button, ...patch } : button;
+        const isPlaceholderLabel = !updates.label ||
+            updates.label.startsWith('Cell_') ||
+            updates.label.startsWith('AutoContent_') ||
+            updates.label.startsWith('Prediction ');
+        if (cell.Content.CaptionAndImage || cell.Content.captionAndImage) {
+            const captionAndImage = cell.Content.CaptionAndImage || cell.Content.captionAndImage;
+            if (!isPlaceholderLabel && updates.label) {
+                captionAndImage.Caption = updates.label;
+                if (captionAndImage['@_xsi:nil'] || captionAndImage['xsi:nil']) {
+                    delete captionAndImage['@_xsi:nil'];
+                    delete captionAndImage['xsi:nil'];
+                }
+            }
+            if (updates.image) {
+                captionAndImage.Image = updates.image;
+            }
+        }
+        const isPlaceholderMessage = !updates.message ||
+            updates.message.startsWith('Cell_') ||
+            updates.message.startsWith('AutoContent_') ||
+            updates.message.startsWith('Prediction ');
+        if (!isPlaceholderMessage &&
+            updates.message &&
+            updates.message !== updates.label &&
+            !cell.Content.Commands) {
+            cell.Content['#text'] = updates.message;
+        }
+    }
+    /**
+     * Add an item to the WordList with de-duplication (Bug A fix)
+     */
+    static addWordListItemToGrid(grid, item) {
+        if (!grid.WordList) {
+            grid.WordList = {};
+        }
+        if (!grid.WordList.Items) {
+            grid.WordList.Items = {};
+        }
+        const existingItems = grid.WordList.Items.WordListItem || grid.WordList.Items.wordlistitem || [];
+        const itemsArray = Array.isArray(existingItems) ? existingItems : [existingItems];
+        // De-duplicate by text
+        const existingTexts = new Set(itemsArray
+            .map((item) => {
+            if (typeof item.Text === 'string')
+                return item.Text;
+            return item.Text?.p?.s?.r || '';
+        })
+            .filter(Boolean));
+        if (!existingTexts.has(item.text)) {
+            itemsArray.push({
+                Text: { p: { s: { r: item.text } } },
+                Image: item.image || '',
+                PartOfSpeech: item.partOfSpeech || 'Unknown',
+            });
+            grid.WordList.Items.WordListItem = itemsArray;
+        }
+    }
+    /**
+     * Remove items from the WordList
+     */
+    static removeWordListItemFromGrid(grid, match) {
+        if (!grid.WordList || !grid.WordList.Items) {
+            return;
+        }
+        const existingItems = grid.WordList.Items.WordListItem || grid.WordList.Items.wordlistitem || [];
+        const itemsArray = Array.isArray(existingItems) ? existingItems : [existingItems];
+        let filteredItems;
+        if (typeof match === 'string') {
+            filteredItems = itemsArray.filter((item) => {
+                const text = item.Text?.p?.s?.r || item.Text || '';
+                return text !== match;
+            });
+        }
+        else {
+            filteredItems = itemsArray.filter(match);
+        }
+        grid.WordList.Items.WordListItem = filteredItems;
+    }
+}
+exports.GridsetSaveHandler = GridsetSaveHandler;

package/dist/processors/gridsetProcessor.d.ts

@@ -4,6 +4,11 @@ import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilit
 import { ValidationResult } from '../validation/validationTypes';
 import { ProcessorInput } from '../utils/io';
 declare class GridsetProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "native";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "restricted";
+    };
     constructor(options?: ProcessorOptions);
     private getGridsetPassword;
     private ensureAlphaChannel;

package/dist/processors/gridsetProcessor.js

@@ -32,6 +32,7 @@ const translationProcessor_1 = require("../utilities/translation/translationProc
 const password_1 = require("./gridset/password");
 const crypto_1 = require("./gridset/crypto");
 const xmlFormatter_1 = require("./gridset/xmlFormatter");
+const saveMutations_1 = require("./gridset/saveMutations");
 const gridCalculations_1 = require("./gridset/gridCalculations");
 const cellHelpers_1 = require("./gridset/cellHelpers");
 const gridsetValidator_1 = require("../validation/gridsetValidator");
@@ -46,6 +47,11 @@ const io_1 = require("../utils/io");
 class GridsetProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'native',
+            preservesAssetsOnSave: true,
+            newCellCreation: 'restricted',
+        };
     }
     // Determine password to use when opening encrypted gridset archives (.gridsetx)
     getGridsetPassword(source) {
@@ -2250,6 +2256,35 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
         const AdmZip = (await Promise.resolve().then(() => __importStar(require('adm-zip')))).default;
         const originalZip = new AdmZip(originalPath);
         const outputZip = new AdmZip();
+        // Check if any page has pending mutations
+        const hasPendingMutations = Object.values(tree.pages).some((page) => page.pendingMutations.length > 0);
+        if (hasPendingMutations) {
+            // NEW: Use mutation-based save path
+            const parser = new fast_xml_parser_1.XMLParser({
+                ignoreAttributes: false,
+                attributeNamePrefix: '@_',
+            });
+            const gridBuilder = new fast_xml_parser_1.XMLBuilder({
+                ignoreAttributes: false,
+                format: true,
+                indentBy: '  ',
+                suppressEmptyNode: true,
+                suppressBooleanAttributes: false,
+            });
+            saveMutations_1.GridsetSaveHandler.saveWithMutations(tree, originalZip, outputZip, parser, gridBuilder, (page) => this.createBasicGridXml(page));
+            // Copy remaining files
+            for (const entry of originalZip.getEntries()) {
+                if (entry.isDirectory)
+                    continue;
+                if (!outputZip.getEntry(entry.entryName)) {
+                    outputZip.addFile(entry.entryName, entry.getData());
+                }
+            }
+            const outputBuffer = outputZip.toBuffer();
+            await writeBinaryToPath(outputPath, outputBuffer);
+            return;
+        }
+        // LEGACY: Original position-based logic continues below...
         // Create a map of pages by name for easy lookup
         const pagesByName = new Map();
         for (const page of Object.values(tree.pages)) {

package/dist/processors/obfProcessor.d.ts

@@ -4,6 +4,11 @@ import { ValidationResult } from '../validation/validationTypes';
 import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 import { ProcessorInput } from '../utils/io';
 declare class ObfProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "none";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "allowed";
+    };
     private zipFile?;
     private imageCache;
     constructor(options?: ProcessorOptions);
@@ -21,6 +26,15 @@ declare class ObfProcessor extends BaseProcessor {
     extractTexts(filePathOrBuffer: ProcessorInput): Promise<string[]>;
     loadIntoTree(filePathOrBuffer: ProcessorInput): Promise<AACTree>;
     private buildGridMetadata;
+    /**
+     * Apply mutations to a buttons array for OBF export
+     * Returns a modified copy of the buttons array with mutations applied
+     *
+     * Note: addButton mutations are NOT applied because the button is already
+     * in the buttons array (added by page.addButton()). We only apply
+     * removeButton and updateButton mutations.
+     */
+    private applyMutationsToButtons;
     private createObfBoardFromPage;
     processTexts(filePathOrBuffer: ProcessorInput, translations: Map<string, string>, outputPath: string): Promise<Uint8Array>;
     saveFromTree(tree: AACTree, outputPath: string, embedData?: boolean): Promise<void>;

package/dist/processors/obfProcessor.js

@@ -44,6 +44,11 @@ function mapObfVisibility(hidden) {
 class ObfProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: true,
+            newCellCreation: 'allowed',
+        };
         this.imageCache = new Map(); // Cache for data URLs
     }
     /**
@@ -557,6 +562,46 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
         }
         return { rows: totalRows, columns: totalColumns, order, buttonPositions };
     }
+    /**
+     * Apply mutations to a buttons array for OBF export
+     * Returns a modified copy of the buttons array with mutations applied
+     *
+     * Note: addButton mutations are NOT applied because the button is already
+     * in the buttons array (added by page.addButton()). We only apply
+     * removeButton and updateButton mutations.
+     */
+    applyMutationsToButtons(buttons, mutations) {
+        let modifiedButtons = [...buttons];
+        for (const mutation of mutations) {
+            switch (mutation.type) {
+                case 'addButton':
+                    // Skip - button is already in the array from page.addButton()
+                    break;
+                case 'removeButton': {
+                    modifiedButtons = modifiedButtons.filter((b) => b.id !== mutation.buttonId);
+                    break;
+                }
+                case 'updateButton': {
+                    modifiedButtons = modifiedButtons.map((b) => {
+                        if (b.id === mutation.buttonId) {
+                            // Create a new AACButton instance with the patched properties
+                            const patched = Object.create(Object.getPrototypeOf(b));
+                            Object.assign(patched, b, mutation.patch);
+                            return patched;
+                        }
+                        return b;
+                    });
+                    break;
+                }
+                case 'addWordListItem':
+                case 'removeWordListItem':
+                case 'clearWordList':
+                    // OBF doesn't have WordList - skip
+                    break;
+            }
+        }
+        return modifiedButtons;
+    }
     createObfBoardFromPage(page, fallbackName, metadata, embedData = false) {
         const { rows, columns, order, buttonPositions } = this.buildGridMetadata(page);
         const boardName = metadata?.name && page.id === metadata?.defaultHomePageId
@@ -569,6 +614,10 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 return image;
             });
         }
+        // Apply mutations if present
+        const buttons = page.pendingMutations.length > 0
+            ? this.applyMutationsToButtons(page.buttons, page.pendingMutations)
+            : page.buttons;
         return {
             format: OBF_FORMAT_VERSION,
             id: page.id,
@@ -583,7 +632,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 columns,
                 order,
             },
-            buttons: page.buttons.map((button) => {
+            buttons: buttons.map((button) => {
                 const extraButtonInfo = button;
                 const imageId = button.parameters?.image_id ||
                     button.parameters?.imageId ||
@@ -728,6 +777,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
         for (const page of Object.values(tree.pages)) {
             const obfFilename = this.getPageFilename(page.id, tree.metadata);
             modifiedObfFiles.add(obfFilename);
+            // createObfBoardFromPage will automatically apply mutations if present
             const obfBoard = this.createObfBoardFromPage(page, 'Board', tree.metadata);
             const obfContent = JSON.stringify(obfBoard, null, 2);
             newObfFiles.set(obfFilename, obfContent);

package/dist/processors/obfsetProcessor.d.ts

@@ -6,6 +6,11 @@ import { AACTree } from '../core/treeStructure';
 import { BaseProcessor, ProcessorOptions } from '../core/baseProcessor';
 import { ProcessorInput } from '../utils/io';
 export declare class ObfsetProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "none";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "allowed";
+    };
     constructor(options?: ProcessorOptions);
     /**
      * Extract all text content

package/dist/processors/obfsetProcessor.js

@@ -11,6 +11,11 @@ const baseProcessor_1 = require("../core/baseProcessor");
 class ObfsetProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options = {}) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
     }
     /**
      * Extract all text content

package/dist/processors/opmlProcessor.d.ts

@@ -2,6 +2,11 @@ import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString
 import { AACTree } from '../core/treeStructure';
 import { ProcessorInput } from '../utils/io';
 declare class OpmlProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "none";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "allowed";
+    };
     constructor(options?: ProcessorOptions);
     private processOutline;
     extractTexts(filePathOrBuffer: ProcessorInput): Promise<string[]>;

package/dist/processors/opmlProcessor.js

@@ -9,6 +9,11 @@ const io_1 = require("../utils/io");
 class OpmlProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
     }
     processOutline(outline, parentId = null) {
         if (!outline || typeof outline !== 'object') {

package/dist/processors/snapProcessor.d.ts

@@ -3,6 +3,11 @@ import { AACTree } from '../core/treeStructure';
 import { ValidationResult } from '../validation/validationTypes';
 import { ProcessorInput } from '../utils/io';
 declare class SnapProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "none";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "allowed";
+    };
     private symbolResolver;
     private loadAudio;
     private pageLayoutPreference;

package/dist/processors/snapProcessor.js

@@ -40,6 +40,11 @@ function mapSnapVisibility(visible) {
 class SnapProcessor extends baseProcessor_1.BaseProcessor {
     constructor(symbolResolver = null, options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
         this.symbolResolver = null;
         this.loadAudio = false;
         this.pageLayoutPreference = 'scanning'; // Default to scanning for metrics

package/dist/processors/touchchatProcessor.d.ts

@@ -4,6 +4,11 @@ import { ValidationResult } from '../validation/validationTypes';
 import { ProcessorInput } from '../utils/io';
 import { type ButtonForTranslation, type LLMLTranslationResult } from '../utilities/translation/translationProcessor';
 declare class TouchChatProcessor extends BaseProcessor {
+    readonly capabilities: {
+        wordList: "none";
+        preservesAssetsOnSave: boolean;
+        newCellCreation: "allowed";
+    };
     private tree;
     private sourceFile;
     constructor(options?: ProcessorOptions);

package/dist/processors/touchchatProcessor.js

@@ -34,6 +34,11 @@ function mapTouchChatVisibility(visible) {
 class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
         this.tree = null;
         this.sourceFile = null;
     }

package/dist/types/aac.d.ts

@@ -206,3 +206,57 @@ export interface AACProcessor {
     extractTexts(filePath: string | Buffer): Promise<string[]>;
     loadIntoTree(filePath: string | Buffer): Promise<AACTree>;
 }
+/**
+ * Word List Item for dynamic content cells (e.g., Grid 3 WordLists)
+ */
+export interface AACWordListItem {
+    text: string;
+    image?: string;
+    partOfSpeech?: string;
+}
+/**
+ * Mutation types for page modifications
+ */
+export type AACPageMutation = {
+    type: 'addButton';
+    button: AACButton;
+} | {
+    type: 'removeButton';
+    buttonId: string;
+} | {
+    type: 'updateButton';
+    buttonId: string;
+    patch: Partial<AACButton>;
+} | {
+    type: 'addWordListItem';
+    item: AACWordListItem;
+} | {
+    type: 'removeWordListItem';
+    match: string | ((item: AACWordListItem) => boolean);
+} | {
+    type: 'clearWordList';
+};
+/**
+ * Processor capabilities declaration
+ */
+export interface ProcessorCapabilities {
+    /**
+     * WordList support level
+     * - 'native': addWordListItem writes a real WordList structure on disk
+     * - 'fallback': addWordListItem becomes addButton (still useful, just not dynamic)
+     * - 'none': addWordListItem throws CapabilityError
+     */
+    wordList: 'native' | 'fallback' | 'none';
+    /**
+     * Whether the processor has a real saveModifiedTree that keeps original images/settings
+     * If false, saveModifiedTree falls back to saveFromTree with a warning
+     */
+    preservesAssetsOnSave: boolean;
+    /**
+     * Rules for creating new cells
+     * - 'allowed': addButton at any (x,y) creates a cell on save
+     * - 'restricted': addButton routes to a WordList if (x,y) is a WordList cell, else dropped with warning
+     * - 'forbidden': addButton requires explicit (x,y) of an existing cell; otherwise CapabilityError
+     */
+    newCellCreation: 'allowed' | 'restricted' | 'forbidden';
+}

package/package.json

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