/**
 * Metadata for an emphasized line.
 */
export interface EmphasisMeta {
  /** Optional description for this emphasis */
  description?: string;
  /** Position: 'single' for single-line, 'start'/'end' for multiline range bounds, undefined for middle */
  position?: 'single' | 'start' | 'end';
  /** Whether this is a strong emphasis (description ended with !) */
  strong?: boolean;
  /** For text highlighting: the specific texts to highlight within the line */
  highlightTexts?: string[];
  /** Whether this line's region is the focused region (for padding) */
  focus?: boolean;
  /** Whether the line itself should receive data-hl. True for highlight directives and false for focus-only directives. */
  lineHighlight: boolean;
  /** How many containing highlight ranges wrap this line (used for mark data-hl propagation) */
  containingRangeDepth?: number;
  /** Optional per-directive padding override for this region */
  paddingFrameMaxSize?: number;
  /** Optional per-directive focus max size override for this region */
  focusFramesMaxSize?: number;
  /**
   * True when the overrides were propagated from a multiline range
   * rather than set by an explicit per-line directive.
   * Explicit overrides take precedence over propagated ones in regions.
   */
  propagatedOverride?: boolean;
}
/**
 * A range of lines that forms a frame in the output.
 */
export interface FrameRange {
  /** First line number (1-based, inclusive) */
  startLine: number;
  /** Last line number (1-based, inclusive) */
  endLine: number;
  /** The type of frame */
  type: 'normal' | 'padding-top' | 'highlighted' | 'highlighted-unfocused' | 'focus' | 'focus-unfocused' | 'padding-bottom' | 'comment';
  /** Index of the highlighted region this frame belongs to. Present on region-type frames. */
  regionIndex?: number;
  /**
   * Present on frames created by splitting an oversized region via `focusFramesMaxSize`.
   * - `'visible'` — the focused window kept visible when collapsed.
   * - `'hidden'`  — the overflow portion hidden when collapsed.
   */
  truncated?: 'visible' | 'hidden';
}
/**
 * Options for the enhance code emphasis factory.
 */
export interface EnhanceCodeEmphasisOptions {
  /**
   * Maximum number of padding lines above and below the focused highlight region.
   * Padding frames provide surrounding context for the highlighted code.
   * Set to 0 or omit to disable padding frames.
   */
  paddingFrameMaxSize?: number;
  /**
   * Maximum total number of lines in the focus area (padding-top + focused region + padding-bottom).
   * When the region fits within this limit, padding sizes are reduced so the total focus area
   * fits. The remainder after subtracting the region size is split: floor(remainder/2) for
   * padding-top and ceil(remainder/2) for padding-bottom.
   * When the region exceeds this limit, a focused window is taken from the start of the
   * region, and the remaining overflow lines are marked as unfocused.
   * @default 12
   */
  focusFramesMaxSize?: number;
  /**
   * How to handle a focused region that exceeds `focusFramesMaxSize`.
   *
   * - `'truncate'` (default) — keep the first `focusFramesMaxSize` lines visible
   *   as a window and hide the overflow.
   * - `'hide'` — produce no visible-window frame at all: the block collapses to
   *   nothing (`focusedLines === 0`) while staying `collapsible`, so the collapsed
   *   state is empty and expanding reveals the whole source.
   *
   * Applies to every focus trigger — an oversized `@highlight` region, an
   * oversized `@focus` / `@focus-start` region, and the auto-focus-from-line-1
   * case (no emphasis comments) when the source exceeds `focusFramesMaxSize`.
   * Regions that fit within `focusFramesMaxSize` are unaffected.
   *
   * @default 'truncate'
   */
  oversizedFocus?: 'truncate' | 'hide';
  /**
   * When `true`, throws an error if a `@highlight-text` match has to be
   * fragmented across element boundaries (producing `data-hl-part` spans).
   * Wrapping multiple complete elements in a single `data-hl` span is still
   * allowed — only boundary-straddling matches are rejected.
   */
  strictHighlightText?: boolean;
  /**
   * When `true`, emits a `data-frame-indent` attribute on highlighted/focus
   * region frames indicating the shared leading indent level. Consumers can
   * use this to visually shift collapsible regions horizontally when
   * surrounding context lines are hidden. Off by default since most demos
   * don't need it and it bloats the rendered HTML.
   *
   * Indent and padding are alternatives for conveying surrounding context.
   * Combining this with the `paddingFrameMaxSize` option throws (configure one
   * or the other); a per-region `@padding` directive in the source is allowed
   * and ignored while this is set.
   * @default false
   */
  emitFrameIndent?: boolean;
}
/** Default max number of lines kept in focus when not explicitly configured. */
export declare const DEFAULT_FOCUS_FRAMES_MAX_SIZE = 12;
/**
 * Calculates frame ranges for the code block based on emphasized lines.
 *
 * This is a pure function that operates on line numbers — no HAST traversal.
 * It groups consecutive highlighted lines into regions, determines the focused
 * region (first by default, or the one with `focus: true`), computes padding
 * for the focused region, and returns an ordered array of frame ranges covering
 * all lines 1 through totalLines.
 *
 * @param emphasizedLines - Map of line numbers to their emphasis metadata
 * @param totalLines - Total number of lines in the code block
 * @param options - Optional padding configuration
 * @param normalFrameMaxSize - Maximum lines per normal frame. Read from `hast.data.frameSize`
 *   (set by `starryNightGutter` when it splits a tree into multiple frames) so that emphasis
 *   reframing matches the original gutter split size.
 * @returns Ordered array of frame ranges covering all lines
 */
export declare function calculateFrameRanges(emphasizedLines: Map<number, EmphasisMeta>, totalLines: number, options?: EnhanceCodeEmphasisOptions, normalFrameMaxSize?: number): FrameRange[];