@willwade/aac-processors 0.2.12 → 0.2.14

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') {
@@ -40,7 +45,8 @@ class OpmlProcessor extends baseProcessor_1.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/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
@@ -577,7 +582,8 @@ class SnapProcessor extends baseProcessor_1.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/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;
     }
@@ -264,8 +269,8 @@ class TouchChatProcessor extends baseProcessor_1.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++) {
@@ -366,7 +371,7 @@ class TouchChatProcessor extends baseProcessor_1.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/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.12",
+  "version": "0.2.14",
   "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",