/**
 * `<canvas-ui>` — A2UI rendering surface.
 *
 * @see https://ui-kit.exe.xyz/site/components/canvas
 *
 * Hand-authored .d.ts (not codegen output). The yaml/a2ui.json sidecars
 * describe declarative component props; canvas-ui's primary public API is
 * a set of imperative runtime methods (`process`, `processAll`, `reset`,
 * `pushVersion`, `back`, `forward`) which cannot be expressed in the yaml
 * shape. Per ADR-0027, dts-codegen skips imperative methods — this file
 * carries them by hand so TypeScript consumers don't need `(canvas as any)`
 * casts. Keep this file in sync with `canvas.js` whenever the public API
 * surface changes.
 *
 * Closes FB-02 finding 2 (claims-ui-v2 2026-05-20 cold-start).
 */

import { UIElement } from '../../core/element.js';

export type CanvasInteractionEvent = CustomEvent<unknown>;

export class UICanvas extends UIElement {
  /** Component property: theme. */
  theme: string;

  /** Process a single A2UI message and apply it to the current surface. */
  process(message: unknown): void;

  /** Process an array of A2UI messages in order. */
  processAll(messages: unknown[]): void;

  /** Clear the canvas surface — discards all components. */
  reset(): void;

  /** Return the formatted innerHTML of the internal `<a2ui-root>`. */
  getHTML(): string;

  /**
   * Save the given messages to the history stack (enables back/forward
   * navigation). Truncates forward history if not at the newest version.
   */
  pushVersion(messages: unknown[]): void;

  /** Navigate to the previous history version. Returns false if at oldest. */
  back(): boolean;

  /** Navigate to the next history version. Returns false if at newest. */
  forward(): boolean;

  /** Number of saved versions in the history stack. */
  readonly historyLength: number;

  /** Current position in the history stack (0-based). */
  readonly historyIndex: number;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UICanvas, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'canvas-interaction', listener: (ev: CanvasInteractionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
