@f5-sales-demo/pi-natives 19.51.2

package/native/index.d.ts

@@ -0,0 +1,1370 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * Parsed file as a chunk tree: query nodes, render views, format grep hits,
+ * and apply edits.
+ */
+export declare class ChunkState {
+  /**
+   * Build chunk state by parsing `source` with the given `language` id (e.g.
+   * `typescript`).
+   */
+  static parse(source: string, language: string): ChunkState
+  /** Normalized language identifier used for the tree-sitter parse. */
+  get language(): string
+  /** Full source text for this file. */
+  get source(): string
+  /** Stable checksum for the entire file contents. */
+  get checksum(): string
+  /** Line count of the source buffer. */
+  get lineCount(): number
+  /** Count of tree-sitter error nodes seen while building the tree. */
+  get parseErrors(): number
+  /** True when a fallback classifier produced the tree. */
+  get fallback(): boolean
+  /** Selector path string for the synthetic root (often empty). */
+  get rootPath(): string
+  /** Top-level child chunk paths under the root. */
+  get rootChildren(): Array<string>
+  /** Total number of chunk nodes. */
+  get chunkCount(): number
+  /** True when the parsed file contains unresolved merge conflicts. */
+  hasConflicts(): boolean
+  /** Count of unresolved merge conflicts represented in the chunk tree. */
+  conflictCount(): number
+  /** Summary for the root chunk, if it exists. */
+  root(): ChunkInfo | null
+  /** Look up [`ChunkInfo`] for a chunk selector path. */
+  chunk(chunkPath: string): ChunkInfo | null
+  /** Every chunk node as a [`ChunkInfo`] list. */
+  chunks(): Array<ChunkInfo>
+  /**
+   * Direct children of `chunkPath` (use empty or omit for root); errors if
+   * the path is missing.
+   */
+  children(chunkPath?: string | undefined | null): Array<ChunkInfo>
+  /** Chunk selector path that contains 1-based source line `line`, if any. */
+  lineToContainingChunkPath(line: number): string | null
+  /** Render a chunk subtree or listing as UTF-8 text for tools. */
+  render(params: RenderParams): string
+  /**
+   * Parse `readPath` (selector, line scope, etc.) and return rendered text or
+   * errors.
+   */
+  renderRead(params: ReadRenderParams): ReadResult
+  /**
+   * Prefix a grep line with `display_path` and the chunk path for
+   * `line_number`, when known.
+   */
+  formatGrepLine(displayPath: string, lineNumber: number, line: string): string
+  /**
+   * Apply batch edits, re-parse, write files, and return updated state and
+   * messaging.
+   */
+  applyEdits(params: EditParams): EditResult
+}
+
+/**
+ * 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>
+}
+
+/**
+ * How chunk anchors are formatted in rendered output (name and checksum
+ * visibility).
+ */
+export declare enum ChunkAnchorStyle {
+  /** `[.name#crc]` style anchor. */
+  Full = 'full',
+  /** `[.kind#crc]` style anchor (kind is the name prefix before `_`). */
+  Kind = 'kind',
+  /** `[#crc]` style anchor. */
+  Bare = 'bare',
+  /** `[.name]` without checksum. */
+  FullOmit = 'full-omit',
+  /** `[.kind]` without checksum. */
+  KindOmit = 'kind-omit',
+  /** Minimal anchor without name or checksum. */
+  None = 'none'
+}
+
+/** Structural edit to apply relative to a chunk anchor. */
+export declare enum ChunkEditOp {
+  /** Put new content into the targeted region. */
+  Put = 'put',
+  /** Find and replace a literal substring within the targeted region. */
+  Replace = 'replace',
+  /** Remove the targeted region. */
+  Delete = 'delete',
+  /** Insert `content` before the targeted region span. */
+  Before = 'before',
+  /** Insert `content` after the targeted region span. */
+  After = 'after',
+  /** Insert `content` at the start inside the targeted region. */
+  Prepend = 'prepend',
+  /** Insert `content` at the end inside the targeted region. */
+  Append = 'append'
+}
+
+/** How a chunk participates in a focus-scoped render pass. */
+export declare enum ChunkFocusMode {
+  /** Emit full content and recurse normally. */
+  Expanded = 'expanded',
+  /** Emit just the opening anchor; do not recurse or emit body. */
+  Collapsed = 'collapsed',
+  /**
+   * Emit opening + closing anchors; recurse into focused children only.
+   * Interior gap lines between children are suppressed.
+   */
+  Container = 'container'
+}
+
+/** Summary of a single chunk node for tool output and navigation. */
+export interface ChunkInfo {
+  /** Chunk selector path within the tree. */
+  path: string
+  /** Bare chunk identifier (without kind prefix), if available. */
+  identifier?: string
+  /** Stable checksum anchor for this chunk. */
+  checksum: string
+  /** 1-based start line in the source file (inclusive). */
+  startLine: number
+  /** 1-based end line in the source file (inclusive). */
+  endLine: number
+  /** Whether this node is a leaf (no child chunks). */
+  leaf: boolean
+}
+
+/** Result of resolving a chunk read request against the tree. */
+export declare enum ChunkReadStatus {
+  /** Selector matched a chunk and content was produced. */
+  Ok = 'ok',
+  /** No chunk matched the requested selector. */
+  NotFound = 'not_found',
+  /** Chunk matched but does not support the requested region. */
+  UnsupportedRegion = 'unsupported_region'
+}
+
+/** Outcome of resolving which chunk was read for a `renderRead`-style request. */
+export interface ChunkReadTarget {
+  /** Whether the selector matched. */
+  status: ChunkReadStatus
+  /** Sanitized selector string that was applied. */
+  selector: string
+}
+
+export declare enum ChunkRegion {
+  Head = '^',
+  Body = '~'
+}
+
+/** 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
+
+/**
+ * One edit in a batch; targets a chunk via `sel`/`crc` (with params-level
+ * defaults).
+ */
+export interface EditOperation {
+  /** Edit kind (replace, delete, insert relative to anchor). */
+  op: ChunkEditOp
+  /**
+   * Chunk selector path; falls back to `EditParams.defaultSelector` when
+   * omitted.
+   */
+  sel?: string
+  /**
+   * Optional checksum anchor; falls back to `EditParams.defaultCrc` when
+   * omitted.
+   */
+  crc?: string
+  /** Region to target. When omitted, targets the full chunk. */
+  region?: ChunkRegion
+  /** Replacement or inserted text (meaning depends on `op`). */
+  content?: string
+  /**
+   * For `replace` op: literal substring to find inside the target chunk.
+   * Must match exactly once.
+   */
+  find?: string
+}
+
+/** Arguments for applying a batch of chunk edits to a file. */
+export interface EditParams {
+  /** Edits to apply in order. */
+  operations: Array<EditOperation>
+  /**
+   * When true, normalize indentation for response rendering and inserted
+   * content. When false, preserve literal tabs/spaces.
+   */
+  normalizeIndent?: boolean
+  /** Default chunk selector when an `EditOperation` omits `sel`. */
+  defaultSelector?: string
+  /** Default checksum when an `EditOperation` omits `crc`. */
+  defaultCrc?: string
+  /** Anchor formatting for rendered response text. */
+  anchorStyle?: ChunkAnchorStyle
+  /** Working directory used to resolve `filePath` and display paths. */
+  cwd: string
+  /** Path to the source file to edit (often relative to `cwd`). */
+  filePath: string
+}
+
+/**
+ * Result of applying edits: new parse state plus before/after source and
+ * messaging.
+ */
+export interface EditResult {
+  /** Chunk tree state after applying edits and re-parsing. */
+  state: ChunkState
+  /** Full file text before edits. */
+  diffBefore: string
+  /** Full file text after edits. */
+  diffAfter: string
+  /** Rendered summary for tooling (hunks, anchors), driven by `anchorStyle`. */
+  responseText: string
+  /** Whether the on-disk source changed. */
+  changed: boolean
+  /** Whether the updated source re-parsed without fatal issues. */
+  parseValid: boolean
+  /** Absolute or normalized paths that were written or touched. */
+  touchedPaths: Array<string>
+  /** Non-fatal issues (e.g. selector warnings) collected during apply. */
+  warnings: Array<string>
+}
+
+/** 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
+}
+
+/** Path + focus mode pair for the N-API boundary (`HashMap` doesn't cross FFI). */
+export interface FocusedPath {
+  path: string
+  mode: ChunkFocusMode
+}
+
+/**
+ * Format one chunk anchor string for a node at `depth` using `style` and
+ * optional checksum omission.
+ */
+export declare function formatAnchor(name: string, checksum: string, style: ChunkAnchorStyle, omitChecksum?: boolean | undefined | null): string
+
+/** 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 control flow keywords (if, else, for, while, return,
+   * import).
+   */
+  control?: 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
+
+/** 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>
+
+/**
+ * Options for `ChunkState.renderRead`: selector path, display path, and
+ * optional line scoping.
+ */
+export interface ReadRenderParams {
+  /** Read selector (`sel=...` path, line range, or empty for whole tree). */
+  readPath: string
+  /** Path shown in titles and error messages (often the file path). */
+  displayPath: string
+  /** Optional language label for the rendered block. */
+  languageTag?: string
+  /** Hide checksums in rendered anchors. */
+  omitChecksum: boolean
+  /** Anchor formatting style. */
+  anchorStyle?: ChunkAnchorStyle
+  /** Optional absolute file line range to intersect with the resolved chunk. */
+  absoluteLineRange?: VisibleLineRange
+  /** Replace tabs in embedded previews. */
+  tabReplacement?: string
+  /** When true, normalize displayed indentation to canonical tabs. */
+  normalizeIndent?: boolean
+}
+
+/** Rendered chunk text plus optional resolution metadata for the read request. */
+export interface ReadResult {
+  /** Rendered UTF-8 text (chunk tree, notice, or error message). */
+  text: string
+  /** When a selector was used, whether it matched and which selector applied. */
+  chunk?: ChunkReadTarget
+}
+
+/**
+ * Options for `ChunkState.render`: which subtree to show and how anchors
+ * appear.
+ */
+export interface RenderParams {
+  /** Path of the chunk to render; `None` uses the tree root. */
+  chunkPath?: string
+  /** Title line shown above the tree (often the file path). */
+  title: string
+  /** Optional language label for the header block. */
+  languageTag?: string
+  /** Restrict output to an inclusive line range of the file. */
+  visibleRange?: VisibleLineRange
+  /** When true, list only direct children instead of a full subtree. */
+  renderChildrenOnly: boolean
+  /** Hide checksums in anchors when true. */
+  omitChecksum: boolean
+  /** Anchor formatting style for chunk headers. */
+  anchorStyle?: ChunkAnchorStyle
+  /** Include a one-line preview for leaf chunks. */
+  showLeafPreview: boolean
+  /** Replace tab characters in displayed previews (e.g. two spaces). */
+  tabReplacement?: string
+  /** When true, normalize displayed indentation to canonical tabs. */
+  normalizeIndent?: boolean
+  /**
+   * When set, restrict rendering to these chunks with their specified focus
+   * modes. Everything not in this list is skipped.
+   */
+  focusedPaths?: Array<FocusedPath>
+}
+
+/** 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
+  /** 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
+}
+
+/** 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
+}
+
+/** 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
+}
+
+/**
+ * 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
+
+/**
+ * Inclusive 1-based line range within a source file (used for scoped chunk
+ * rendering).
+ */
+export interface VisibleLineRange {
+  /** First line to include. */
+  startLine: number
+  /** Last line to include. */
+  endLine: number
+}
+
+/**
+ * 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>