treeStructure.ts

// Note: To avoid circular dependency issues with Vite, we use type-only imports
import type {
  AACStyle,
  AACTreeMetadata,
  SnapMetadata,
  GridSetMetadata,
  AstericsGridMetadata,
  TouchChatMetadata,
  CellScanningOrder,
  ScanningSelectionMethod,
  AACWordListItem,
  AACPageMutation,
  ProcessorCapabilities,
} from '../types/aac';

// Re-export for consumers
export type {
  AACStyle,
  AACTreeMetadata,
  SnapMetadata,
  GridSetMetadata,
  AstericsGridMetadata,
  TouchChatMetadata,
  CellScanningOrder,
  ScanningSelectionMethod,
  AACWordListItem,
  AACPageMutation,
  ProcessorCapabilities,
};

// Semantic action categories for cross-platform compatibility
export enum AACSemanticCategory {
  COMMUNICATION = 'communication', // Speech, text output
  NAVIGATION = 'navigation', // Page/grid navigation
  TEXT_EDITING = 'text_editing', // Text manipulation
  SYSTEM_CONTROL = 'system_control', // Device/app control
  MEDIA = 'media', // Audio/video playback
  ACCESSIBILITY = 'accessibility', // Switch scanning, etc.
  CUSTOM = 'custom', // Platform-specific extensions
}

// Semantic intents within each category
export enum AACSemanticIntent {
  // Communication
  SPEAK_TEXT = 'SPEAK_TEXT',
  SPEAK_IMMEDIATE = 'SPEAK_IMMEDIATE',
  STOP_SPEECH = 'STOP_SPEECH',
  INSERT_TEXT = 'INSERT_TEXT',

  // Navigation
  NAVIGATE_TO = 'NAVIGATE_TO',
  GO_BACK = 'GO_BACK',
  GO_HOME = 'GO_HOME',

  // Text Editing
  DELETE_WORD = 'DELETE_WORD',
  DELETE_CHARACTER = 'DELETE_CHARACTER',
  CLEAR_TEXT = 'CLEAR_TEXT',
  COPY_TEXT = 'COPY_TEXT',
  PASTE_TEXT = 'PASTE_TEXT',

  // System Control
  SEND_KEYS = 'SEND_KEYS',
  MOUSE_CLICK = 'MOUSE_CLICK',

  // Media
  PLAY_SOUND = 'PLAY_SOUND',
  PLAY_VIDEO = 'PLAY_VIDEO',

  // Accessibility
  SCAN_NEXT = 'SCAN_NEXT',
  SCAN_SELECT = 'SCAN_SELECT',

  // Custom
  PLATFORM_SPECIFIC = 'PLATFORM_SPECIFIC',
}

/**
 * Scanning types for accessibility
 */
export enum AACScanType {
  LINEAR = 'linear', // Left-to-right, top-to-bottom
  ROW_COLUMN = 'row-column', // Scan rows, then columns
  COLUMN_ROW = 'column-row', // Scan columns, then rows
  BLOCK_ROW_COLUMN = 'block-row-column', // Scan blocks, then rows, then columns
  BLOCK_COLUMN_ROW = 'block-column-row', // Scan blocks, then columns, then rows
}

/**
 * Configuration for a scan block
 */
export interface AACScanBlock {
  id: number;
  name?: string;
  order?: number; // Sequence in scanning
  scanType?: AACScanType; // Override scanning within this block
}

// New semantic action interface for cross-platform compatibility
export interface AACSemanticAction {
  // Make category optional for backward-compat with older tests constructing minimal actions
  category?: AACSemanticCategory;
  intent: AACSemanticIntent | string;

  // Core parameters that most platforms understand
  text?: string; // Text content
  targetId?: string; // Navigation target
  audioData?: Buffer; // Audio content

  // Rich content for advanced platforms
  richText?: {
    text: string;
    symbols?: Array<{ text: string; image?: string }>;
    grammar?: {
      partOfSpeech?: string;
      person?: string;
      number?: string;
      verbState?: string;
    };
  };

  // Generic parameters bag for compatibility with older tests
  parameters?: { [key: string]: any };

  // Platform-specific extensions
  platformData?: {
    grid3?: {
      commandId: string;
      parameters: { [key: string]: any };
    };
    astericsGrid?: {
      modelName: string;
      properties: { [key: string]: any };
    };
    touchChat?: {
      actionCode: number;
      actionData: string;
      resourceId?: number;
    };
    snap?: {
      navigatePageId?: number;
      elementReferenceId?: number;
    };
    applePanels?: {
      actionType: string;
      parameters: { [key: string]: any };
    };
  };

  // Fallback for unknown platforms
  fallback?: {
    type: 'SPEAK' | 'NAVIGATE' | 'ACTION';
    message?: string;
    targetPageId?: string;
    temporary_home?: boolean | string | null;
    add_to_sentence?: boolean;
  };
}

export class AACButton {
  id: string;
  label: string;
  message: string;

  // Semantic action system
  semanticAction?: AACSemanticAction;

  targetPageId?: string;
  style?: AACStyle;
  audioRecording?: {
    id?: number;
    data?: Buffer;
    identifier?: string;
    metadata?: string;
  };

  // Extended properties for advanced platforms
  contentType?: 'Normal' | 'AutoContent' | 'Workspace' | 'LiveCell';
  contentSubType?: string;
  image?: string;
  resolvedImageEntry?: string; // normalized zip path to resolved image, if present
  symbolLibrary?: string;
  symbolPath?: string;
  x?: number;
  y?: number;
  columnSpan?: number;
  rowSpan?: number;
  /**
   * @deprecated Use scanBlock instead (singular, not array)
   */
  scanBlocks?: number[];
  /**
   * Scan block number (1-8) for block scanning
   */
  scanBlock?: number;
  visibility?: 'Visible' | 'Hidden' | 'Disabled' | 'PointerAndTouchOnly' | 'Empty';
  directActivate?: boolean;
  audioDescription?: string;
  parameters?: { [key: string]: any };
  // Predictions: Array of predicted word forms for smart grammar
  predictions?: string[];
  // Part-of-speech tag from gridset (e.g., 'Verb', 'Noun', 'Pronoun', 'Unknown')
  pos?: string;
  wordForms?: Array<{
    lang?: string;
    tags: string[];
    value: string;
    pronunciation?: string;
    base?: string;
  }>;
  semantic_id?: string; // Unique ID for buttons with same semantic meaning across boards
  clone_id?: string; // Unique ID for buttons with same label+location across boards

  constructor({
    id,
    label = '',
    message = '',
    targetPageId,
    semanticAction,
    audioRecording,
    style,
    contentType,
    contentSubType,
    image,
    resolvedImageEntry,
    symbolLibrary,
    symbolPath,
    x,
    y,
    columnSpan,
    rowSpan,
    scanBlocks,
    scanBlock,
    visibility,
    directActivate,
    parameters,
    predictions,
    pos,
    wordForms,
    semantic_id,
    clone_id,
    // Legacy input support
    type,
    action,
  }: {
    id: string;
    label?: string;
    message?: string;
    targetPageId?: string;
    semanticAction?: AACSemanticAction;
    audioRecording?: {
      id?: number;
      data?: Buffer;
      identifier?: string;
      metadata?: string;
    };
    style?: AACStyle;
    contentType?: 'Normal' | 'AutoContent' | 'Workspace' | 'LiveCell';
    contentSubType?: string;
    image?: string;
    resolvedImageEntry?: string;
    symbolLibrary?: string;
    symbolPath?: string;
    x?: number;
    y?: number;
    columnSpan?: number;
    rowSpan?: number;
    scanBlocks?: number[];
    scanBlock?: number;
    visibility?: 'Visible' | 'Hidden' | 'Disabled' | 'PointerAndTouchOnly' | 'Empty';
    directActivate?: boolean;
    parameters?: { [key: string]: any };
    predictions?: string[];
    pos?: string;
    wordForms?: Array<{
      lang?: string;
      tags: string[];
      value: string;
      pronunciation?: string;
      base?: string;
    }>;
    semantic_id?: string;
    clone_id?: string;
    // Legacy constructor properties for backward compatibility
    type?: 'SPEAK' | 'NAVIGATE' | 'ACTION';
    action?: {
      type: 'SPEAK' | 'NAVIGATE' | 'ACTION';
      targetPageId?: string;
      message?: string;
    } | null;
  }) {
    this.id = id;
    this.label = label;
    this.message = message;
    this.targetPageId = targetPageId;
    this.semanticAction = semanticAction;
    this.audioRecording = audioRecording;
    this.style = style;
    this.contentType = contentType;
    this.contentSubType = contentSubType;
    this.image = image;
    this.resolvedImageEntry = resolvedImageEntry;
    this.symbolLibrary = symbolLibrary;
    this.symbolPath = symbolPath;
    this.x = x;
    this.y = y;
    this.columnSpan = columnSpan;
    this.rowSpan = rowSpan;
    this.scanBlocks = scanBlocks;
    this.scanBlock = scanBlock;
    this.visibility = visibility;
    this.directActivate = directActivate;
    this.parameters = parameters;
    this.predictions = predictions;
    this.pos = pos;
    this.wordForms = wordForms;
    this.semantic_id = semantic_id;
    this.clone_id = clone_id;

    // Legacy mapping: if no semanticAction provided, derive from legacy `action` first
    if (!this.semanticAction && action) {
      if (action.type === 'NAVIGATE' && (action.targetPageId || this.targetPageId)) {
        if (!this.targetPageId) this.targetPageId = action.targetPageId;
        this.semanticAction = {
          category: AACSemanticCategory.NAVIGATION,
          intent: AACSemanticIntent.NAVIGATE_TO,
          targetId: this.targetPageId,
          fallback: { type: 'NAVIGATE', targetPageId: this.targetPageId },
        };
      } else if (action.type === 'SPEAK') {
        const text = action.message || this.message || this.label || '';
        if (!this.message) this.message = text;
        this.semanticAction = {
          category: AACSemanticCategory.COMMUNICATION,
          intent: AACSemanticIntent.SPEAK_TEXT,
          text,
          fallback: { type: 'SPEAK', message: text },
        };
      } else {
        this.semanticAction = {
          category: AACSemanticCategory.SYSTEM_CONTROL,
          intent: AACSemanticIntent.PLATFORM_SPECIFIC,
          fallback: { type: 'ACTION' },
        };
      }
    }

    // Legacy mapping: if still no semanticAction and `type` provided
    if (!this.semanticAction && type) {
      if (type === 'NAVIGATE' && this.targetPageId) {
        this.semanticAction = {
          category: AACSemanticCategory.NAVIGATION,
          intent: AACSemanticIntent.NAVIGATE_TO,
          targetId: this.targetPageId,
          fallback: { type: 'NAVIGATE', targetPageId: this.targetPageId },
        };
      } else if (type === 'SPEAK') {
        const text = this.message || this.label || '';
        this.semanticAction = {
          category: AACSemanticCategory.COMMUNICATION,
          intent: AACSemanticIntent.SPEAK_TEXT,
          text,
          fallback: { type: 'SPEAK', message: text },
        };
      } else {
        this.semanticAction = {
          category: AACSemanticCategory.SYSTEM_CONTROL,
          intent: AACSemanticIntent.PLATFORM_SPECIFIC,
          fallback: { type: 'ACTION' },
        };
      }
    }
  }

  // Legacy compatibility properties
  get type(): 'SPEAK' | 'NAVIGATE' | 'ACTION' | undefined {
    if (this.semanticAction) {
      const i = String(this.semanticAction.intent);
      if (i === 'NAVIGATE_TO') return 'NAVIGATE';
      if (i === 'SPEAK_TEXT' || i === 'SPEAK_IMMEDIATE') return 'SPEAK';
      return 'ACTION';
    }
    if (this.targetPageId) return 'NAVIGATE';
    if (this.message) return 'SPEAK';
    return 'SPEAK';
  }

  get action(): {
    type: 'SPEAK' | 'NAVIGATE' | 'ACTION';
    targetPageId?: string;
    message?: string;
  } | null {
    const t = this.type;
    if (!t) return null;
    if (t === 'SPEAK' && !this.message && !this.label && !this.semanticAction) {
      return null;
    }
    return { type: t, targetPageId: this.targetPageId, message: this.message };
  }
}

export class AACPage {
  id: string;
  name: string;
  grid: Array<Array<AACButton | null>>;
  buttons: AACButton[];
  parentId: string | null;
  style?: AACStyle;
  locale?: string;
  descriptionHtml?: string;
  images?: any[];
  sounds?: any[];
  // Metrics support: Track semantic/clone IDs used on this page
  semantic_ids?: string[];
  clone_ids?: string[];
  // Scanning configuration for this page
  scanningConfig?: import('../types/aac').ScanningConfig;

  // Scanning support
  scanType?: AACScanType;
  scanBlocksConfig?: AACScanBlock[];

  // Mutation tracking
  private _pendingMutations: AACPageMutation[] = [];

  constructor({
    id,
    name = '',
    grid = [],
    buttons = [],
    parentId = null,
    style,
    locale,
    descriptionHtml,
    images,
    sounds,
    semantic_ids,
    clone_ids,
    scanningConfig,
    scanBlocksConfig,
    scanType,
  }: {
    id: string;
    name?: string;
    grid?: Array<Array<AACButton | null>> | { columns: number; rows: number };
    buttons?: AACButton[];
    parentId?: string | null;
    style?: AACStyle;
    locale?: string;
    descriptionHtml?: string;
    images?: any[];
    sounds?: any[];
    semantic_ids?: string[];
    clone_ids?: string[];
    scanningConfig?: import('../types/aac').ScanningConfig;
    scanBlocksConfig?: AACScanBlock[];
    scanType?: AACScanType;
  }) {
    this.id = id;
    this.name = name;
    if (Array.isArray(grid)) {
      this.grid = grid;
    } else if (grid && typeof grid === 'object' && 'columns' in grid && 'rows' in grid) {
      const cols = (grid as any).columns as number;
      const rows = (grid as any).rows as number;
      this.grid = Array.from({ length: rows }, () => Array.from({ length: cols }, () => null));
    } else {
      this.grid = [];
    }
    this.buttons = buttons;
    this.parentId = parentId;
    this.style = style;
    this.locale = locale;
    this.descriptionHtml = descriptionHtml;
    this.images = images;
    this.sounds = sounds;
    this.semantic_ids = semantic_ids;
    this.clone_ids = clone_ids;
    this.scanningConfig = scanningConfig;
    this.scanBlocksConfig = scanBlocksConfig;
    this.scanType = scanType;
  }

  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' });
  }
}

export class AACTree {
  pages: { [key: string]: AACPage };
  metadata: AACTreeMetadata;

  public get rootId(): string | null {
    return this.metadata.defaultHomePageId || null;
  }
  public set rootId(id: string | null) {
    this.metadata.defaultHomePageId = id || undefined;
  }

  public get toolbarId(): string | null {
    return this.metadata.toolbarId || null;
  }
  public set toolbarId(id: string | null) {
    this.metadata.toolbarId = id || undefined;
  }

  public get dashboardId(): string | null {
    return this.metadata.dashboardId || null;
  }
  public set dashboardId(id: string | null) {
    this.metadata.dashboardId = id || undefined;
  }

  constructor() {
    this.pages = {};
    this.metadata = {};
  }

  addPage(page: AACPage): void {
    this.pages[page.id] = page;
    if (!this.rootId) this.rootId = page.id;
  }

  getPage(id: string): AACPage | undefined {
    return this.pages[id];
  }

  traverse(callback: (page: AACPage) => void): void {
    const queue: string[] = Object.keys(this.pages);
    const visited = new Set<string>();

    while (queue.length > 0) {
      const id = queue.shift();
      if (!id || visited.has(id)) continue;
      visited.add(id);

      const page = this.pages[id];
      if (page) {
        callback(page);
        // Add child pages to queue
        page.buttons
          .filter((b) => {
            const i = String(b.semanticAction?.intent);
            return i === 'NAVIGATE_TO' || !!b.semanticAction?.targetId || !!b.targetPageId;
          })
          .forEach((b) => {
            const target = b.semanticAction?.targetId || b.targetPageId;
            if (target) queue.push(target);
          });
      }
    }
  }
}