start of Mutation API on AACPage

Author: willwade

src/core/baseProcessor.ts

@@ -45,6 +45,7 @@ import { StringCasing, detectCasing, isNumericOrEmpty } from './stringCasing';
 import { ValidationResult } from '../validation/validationTypes';
 import { BinaryOutput, defaultFileAdapter, FileAdapter, ProcessorInput } from '../utils/io';
 import { getZipAdapter, ZipAdapter } from '../utils/zip';
+import type { ProcessorCapabilities } from '../types/aac';
 
 // Configuration options for processors
 export interface ProcessorConfig {
@@ -122,6 +123,7 @@ export interface SourceString {
 
 abstract class BaseProcessor {
   protected options: ProcessorConfig;
+  abstract readonly capabilities: ProcessorCapabilities;
 
   constructor(options: ProcessorOptions = {}) {
     // Default configuration: exclude navigation/system buttons

src/core/treeStructure.ts

@@ -8,6 +8,9 @@ import type {
   TouchChatMetadata,
   CellScanningOrder,
   ScanningSelectionMethod,
+  AACWordListItem,
+  AACPageMutation,
+  ProcessorCapabilities,
 } from '../types/aac';
 
 // Re-export for consumers
@@ -20,6 +23,9 @@ export type {
   TouchChatMetadata,
   CellScanningOrder,
   ScanningSelectionMethod,
+  AACWordListItem,
+  AACPageMutation,
+  ProcessorCapabilities,
 };
 
 // Semantic action categories for cross-platform compatibility
@@ -414,6 +420,9 @@ export class AACPage {
   scanType?: AACScanType;
   scanBlocksConfig?: AACScanBlock[];
 
+  // Mutation tracking
+  private _pendingMutations: AACPageMutation[] = [];
+
   constructor({
     id,
     name = '',
@@ -474,6 +483,55 @@ export class AACPage {
 
   addButton(button: AACButton): void {
     this.buttons.push(button);
+    // Record the mutation
+    this._pendingMutations.push({ type: 'addButton', button });
+  }
+
+  /**
+   * Get the list of pending mutations for this page (read-only)
+   */
+  get pendingMutations(): readonly AACPageMutation[] {
+    return Object.freeze([...this._pendingMutations]);
+  }
+
+  /**
+   * Remove a button by ID
+   * @param buttonId - The ID of the button to remove
+   */
+  removeButton(buttonId: string): void {
+    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: string, patch: Partial<AACButton>): void {
+    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: AACWordListItem): void {
+    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: string | ((item: AACWordListItem) => boolean)): void {
+    this._pendingMutations.push({ type: 'removeWordListItem', match: textOrPredicate });
+  }
+
+  /**
+   * Clear all items from the page's WordList
+   */
+  clearWordList(): void {
+    this._pendingMutations.push({ type: 'clearWordList' });
   }
 }
 

src/processors/applePanelsProcessor.ts

@@ -169,6 +169,12 @@ function normalizeActionParameters(input: unknown): ApplePanelsActionParameters
 }
 
 class ApplePanelsProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'none' as const,
+    preservesAssetsOnSave: false,
+    newCellCreation: 'allowed' as const,
+  };
+
   constructor(options?: ProcessorOptions) {
     super(options);
   }

src/processors/astericsGridProcessor.ts

@@ -720,6 +720,12 @@ function mapAstericsVisibility(hidden: boolean | undefined): 'Hidden' | 'Visible
 }
 
 class AstericsGridProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'none' as const,
+    preservesAssetsOnSave: false,
+    newCellCreation: 'allowed' as const,
+  };
+
   private loadAudio: boolean = false;
 
   constructor(options: ProcessorOptions & { loadAudio?: boolean } = {}) {

src/processors/dotProcessor.ts

@@ -24,6 +24,12 @@ interface DotEdge {
 }
 
 class DotProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'none' as const,
+    preservesAssetsOnSave: false,
+    newCellCreation: 'allowed' as const,
+  };
+
   constructor(options?: ProcessorOptions) {
     super(options);
   }

src/processors/excelProcessor.ts

@@ -15,6 +15,12 @@ import { AACStyle } from '../types/aac';
  * Supports visual styling, navigation links, and vocabulary analysis workflows
  */
 export class ExcelProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'none' as const,
+    preservesAssetsOnSave: false,
+    newCellCreation: 'allowed' as const,
+  };
+
   private static readonly NAVIGATION_BUTTONS = ['Home', 'Message Bar', 'Delete', 'Back', 'Clear'];
 
   /**

src/processors/gridsetProcessor.ts

@@ -48,6 +48,12 @@ import { ProcessorInput, decodeText } from '../utils/io';
 import { ZipFile } from '../utils/zip';
 
 class GridsetProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'native' as const,
+    preservesAssetsOnSave: true,
+    newCellCreation: 'restricted' as const,
+  };
+
   constructor(options?: ProcessorOptions) {
     super(options);
   }

src/processors/obfProcessor.ts

@@ -102,6 +102,12 @@ interface ObfBoard {
 }
 
 class ObfProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'none' as const,
+    preservesAssetsOnSave: true,
+    newCellCreation: 'allowed' as const,
+  };
+
   private zipFile?: ZipAdapter;
   private imageCache: Map<string, string> = new Map(); // Cache for data URLs
 

src/processors/obfsetProcessor.ts

@@ -37,6 +37,12 @@ interface ObfsetBoard {
 }
 
 export class ObfsetProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'none' as const,
+    preservesAssetsOnSave: false,
+    newCellCreation: 'allowed' as const,
+  };
+
   constructor(options: ProcessorOptions = {}) {
     super(options);
   }

src/processors/opmlProcessor.ts

@@ -32,6 +32,12 @@ interface OpmlDocument {
 }
 
 class OpmlProcessor extends BaseProcessor {
+  readonly capabilities = {
+    wordList: 'none' as const,
+    preservesAssetsOnSave: false,
+    newCellCreation: 'allowed' as const,
+  };
+
   constructor(options?: ProcessorOptions) {
     super(options);
   }