oh-my-pi/packages/natives/native/index.d.ts

/* auto-generated by NAPI-RS */
/* eslint-disable */
/**
 * Long-lived macOS appearance observer.
 *
 * Subscribes to `AppleInterfaceThemeChangedNotification` via
 * `CFDistributedNotificationCenter` and calls the provided callback
 * with `"dark"` or `"light"` on each change (and once on start).
 *
 * A 2-second polling timer also runs as fallback — distributed
 * notifications may not reliably reach background threads on all
 * macOS versions.
 *
 * On non-macOS platforms, `start()` returns a no-op observer.
 */
export declare class MacAppearanceObserver {
  static start(callback: (err: null | Error, appearance: MacOSAppearance) => void): MacAppearanceObserver
  stop(): void
}

/**
 * Long-lived macOS power assertion.
 *
 * On macOS this acquires an `IOKit` assertion that prevents idle sleep until
 * the handle is stopped or dropped. On other platforms it is a no-op handle so
 * the caller can keep one cross-platform code path.
 */
export declare class MacOSPowerAssertion {
  /** Acquire a macOS power assertion. */
  static start(options?: MacOSPowerAssertionOptions | undefined | null): MacOSPowerAssertion
  /** Release the power assertion early. */
  stop(): void
}

/** Image container for native interop. */
export declare class PhotonImage {
  /**
   * Create a new `PhotonImage` from encoded image bytes (PNG, JPEG, WebP,
   * GIF). Returns the decoded image handle on success.
   *
   * # Errors
   * Returns an error if the image format cannot be detected or decoded.
   */
  static parse(bytes: Uint8Array): ImageTask
  /** Get the image width in pixels. */
  get width(): number
  /** Get the image height in pixels. */
  get height(): number
  /**
   * Encode the image to bytes in the specified format.
   *
   * # Errors
   * Returns an error if encoding fails or format is invalid.
   */
  encode(format: ImageFormat, quality: number): Promise<Array<number>>
  /**
   * Resize the image to the specified pixel dimensions using the filter.
   * Returns a new `PhotonImage` containing the resized image.
   */
  resize(width: number, height: number, filter: SamplingFilter): ImageTask
}

/** Stateful PTY session for interactive stdin/stdout passthrough. */
export declare class PtySession {
  constructor()
  /** Start a PTY command and stream output chunks via callback. */
  start(options: PtyStartOptions, onChunk?: ((error: Error | null, chunk: string) => void) | undefined | null): Promise<PtyRunResult>
  /** Write raw input bytes to PTY stdin. */
  write(data: string): void
  /** Resize the active PTY. */
  resize(cols: number, rows: number): void
  /** Force-kill the active PTY command. */
  kill(): void
}

/** Persistent brush-core shell session. */
export declare class Shell {
  /**
   * Create a new shell session from optional configuration.
   *
   * The options set session-scoped environment variables and a snapshot path.
   */
  constructor(options?: ShellOptions | undefined | null)
  /**
   * Run a shell command using the provided options.
   *
   * The `on_chunk` callback receives streamed stdout/stderr output. Returns
   * the exit code when the command completes, or flags when cancelled or
   * timed out.
   */
  run(options: ShellRunOptions, onChunk?: ((error: Error | null, chunk: string) => void) | undefined | null): Promise<ShellRunResult>
  /**
   * Abort all running commands for this shell session.
   *
   * Returns `Ok(())` even when no commands are running.
   */
  abort(): Promise<void>
}

/**
 * Apply ast-grep rewrite rules to matching files; honors `dryRun` and returns
 * a promise.
 */
export declare function astEdit(options: AstReplaceOptions): Promise<AstReplaceResult>

/** One ast-grep match with source range and optional meta-variables. */
export interface AstFindMatch {
  /** Display path of the matching file. */
  path: string
  /** Matched source text. */
  text: string
  /** Start byte offset in the file (UTF-8 byte index). */
  byteStart: number
  /** End byte offset in the file (exclusive UTF-8 byte index). */
  byteEnd: number
  /** 1-based start line. */
  startLine: number
  /** 1-based start column. */
  startColumn: number
  /** 1-based end line. */
  endLine: number
  /** 1-based end column. */
  endColumn: number
  /** Meta-variable name to captured text, when `includeMeta` was enabled. */
  metaVariables?: Record<string, string>
}

/** Options for `astGrep`: patterns, scan scope, and match limits. */
export interface AstFindOptions {
  /** ast-grep patterns to search for (OR across patterns). */
  patterns?: Array<string>
  /** Language override; otherwise inferred from file extension per candidate. */
  lang?: string
  /** Single file or directory to scan (combined with `glob` when set). */
  path?: string
  /** Optional glob filter relative to the search root. */
  glob?: string
  /** Rule selector for multi-rule ast-grep configurations. */
  selector?: string
  /** Pattern strictness; defaults to smart matching when omitted. */
  strictness?: AstMatchStrictness
  /** Maximum matches to return after `offset` (default applies when omitted). */
  limit?: number
  /** Number of leading matches to skip before applying `limit`. */
  offset?: number
  /** When true, include meta-variable bindings per match. */
  includeMeta?: boolean
  /**
   * Reserved for contextual snippets; not used by the current native find
   * path.
   */
  context?: number
  /** Optional cancellation handle (library-specific). */
  signal?: unknown
  /** Wall-clock timeout for the worker task in milliseconds. */
  timeoutMs?: number
}

/** Aggregated search statistics and any parse or compile diagnostics. */
export interface AstFindResult {
  /** Page of matches after sort, offset, and limit. */
  matches: Array<AstFindMatch>
  /** Total matches found before paging (can exceed `matches.length`). */
  totalMatches: number
  /** Distinct files that contained at least one match. */
  filesWithMatches: number
  /** Files examined for the query. */
  filesSearched: number
  /** True when results were truncated by `limit`. */
  limitReached: boolean
  /** Non-fatal parse or pattern errors collected during the run. */
  parseErrors?: Array<string>
}

/**
 * Search source files with ast-grep patterns; returns a promise resolved on a
 * worker thread.
 */
export declare function astGrep(options: AstFindOptions): Promise<AstFindResult>

/** ast-grep pattern strictness (controls how patterns match syntax). */
export declare enum AstMatchStrictness {
  /** Match at the concrete syntax tree level. */
  Cst = 'cst',
  /** Balanced default suitable for most searches. */
  Smart = 'smart',
  /** Match at the AST level. */
  Ast = 'ast',
  /** More permissive matching. */
  Relaxed = 'relaxed',
  /** Match structural signatures. */
  Signature = 'signature',
  /** Template-style pattern matching. */
  Template = 'template'
}

/**
 * One textual replacement applied to a file (before/after slice and
 * coordinates).
 */
export interface AstReplaceChange {
  /** File path for this change. */
  path: string
  /** Original matched text. */
  before: string
  /** Replacement text. */
  after: string
  /** Start byte offset of the replaced span. */
  byteStart: number
  /** End byte offset of the replaced span (exclusive). */
  byteEnd: number
  /**
   * Length of deleted text in bytes (may differ from `byteEnd - byteStart`
   * for edge cases).
   */
  deletedLength: number
  /** 1-based start line of the match. */
  startLine: number
  /** 1-based start column. */
  startColumn: number
  /** 1-based end line. */
  endLine: number
  /** 1-based end column. */
  endColumn: number
}

/** Per-file replacement count after an `astEdit` run. */
export interface AstReplaceFileChange {
  /** File that had replacements. */
  path: string
  /** Number of replacements in that file. */
  count: number
}

/**
 * Options for `astEdit`: rewrite rules, scan scope, safety limits, and
 * dry-run.
 */
export interface AstReplaceOptions {
  /** Map of pattern string to replacement template. */
  rewrites?: Record<string, string>
  /** Language override; otherwise inferred from discovered files. */
  lang?: string
  /** Single file or directory to rewrite. */
  path?: string
  /** Optional glob filter within the search root. */
  glob?: string
  /** Rule selector for multi-rule configurations. */
  selector?: string
  /** Pattern strictness for rewrites. */
  strictness?: AstMatchStrictness
  /** When true (default), compute changes without writing files. */
  dryRun?: boolean
  /** Cap on replacement applications across all files. */
  maxReplacements?: number
  /** Cap on distinct files that may be modified. */
  maxFiles?: number
  /** Fail the operation when a file cannot be parsed for rewriting. */
  failOnParseError?: boolean
  /** Optional cancellation handle. */
  signal?: unknown
  /** Wall-clock timeout for the worker task in milliseconds. */
  timeoutMs?: number
}

/** Summary of an ast-grep rewrite pass, including whether disk writes occurred. */
export interface AstReplaceResult {
  /** Individual replacement records (may be large). */
  changes: Array<AstReplaceChange>
  /** Replacement counts grouped by file. */
  fileChanges: Array<AstReplaceFileChange>
  /** Total replacements applied or previewed. */
  totalReplacements: number
  /** Files that had at least one replacement. */
  filesTouched: number
  /** Files considered for rewriting. */
  filesSearched: number
  /** False when `dryRun` prevented writing. */
  applied: boolean
  /** True when limits stopped further replacements. */
  limitReached: boolean
  /** Parse or pattern errors when not failing the whole operation. */
  parseErrors?: Array<string>
}

/** Clipboard image payload encoded as PNG bytes. */
export interface ClipboardImage {
  /** PNG-encoded image bytes. */
  data: Uint8Array
  /** MIME type for the encoded image payload. */
  mimeType: string
}

/** A context line (before or after a match). */
export interface ContextLine {
  /** 1-indexed line number in the source file. */
  lineNumber: number
  /** Raw line content (trimmed line ending). */
  line: string
}

/**
 * Copy plain text to the system clipboard.
 *
 * # Parameters
 * - `text`: UTF-8 text to place on the clipboard.
 *
 * # Errors
 * Returns an error if clipboard access fails.
 */
export declare function copyToClipboard(text: string): void

/**
 * Detect macOS system appearance via CoreFoundation.
 * Returns `"dark"` or `"light"` on macOS, `null` on other platforms.
 */
export declare function detectMacOSAppearance(): MacOSAppearance | null

/** Ellipsis strategy for [`truncate_to_width`]. */
export declare enum Ellipsis {
  /** Use a single Unicode ellipsis character ("…"). */
  Unicode = 0,
  /** Use three ASCII dots ("..."). */
  Ascii = 1,
  /** Omit ellipsis entirely. */
  Omit = 2
}

/**
 * Encode image bytes into a SIXEL escape sequence for terminal rendering.
 *
 * The input image is decoded and resized to the requested pixel dimensions
 * before encoding.
 *
 * # Errors
 * Returns an error if decoding, resizing, or SIXEL encoding fails.
 */
export declare function encodeSixel(bytes: Uint8Array, targetWidthPx: number, targetHeightPx: number): string

/**
 * Execute a brush shell command.
 *
 * Creates a fresh session for each call. The `on_chunk` callback receives
 * streamed stdout/stderr output. Returns the exit code when the command
 * completes, or flags when cancelled or timed out.
 */
export declare function executeShell(options: ShellExecuteOptions, onChunk?: ((error: Error | null, chunk: string) => void) | undefined | null): Promise<ShellExecuteResult>

/**
 * Extract the before/after slices around an overlay region.
 *
 * Preserves ANSI state so the `after` segment renders correctly after
 * truncation.
 */
export declare function extractSegments(line: string, beforeEnd: number, afterStart: number, afterLen: number, strictAfter: boolean, tabWidth: number): ExtractSegmentsResult

/** Before/after UTF-16 segments around an overlay region, with measured widths. */
export interface ExtractSegmentsResult {
  /** UTF-16 content before the overlay region. */
  before: string
  /** Visible width of the `before` segment. */
  beforeWidth: number
  /** UTF-16 content after the overlay region. */
  after: string
  /** Visible width of the `after` segment. */
  afterWidth: number
}

/** Resolved filesystem entry kind for glob filters and match metadata. */
export declare enum FileType {
  /** Regular file. */
  File = 1,
  /** Directory. */
  Dir = 2,
  /** Symbolic link. */
  Symlink = 3
}

/** Fuzzy file path search for autocomplete. */
export declare function fuzzyFind(options: FuzzyFindOptions): Promise<FuzzyFindResult>

/** A single match in fuzzy find results. */
export interface FuzzyFindMatch {
  /** Relative path from the search root (uses `/` separators). */
  path: string
  /** Whether this entry is a directory. */
  isDirectory: boolean
  /** Match quality score (higher is better). */
  score: number
}

/** Options for fuzzy file path search. */
export interface FuzzyFindOptions {
  /** Fuzzy query to match against file paths (case-insensitive). */
  query: string
  /** Directory to search. */
  path: string
  /** Include hidden files (default: false). */
  hidden?: boolean
  /** Respect .gitignore (default: true). */
  gitignore?: boolean
  /** Enable shared filesystem scan cache (default: false). */
  cache?: boolean
  /** Maximum number of matches to return (default: 100). */
  maxResults?: number
  /** Abort signal for cancelling the operation. */
  signal?: unknown
  /** Timeout in milliseconds for the operation. */
  timeoutMs?: number
}

/** Result of fuzzy file path search. */
export interface FuzzyFindResult {
  /** Matched entries (up to `maxResults`). */
  matches: Array<FuzzyFindMatch>
  /** Total number of matches found (may exceed `matches.len()`). */
  totalMatches: number
}

/** Get list of supported languages. */
export declare function getSupportedLanguages(): Array<string>

/**
 * Get work profile data from the last N seconds.
 *
 * Always-on profiling - no need to start/stop. Just call this to get
 * recent activity.
 */
export declare function getWorkProfile(lastSeconds: number): WorkProfile

/**
 * Find filesystem entries matching a glob pattern.
 *
 * Resolves the search root, scans entries, applies glob and optional file-type
 * filters, and optionally streams each accepted match through `on_match`.
 *
 * If `sortByMtime` is enabled, all matching entries are collected, sorted by
 * descending mtime, then truncated to `maxResults`.
 *
 * # Errors
 * Returns an error when the search path cannot be resolved, the path is not a
 * directory, the glob pattern is invalid, or cancellation/timeout is
 * triggered.
 */
export declare function glob(options: GlobOptions, onMatch?: ((error: Error | null, match: GlobMatch) => void) | undefined | null): Promise<GlobResult>

/** A single filesystem entry from a directory scan. */
export interface GlobMatch {
  /** Relative path from the search root, using forward slashes. */
  path: string
  /** Resolved filesystem type for the match. */
  fileType: FileType
  /**
   * Modification time in milliseconds since Unix epoch (from
   * `symlink_metadata`).
   */
  mtime?: number
}

/** Input options for `glob`, including traversal, filtering, and cancellation. */
export interface GlobOptions {
  /** Glob pattern to match (e.g., "*.ts"). */
  pattern: string
  /** Directory to search. */
  path: string
  /**
   * Filter by file type: "file", "dir", or "symlink". Symlinks are
   * matched for file/dir filters based on their target type.
   */
  fileType?: FileType
  /** Match simple patterns recursively by default (`*.ts` -> recursive). */
  recursive?: boolean
  /** Include hidden files (default: false). */
  hidden?: boolean
  /** Maximum number of results to return. */
  maxResults?: number
  /** Respect .gitignore files (default: true). */
  gitignore?: boolean
  /** Enable shared filesystem scan cache (default: false). */
  cache?: boolean
  /** Sort results by mtime (most recent first) before applying limit. */
  sortByMtime?: boolean
  /**
   * Include `node_modules` entries when the pattern does not explicitly
   * mention them.
   */
  includeNodeModules?: boolean
  /** Abort signal for cancelling the operation. */
  signal?: unknown
  /** Timeout in milliseconds for the operation. */
  timeoutMs?: number
}

/** Result payload returned by a glob operation. */
export interface GlobResult {
  /** Matched filesystem entries. */
  matches: Array<GlobMatch>
  /** Number of returned matches (`matches.len()`), clamped to `u32::MAX`. */
  totalMatches: number
}

/**
 * Search files for a regex pattern.
 *
 * # Arguments
 * - `options`: Pattern, path, filters, and output mode.
 * - `on_match`: Optional callback invoked per match/result.
 *
 * # Returns
 * Aggregated results across matching files.
 */
export declare function grep(options: GrepOptions, onMatch?: ((error: Error | null, match: GrepMatch) => void) | undefined | null): Promise<GrepResult>

/** A single match in a grep result. */
export interface GrepMatch {
  /** File path for the match (relative for directory searches). */
  path: string
  /** 1-indexed line number (0 for count-only entries). */
  lineNumber: number
  /** The matched line content (empty for count-only entries). */
  line: string
  /** Context lines before the match. */
  contextBefore?: Array<ContextLine>
  /** Context lines after the match. */
  contextAfter?: Array<ContextLine>
  /** Whether the line was truncated. */
  truncated?: boolean
  /** Per-file match count (count mode only). */
  matchCount?: number
}

/** Options for searching files on disk. */
export interface GrepOptions {
  /** Regex pattern to search for. */
  pattern: string
  /** Directory or file to search. */
  path: string
  /** Glob filter for filenames (e.g., "*.ts"). */
  glob?: string
  /** Filter by file type (e.g., "js", "py", "rust"). */
  type?: string
  /** Case-insensitive search. */
  ignoreCase?: boolean
  /** Enable multiline matching. */
  multiline?: boolean
  /** Include hidden files (default: true). */
  hidden?: boolean
  /** Respect .gitignore files (default: true). */
  gitignore?: boolean
  /** Enable shared filesystem scan cache (default: false). */
  cache?: boolean
  /** Maximum number of matches to return. */
  maxCount?: number
  /** Skip first N matches. */
  offset?: number
  /** Lines of context before matches. */
  contextBefore?: number
  /** Lines of context after matches. */
  contextAfter?: number
  /** Lines of context before/after matches (legacy). */
  context?: number
  /** Truncate lines longer than this (characters). */
  maxColumns?: number
  /** Output mode (content, filesWithMatches, or count). */
  mode?: GrepOutputMode
  /** Abort signal for cancelling the operation. */
  signal?: unknown
  /** Timeout in milliseconds for the operation. */
  timeoutMs?: number
}

/** Output mode for [`search`] and [`grep`] (string values match JS callers). */
export declare enum GrepOutputMode {
  /** Emit matched lines (and optional context lines). */
  Content = 'content',
  /** Emit per-file or total counts instead of line content. */
  Count = 'count',
  /** Emit one row per file that matched, without line content. */
  FilesWithMatches = 'filesWithMatches'
}

/** Result of searching files. */
export interface GrepResult {
  /** Matches or per-file counts, depending on output mode. */
  matches: Array<GrepMatch>
  /** Total matches across all files. */
  totalMatches: number
  /** Number of files with at least one match. */
  filesWithMatches: number
  /** Number of files searched. */
  filesSearched: number
  /** Whether the limit/offset stopped the search early. */
  limitReached?: boolean
}

/**
 * Quick check if content matches a pattern.
 *
 * # Arguments
 * - `content`: `Uint8Array`/`Buffer` (zero-copy) or `string` (UTF-8).
 * - `pattern`: `Uint8Array`/`Buffer` (zero-copy) or `string` (UTF-8).
 * - `ignore_case`: Case-insensitive matching.
 * - `multiline`: Enable multiline regex mode.
 *
 * # Returns
 * True if any match exists; false on no match.
 */
export declare function hasMatch(content: string | Uint8Array, pattern: string | Uint8Array, ignoreCase?: boolean | undefined | null, multiline?: boolean | undefined | null): boolean

/**
 * Highlight code and return ANSI-colored lines.
 *
 * # Arguments
 * * `code` - The source code to highlight
 * * `lang` - Language identifier (e.g., "rust", "typescript", "python")
 * * `colors` - Theme colors as ANSI escape sequences
 *
 * # Returns
 * Highlighted code with ANSI color codes, or the original code if highlighting
 * fails.
 */
export declare function highlightCode(code: string, lang: string | undefined | null, colors: HighlightColors): string

/**
 * Theme colors for syntax highlighting.
 * Each color is an ANSI escape sequence (e.g., "\x1b[38;2;255;0;0m").
 */
export interface HighlightColors {
  /** ANSI color for comments. */
  comment: string
  /** ANSI color for keywords. */
  keyword: string
  /** ANSI color for function names. */
  function: string
  /** ANSI color for variables and identifiers. */
  variable: string
  /** ANSI color for string literals. */
  string: string
  /** ANSI color for numeric literals. */
  number: string
  /** ANSI color for type identifiers. */
  type: string
  /** ANSI color for operators. */
  operator: string
  /** ANSI color for punctuation tokens. */
  punctuation: string
  /** ANSI color for diff inserted lines. */
  inserted?: string
  /** ANSI color for diff deleted lines. */
  deleted?: string
}

/**
 * Convert HTML source to Markdown with optional preprocessing.
 *
 * # Errors
 * Returns an error if the conversion fails or the worker task aborts.
 */
export declare function htmlToMarkdown(html: string, options?: HtmlToMarkdownOptions | undefined | null): Promise<string>

/** Options for HTML to Markdown conversion. */
export interface HtmlToMarkdownOptions {
  /** Remove navigation elements, forms, headers, footers. */
  cleanContent?: boolean
  /** Skip images during conversion. */
  skipImages?: boolean
}

/** Output format for [`PhotonImage::encode`]. */
export declare enum ImageFormat {
  /** PNG encoded bytes. */
  PNG = 0,
  /** JPEG encoded bytes. */
  JPEG = 1,
  /** WebP encoded bytes. */
  WEBP = 2,
  /** GIF encoded bytes. */
  GIF = 3
}

/**
 * Invalidate the filesystem scan cache.
 *
 * When called with a path, removes entries for roots containing that path.
 * When called without a path, clears the entire cache.
 *
 * Intended to be called after agent file mutations (write, edit, rename,
 * delete).
 */
export declare function invalidateFsScanCache(path?: string | undefined | null): void

/** Event types from Kitty keyboard protocol (flag 2). */
export declare enum KeyEventType {
  /** Key press event. */
  Press = 1,
  /** Key repeat event. */
  Repeat = 2,
  /** Key release event. */
  Release = 3
}

/**
 * Kill a process tree (the process and all its descendants).
 *
 * Arguments: `pid` is the root process and `signal` is the kill signal.
 * Kills children first (bottom-up) to prevent orphan re-parenting issues.
 * Returns the number of processes successfully killed.
 */
export declare function killTree(pid: number, signal: number): number

/**
 * List all descendant PIDs of `pid`.
 *
 * Returns an empty array if the process has no children or doesn't exist.
 */
export declare function listDescendants(pid: number): Array<number>

/**
 * System UI appearance reported by native macOS APIs (`detectMacOSAppearance`
 * and observer).
 */
export declare enum MacOSAppearance {
  /** Dark color scheme. */
  Dark = 'dark',
  /** Light color scheme. */
  Light = 'light'
}

/** Options for starting a macOS power assertion. */
export interface MacOSPowerAssertionOptions {
  /** Human-readable reason shown in macOS power diagnostics. */
  reason?: string
  /** Keep the display awake in addition to preventing idle system sleep. */
  display?: boolean
}

/** A single match in the content. */
export interface Match {
  /** 1-indexed line number. */
  lineNumber: number
  /** The matched line content. */
  line: string
  /** Context lines before the match. */
  contextBefore?: Array<ContextLine>
  /** Context lines after the match. */
  contextAfter?: Array<ContextLine>
  /** Whether the line was truncated. */
  truncated?: boolean
}

/**
 * Match input data against a key identifier string.
 *
 * Returns true when the bytes represent the specified key with modifiers.
 */
export declare function matchesKey(data: string, keyId: string, kittyProtocolActive: boolean): boolean

/**
 * Match Kitty protocol input against a codepoint and modifier mask.
 *
 * Returns true when the parsed sequence matches the expected codepoint (or
 * base layout key) and modifier bits.
 */
export declare function matchesKittySequence(data: string, expectedCodepoint: number, expectedModifier: number): boolean

/**
 * Check if input matches a legacy escape sequence for the given key name.
 *
 * Returns true only when the byte sequence maps to the exact key identifier.
 */
export declare function matchesLegacySequence(data: string, keyName: string): boolean

/** N-API opt-in handle for the minimizer. */
export interface MinimizerOptions {
  /** Master switch. Absent / false = disabled. */
  enabled?: boolean
  /**
   * Optional path to a TOML settings file whose values override
   * field-level defaults. `~` is expanded.
   */
  settingsPath?: string
  /**
   * Optional xxHash64 digest (hex) of the settings file contents. When
   * supplied, the engine refuses to honor a settings file whose hash does
   * not match — a lightweight trust gate for agent-controllable paths.
   */
  settingsHash?: string
  /**
   * Opt-in allowlist of program names (e.g. `"git"`). When empty or
   * absent, all built-in filters are active.
   */
  only?: Array<string>
  /** Program names explicitly excluded from minimization. */
  except?: Array<string>
  /**
   * Maximum captured bytes per command before the engine falls back to
   * the raw, un-minimized output. Default 4 MiB.
   */
  maxCaptureBytes?: number
}

/**
 * Telemetry for a single minimization.
 *
 * Surfaced when the minimizer actually rewrote the command's output. The
 * session layer is expected to persist `original_text` via its
 * `ArtifactManager`, splice the resulting `artifact://<id>` reference
 * into `text`, and replace any previously streamed raw output with the
 * minimized text.
 */
export interface MinimizerResult {
  /**
   * Dispatch label produced by the minimizer (e.g. `"git"`,
   * `"pipeline:gradle"`, `"pipeline+builtin"`).
   */
  filter: string
  /**
   * The minimized replacement text. Callers that streamed raw chunks
   * during execution should clear and replace their accumulated output
   * with this text.
   */
  text: string
  /** The full original capture, before minimization. */
  originalText: string
  /** Captured byte length before minimization. */
  inputBytes: number
  /** Byte length of the minimized text the consumer received. */
  outputBytes: number
}

/** Parsed Kitty keyboard protocol sequence result for a Kitty input sequence. */
export interface ParsedKittyResult {
  /** Primary codepoint associated with the key. */
  codepoint: number
  /** Optional shifted key codepoint from the sequence. */
  shiftedKey?: number
  /** Optional base layout key codepoint from the sequence. */
  baseLayoutKey?: number
  /** Modifier bitmask (shift/alt/ctrl), excluding lock bits. */
  modifier: number
  /** Optional event type (1 = press, 2 = repeat, 3 = release). */
  eventType?: KeyEventType
}

/**
 * Parse terminal input and return a normalized key identifier.
 *
 * Returns a key id like "escape" or "ctrl+c", or None if unrecognized.
 */
export declare function parseKey(data: string, kittyProtocolActive: boolean): string | null

/**
 * Parse a Kitty keyboard protocol sequence.
 *
 * Returns a structured parse result when the input is a valid Kitty sequence.
 */
export declare function parseKittySequence(data: string): ParsedKittyResult | null

/** Probe whether `ProjFS` overlay virtualization can be started on this system. */
export declare function projfsOverlayProbe(): ProjfsOverlayProbeResult

/**
 * Result of probing Windows Projected File System (`ProjFS`) support for
 * overlay workflows.
 */
export interface ProjfsOverlayProbeResult {
  /** True when `ProjFS` APIs are available and loaded. */
  available: boolean
  /**
   * Human-readable reason when `available` is false (e.g. wrong OS or missing
   * DLL).
   */
  reason?: string
}

/**
 * Start a `ProjFS` overlay: `projection_root` shows the merged view;
 * `lower_root` is the backing tree.
 */
export declare function projfsOverlayStart(lowerRoot: string, projectionRoot: string): void

/** Stop `ProjFS` virtualization for an active `projection_root` session. */
export declare function projfsOverlayStop(projectionRoot: string): void

/** Result of a PTY command run. */
export interface PtyRunResult {
  /** Exit code when the command completes. */
  exitCode?: number
  /** Whether command was cancelled by signal/user kill. */
  cancelled: boolean
  /** Whether command timed out. */
  timedOut: boolean
}

/** Options for running a command in a PTY session. */
export interface PtyStartOptions {
  /** Command string to execute. */
  command: string
  /** Working directory for command execution. */
  cwd?: string
  /** Environment variables for this command. */
  env?: Record<string, string>
  /** Timeout in milliseconds before cancelling. */
  timeoutMs?: number
  /** Abort signal for cancelling the operation. */
  signal?: unknown
  /** PTY column count. */
  cols?: number
  /** PTY row count. */
  rows?: number
}

/**
 * Read an image from the system clipboard.
 *
 * Returns `Ok(None)` when no image data is available.
 *
 * # Errors
 * Returns an error if clipboard access fails or image encoding fails.
 */
export declare function readImageFromClipboard(): Promise<ClipboardImage | undefined | null>

/** Sampling filter for resize operations. */
export declare enum SamplingFilter {
  /** Nearest-neighbor sampling (fast, low quality). */
  Nearest = 1,
  /** Triangle filter (linear interpolation). */
  Triangle = 2,
  /** Catmull-Rom filter with sharper edges. */
  CatmullRom = 3,
  /** Gaussian filter for smoother results. */
  Gaussian = 4,
  /** Lanczos3 filter for high-quality downscaling. */
  Lanczos3 = 5
}

/**
 * Strip ANSI escape sequences, remove control characters / lone surrogates,
 * and normalize line endings.
 */
export declare function sanitizeText(text: string): string

/**
 * Search content for a pattern (one-shot, compiles pattern each time).
 * For repeated searches with the same pattern, use [`grep`] with file filters.
 *
 * # Arguments
 * - `content`: `Uint8Array`/`Buffer` (zero-copy) or `string` (UTF-8).
 * - `options`: Regex settings, context, and output mode.
 *
 * # Returns
 * Match list plus counts/limit status; errors are surfaced in `error`.
 */
export declare function search(content: string | Uint8Array, options: SearchOptions): SearchResult

/** Options for searching file content. */
export interface SearchOptions {
  /** Regex pattern to search for. */
  pattern: string
  /** Case-insensitive search. */
  ignoreCase?: boolean
  /** Enable multiline matching. */
  multiline?: boolean
  /** Maximum number of matches to return. */
  maxCount?: number
  /** Skip first N matches. */
  offset?: number
  /** Lines of context before matches. */
  contextBefore?: number
  /** Lines of context after matches. */
  contextAfter?: number
  /** Lines of context before/after matches (legacy). */
  context?: number
  /** Truncate lines longer than this (characters). */
  maxColumns?: number
  /** Output mode (content or count). */
  mode?: GrepOutputMode
}

/** Result of searching content. */
export interface SearchResult {
  /** All matches found. */
  matches: Array<Match>
  /** Total number of matches (may exceed `matches.len()` due to offset/limit). */
  matchCount: number
  /** Whether the limit was reached. */
  limitReached: boolean
  /** Error message, if any. */
  error?: string
}

/** Options for executing a shell command via brush-core. */
export interface ShellExecuteOptions {
  /** Command string to execute in the shell. */
  command: string
  /** Working directory for the command. */
  cwd?: string
  /** Environment variables to apply for this command only. */
  env?: Record<string, string>
  /** Environment variables to apply once per session. */
  sessionEnv?: Record<string, string>
  /** Timeout in milliseconds before cancelling the command. */
  timeoutMs?: number
  /** Optional snapshot file to source on session creation. */
  snapshotPath?: string
  /** Optional per-command output minimizer configuration. */
  minimizer?: MinimizerOptions
  /** Abort signal for cancelling the operation. */
  signal?: unknown
}

/** Result of executing a shell command via brush-core. */
export interface ShellExecuteResult {
  /** Exit code when the command completes normally. */
  exitCode?: number
  /** Whether the command was cancelled via abort. */
  cancelled: boolean
  /** Whether the command timed out before completion. */
  timedOut: boolean
  /** See [`ShellRunResult::minimized`]. */
  minimized?: MinimizerResult
}

/** Options for configuring a persistent shell session. */
export interface ShellOptions {
  /** Environment variables to apply once per session. */
  sessionEnv?: Record<string, string>
  /** Optional snapshot file to source on session creation. */
  snapshotPath?: string
  /** Optional per-command output minimizer configuration. */
  minimizer?: MinimizerOptions
}

/** Options for running a shell command. */
export interface ShellRunOptions {
  /** Command string to execute in the shell. */
  command: string
  /** Working directory for the command. */
  cwd?: string
  /** Environment variables to apply for this command only. */
  env?: Record<string, string>
  /** Timeout in milliseconds before cancelling the command. */
  timeoutMs?: number
  /** Abort signal for cancelling the operation. */
  signal?: unknown
}

/** Result of running a shell command. */
export interface ShellRunResult {
  /** Exit code when the command completes normally. */
  exitCode?: number
  /** Whether the command was cancelled via abort. */
  cancelled: boolean
  /** Whether the command timed out before completion. */
  timedOut: boolean
  /**
   * When the minimizer rewrote the captured output, this carries the
   * original buffer + telemetry so the session layer can persist it as
   * an artifact and splice an `artifact://<id>` reference into the
   * minimized text shown to the agent. `None` when nothing was rewritten.
   */
  minimized?: MinimizerResult
}

/**
 * Visible slice of a line after ANSI-aware column selection
 * (`sliceWithWidth`).
 */
export interface SliceResult {
  /** UTF-16 slice containing the selected text. */
  text: string
  /** Visible width of the slice in terminal cells. */
  width: number
}

/**
 * Slice a range of visible columns from a line.
 *
 * Counts terminal cells, skipping ANSI escapes, and optionally enforces strict
 * width.
 */
export declare function sliceWithWidth(line: string, startCol: number, length: number, strict: boolean | undefined | null, tabWidth: number): SliceResult

/**
 * Check if a language is supported for highlighting.
 * Returns true if the language has either direct support or a fallback
 * mapping.
 */
export declare function supportsLanguage(lang: string): boolean

/**
 * Truncate text to a visible width, preserving ANSI codes.
 *
 * Pads with spaces when requested.
 */
export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind: Ellipsis | undefined | null, pad: boolean | undefined | null, tabWidth: number): string

/**
 * Calculate visible width of text, excluding ANSI escape sequences.
 *
 * Tabs count as a fixed-width cell.
 */
export declare function visibleWidth(text: string, tabWidth: number): number

/** Profiling results returned to JavaScript. */
export interface WorkProfile {
  /** Folded stack format for flamegraph tools. */
  folded: string
  /** Markdown summary of profiling results. */
  summary: string
  /** SVG flamegraph (if generation succeeded). */
  svg?: string
  /** Total profiled duration in milliseconds. */
  totalMs: number
  /** Number of samples collected. */
  sampleCount: number
}

/**
 * Wrap text to a visible width, preserving ANSI escape codes across line
 * breaks.
 *
 * Returns UTF-16 lines with active SGR codes carried across line boundaries.
 */
export declare function wrapTextWithAnsi(text: string, width: number, tabWidth: number): Array<string>