@willwade/aac-processors 0.2.12 → 0.2.14

package/dist/browser/core/treeStructure.js

@@ -168,6 +168,8 @@ export class AACButton {
 }
 export class AACPage {
     constructor({ id, name = '', grid = [], buttons = [], parentId = null, style, locale, descriptionHtml, images, sounds, semantic_ids, clone_ids, scanningConfig, scanBlocksConfig, scanType, }) {
+        // Mutation tracking
+        this._pendingMutations = [];
         this.id = id;
         this.name = name;
         if (Array.isArray(grid)) {
@@ -196,6 +198,64 @@ export class AACPage {
     }
     addButton(button) {
         this.buttons.push(button);
+        // Record the mutation
+        this._pendingMutations.push({ type: 'addButton', button });
+    }
+    /**
+     * Internal load-path button push: adds a button to the page WITHOUT recording a mutation.
+     * Used by processors during loadIntoTree so the loaded baseline isn't treated as user changes.
+     * Not part of the public API — consumers should always use addButton.
+     */
+    _loadButton(button) {
+        this.buttons.push(button);
+    }
+    /**
+     * Discard all recorded mutations on this page.
+     * Useful as an escape hatch after loadIntoTree if the consumer wants a clean baseline.
+     */
+    clearMutations() {
+        this._pendingMutations = [];
+    }
+    /**
+     * Get the list of pending mutations for this page (read-only)
+     */
+    get pendingMutations() {
+        return Object.freeze([...this._pendingMutations]);
+    }
+    /**
+     * Remove a button by ID
+     * @param buttonId - The ID of the button to remove
+     */
+    removeButton(buttonId) {
+        this._pendingMutations.push({ type: 'removeButton', buttonId });
+    }
+    /**
+     * Update a button by merging a patch
+     * @param buttonId - The ID of the button to update
+     * @param patch - Partial button object with fields to update
+     */
+    updateButton(buttonId, patch) {
+        this._pendingMutations.push({ type: 'updateButton', buttonId, patch });
+    }
+    /**
+     * Add an item to the page's WordList (for formats with dynamic content cells)
+     * @param item - WordList item to add
+     */
+    addWordListItem(item) {
+        this._pendingMutations.push({ type: 'addWordListItem', item });
+    }
+    /**
+     * Remove items from the page's WordList
+     * @param textOrPredicate - Text to match or predicate function to filter items
+     */
+    removeWordListItem(textOrPredicate) {
+        this._pendingMutations.push({ type: 'removeWordListItem', match: textOrPredicate });
+    }
+    /**
+     * Clear all items from the page's WordList
+     */
+    clearWordList() {
+        this._pendingMutations.push({ type: 'clearWordList' });
     }
 }
 export class AACTree {

package/dist/browser/processors/applePanelsProcessor.js

@@ -45,6 +45,11 @@ function normalizeActionParameters(input) {
 class ApplePanelsProcessor extends BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
     }
     // Helper function to parse Apple Panels Rect format "{{x, y}, {width, height}}"
     parseRect(rectString) {
@@ -214,7 +219,8 @@ class ApplePanelsProcessor extends BaseProcessor {
                             fontWeight: btn.DisplayImageWeight === 'bold' ? 'bold' : 'normal',
                         },
                     });
-                    page.addButton(button);
+                    // Load path: do not record as a user mutation
+                    page._loadButton(button);
                     if (btn.Rect) {
                         const rect = this.parseRect(btn.Rect);
                         if (rect) {

package/dist/browser/processors/astericsGridProcessor.js

@@ -544,6 +544,11 @@ function mapAstericsVisibility(hidden) {
 class AstericsGridProcessor extends BaseProcessor {
     constructor(options = {}) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
         this.loadAudio = false;
         this.loadAudio = options.loadAudio || false;
     }
@@ -709,7 +714,8 @@ class AstericsGridProcessor extends BaseProcessor {
                 }
                 grid.gridElements.forEach((element) => {
                     const button = this.createButtonFromElement(element, colorConfig, activeColorSchemeDefinition);
-                    page.addButton(button);
+                    // Load path: do not record as a user mutation
+                    page._loadButton(button);
                     const buttonX = element.x || 0;
                     const buttonY = element.y || 0;
                     const buttonWidth = element.width || 1;

package/dist/browser/processors/dotProcessor.js

@@ -5,6 +5,11 @@ import { getBasename, encodeText } from '../utils/io';
 class DotProcessor extends BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
     }
     parseDotFile(content) {
         const nodes = new Map();
@@ -112,7 +117,8 @@ class DotProcessor extends BaseProcessor {
                 });
                 tree.addPage(page);
                 // Add a self button so single-node graphs yield one button
-                page.addButton(new AACButton({
+                // Load path: do not record as a user mutation
+                page._loadButton(new AACButton({
                     id: `${node.id}_self`,
                     label: node.label,
                     message: node.label,
@@ -133,7 +139,8 @@ class DotProcessor extends BaseProcessor {
                         message: '',
                         targetPageId: edge.to,
                     });
-                    fromPage.addButton(button);
+                    // Load path: do not record as a user mutation
+                    fromPage._loadButton(button);
                 }
             }
             return tree;

package/dist/browser/processors/gridset/saveMutations.js

@@ -0,0 +1,212 @@
+/**
+ * Gridset Save Mutations Module
+ *
+ * Handles saving AACTree mutations back to Gridset files.
+ * This module extracts the save logic from gridsetProcessor for better modularity.
+ */
+import { formatGrid3XmlComplete } from './xmlFormatter';
+export 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 = 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;
+    }
+}

package/dist/browser/processors/gridsetProcessor.js

@@ -6,6 +6,7 @@ import { extractAllButtonsForTranslation, validateTranslationResults, } from '..
 import { getZipEntriesFromAdapter, resolveGridsetPassword, } from './gridset/password';
 import { decryptGridsetEntry } from './gridset/crypto';
 import { formatGrid3XmlComplete } from './gridset/xmlFormatter';
+import { GridsetSaveHandler } from './gridset/saveMutations';
 import { calculateColumnDefinitions as calcColumnDefs, calculateRowDefinitions as calcRowDefs, } from './gridset/gridCalculations';
 import { findButtonPosition as findButtonPos } from './gridset/cellHelpers';
 import { GridsetValidator } from '../validation/gridsetValidator';
@@ -20,6 +21,11 @@ import { decodeText } from '../utils/io';
 class GridsetProcessor extends 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) {
@@ -1565,8 +1571,8 @@ class GridsetProcessor extends BaseProcessor {
                                 ...(imageData ? { imageData, image_id: resolvedImageEntry } : {}),
                             },
                         });
-                        // Add button to page
-                        page.addButton(button);
+                        // Add button to page (load path: do not record as a user mutation)
+                        page._loadButton(button);
                         // Place button in grid layout (handle colspan/rowspan)
                         for (let r = cellY; r < cellY + rowSpan && r < maxRows; r++) {
                             for (let c = cellX; c < cellX + colSpan && c < maxCols; c++) {
@@ -2224,6 +2230,35 @@ class GridsetProcessor extends BaseProcessor {
         const AdmZip = (await import('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 XMLParser({
+                ignoreAttributes: false,
+                attributeNamePrefix: '@_',
+            });
+            const gridBuilder = new XMLBuilder({
+                ignoreAttributes: false,
+                format: true,
+                indentBy: '  ',
+                suppressEmptyNode: true,
+                suppressBooleanAttributes: false,
+            });
+            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)) {
@@ -2417,43 +2452,6 @@ class GridsetProcessor extends BaseProcessor {
                     originalGrid.Grid.WordList.Items.WordListItem = allItems;
                 }
             }
-            // Process WordList items attached to the page (from personalisation)
-            // These are tracked separately and shouldn't create new cells
-            // Use a known symbol key to check for WordList items
-            const WORDLIST_ITEMS_KEY = 'wordListItems';
-            const wordListItems = page[WORDLIST_ITEMS_KEY];
-            if (wordListItems && wordListItems.length > 0) {
-                // Ensure WordList structure exists
-                if (!originalGrid.Grid) {
-                    originalGrid.Grid = {};
-                }
-                if (!originalGrid.Grid.WordList) {
-                    originalGrid.Grid.WordList = {};
-                }
-                if (!originalGrid.Grid.WordList.Items) {
-                    originalGrid.Grid.WordList.Items = {};
-                }
-                const existingItems = originalGrid.Grid.WordList.Items.WordListItem ||
-                    originalGrid.Grid.WordList.Items.wordlistitem ||
-                    [];
-                const itemsArray = Array.isArray(existingItems) ? existingItems : [existingItems];
-                // Add new WordList items with proper Grid 3 format
-                for (const item of wordListItems) {
-                    itemsArray.push({
-                        Text: {
-                            p: {
-                                s: {
-                                    r: item.label,
-                                },
-                            },
-                        },
-                        Image: '',
-                        PartOfSpeech: 'Unknown',
-                    });
-                }
-                // Update the WordList
-                originalGrid.Grid.WordList.Items.WordListItem = itemsArray;
-            }
             // Build the updated grid XML and format for Grid 3 compatibility
             let builtXml = gridBuilder.build(originalGrid);
             builtXml = formatGrid3XmlComplete(builtXml);

package/dist/browser/processors/obfProcessor.js

@@ -18,6 +18,11 @@ function mapObfVisibility(hidden) {
 class ObfProcessor extends BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: true,
+            newCellCreation: 'allowed',
+        };
         this.imageCache = new Map(); // Cache for data URLs
     }
     /**
@@ -531,6 +536,46 @@ class ObfProcessor extends 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
@@ -543,6 +588,10 @@ class ObfProcessor extends 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,
@@ -557,7 +606,7 @@ class ObfProcessor extends BaseProcessor {
                 columns,
                 order,
             },
-            buttons: page.buttons.map((button) => {
+            buttons: buttons.map((button) => {
                 const extraButtonInfo = button;
                 const imageId = button.parameters?.image_id ||
                     button.parameters?.imageId ||
@@ -702,6 +751,7 @@ class ObfProcessor extends 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/browser/processors/opmlProcessor.js

@@ -6,6 +6,11 @@ import { getBasename, encodeText } from '../utils/io';
 class OpmlProcessor extends BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
     }
     processOutline(outline, parentId = null) {
         if (!outline || typeof outline !== 'object') {
@@ -37,7 +42,8 @@ class OpmlProcessor extends BaseProcessor {
                         message: '',
                         targetPageId: childText.replace(/[^a-zA-Z0-9]/g, '_'),
                     });
-                    page.addButton(button);
+                    // Load path: do not record as a user mutation
+                    page._loadButton(button);
                     const { page: childPage, childPages: grandChildren } = this.processOutline(child, page.id);
                     if (childPage && childPage.id)
                         childPages.push(childPage, ...grandChildren);

package/dist/browser/processors/snapProcessor.js

@@ -37,6 +37,11 @@ function mapSnapVisibility(visible) {
 class SnapProcessor extends 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
@@ -574,7 +579,8 @@ class SnapProcessor extends BaseProcessor {
                     // Add to the intended parent page
                     const parentPage = tree.getPage(parentUniqueId);
                     if (parentPage) {
-                        parentPage.addButton(button);
+                        // Load path: do not record as a user mutation
+                        parentPage._loadButton(button);
                         // Add button to grid layout if position data is available
                         const gridPositionStr = String(btnRow.GridPosition || '');
                         if (gridPositionStr && gridPositionStr.includes(',')) {

package/dist/browser/processors/touchchatProcessor.js

@@ -31,6 +31,11 @@ function mapTouchChatVisibility(visible) {
 class TouchChatProcessor extends BaseProcessor {
     constructor(options) {
         super(options);
+        this.capabilities = {
+            wordList: 'none',
+            preservesAssetsOnSave: false,
+            newCellCreation: 'allowed',
+        };
         this.tree = null;
         this.sourceFile = null;
     }
@@ -261,8 +266,8 @@ class TouchChatProcessor extends BaseProcessor {
                             // Set button's x and y coordinates
                             button.x = absoluteX;
                             button.y = absoluteY;
-                            // Add button to page
-                            page.addButton(button);
+                            // Add button to page (load path: do not record as a user mutation)
+                            page._loadButton(button);
                             // Place button in grid (handle span)
                             for (let r = absoluteY; r < absoluteY + safeSpanY && r < 10; r++) {
                                 for (let c = absoluteX; c < absoluteX + safeSpanX && c < 10; c++) {
@@ -363,7 +368,7 @@ class TouchChatProcessor extends BaseProcessor {
                     // Find the page that references this resource
                     const page = Object.values(tree.pages).find((p) => p.id === (numericToRid.get(btnRow.id) || String(btnRow.id)));
                     if (page)
-                        page.addButton(button);
+                        page._loadButton(button); // load path: do not record as a user mutation
                 });
             }
             catch (_e) {

package/dist/core/baseProcessor.d.ts

@@ -44,6 +44,7 @@ import { StringCasing } from './stringCasing';
 import { ValidationResult } from '../validation/validationTypes';
 import { BinaryOutput, FileAdapter, ProcessorInput } from '../utils/io';
 import { ZipAdapter } from '../utils/zip';
+import type { ProcessorCapabilities } from '../types/aac';
 export interface ProcessorConfig {
     excludeNavigationButtons?: boolean;
     excludeSystemButtons?: boolean;
@@ -90,6 +91,7 @@ export interface SourceString {
 }
 declare abstract class BaseProcessor {
     protected options: ProcessorConfig;
+    abstract readonly capabilities: ProcessorCapabilities;
     constructor(options?: ProcessorOptions);
     abstract extractTexts(filePathOrBuffer: ProcessorInput): Promise<string[]>;
     abstract loadIntoTree(filePathOrBuffer: ProcessorInput): Promise<AACTree>;