/**
 * A parsed ANSI color.
 *
 * - `name`: one of the 16 themable base colors (e.g. `"red"`, `"bright-red"`).
 * - `index`: a 256-color palette index (16-255); 0-15 are normalized to `name`.
 * - `rgb`: a 24-bit truecolor triple.
 */
export type AnsiColor =
  | { name: string }
  | { index: number }
  | { rgb: [number, number, number] };

/** Active styling while parsing. */
export type AnsiStyle = {
  bold?: boolean | undefined;
  dim?: boolean | undefined;
  italic?: boolean | undefined;
  underline?: boolean | undefined;
  reverse?: boolean | undefined;
  strikethrough?: boolean | undefined;
  conceal?: boolean | undefined;
  fg?: AnsiColor | undefined;
  bg?: AnsiColor | undefined;
};

/** Text run with styling. Omitted fields are inactive. */
export type AnsiSegment = {
  /** Literal text (escape codes stripped). */
  text: string;
  bold?: boolean;
  dim?: boolean;
  italic?: boolean;
  underline?: boolean;
  /** Strikethrough (SGR 9). */
  strikethrough?: boolean;
  /** Text is present for layout/copy but rendered invisible (SGR 8). */
  conceal?: boolean;
  fg?: AnsiColor;
  bg?: AnsiColor;
  /**
   * OSC 8 hyperlink target for this run, if any. Only `http:`, `https:`,
   * and `mailto:` schemes are accepted (case-insensitive); any other
   * scheme (e.g. `javascript:`, `data:`) or a scheme-less uri is dropped
   * as if no link were present.
   */
  link?: string;
};

/**
 * Parse ANSI SGR escape codes into styled segments. Malformed input is
 * dropped.
 *
 * This is a one-shot parse: a trailing unterminated escape sequence is
 * dropped rather than buffered, so calling it once per streamed chunk
 * loses any sequence that straddles a chunk boundary. Accumulate the full
 * string and re-parse it on each update instead of parsing per chunk.
 */
export declare function parseAnsi(text: string): AnsiSegment[];

/** An incremental ANSI parser session; see {@link createAnsiSession}. */
export interface AnsiSession {
  /** Feed the next chunk of text into the session. */
  append(chunk: string): void;
  /**
   * Completed segments so far, plus a live trailing segment for any
   * buffered-but-not-yet-flushed text. Does not mutate session state.
   */
  segments(): AnsiSegment[];
  /**
   * Flush remaining buffered text and drop any still-pending incomplete
   * sequence, then return the final segments. Calling `append()` after
   * `finish()` is unsupported.
   */
  finish(): AnsiSegment[];
}

/**
 * Create an incremental counterpart to {@link parseAnsi} for text that
 * arrives in chunks. Carries style, the open OSC 8 link, and a
 * partial-escape buffer across `append()` calls, so a chunk boundary that
 * splits a sequence doesn't get parsed wrong or dropped. `finish()`'s
 * output is identical to calling `parseAnsi` once on the full
 * concatenation of every appended chunk.
 */
export declare function createAnsiSession(): AnsiSession;