feat: add text locator js api

bindings/js/README.md

@@ -49,7 +49,12 @@ All derive from `TuiTestError` and carry `kind` and `exitCode`. `waitX` and `exp
 
 ## API
 
-`new TuiTest(session?, { profile?, timeouts?, artifacts? })` mirrors the cli: `open` / `run`, `type` / `write`, `submit`, `press` / `keys`, `mouse.click|move|down|up|drag|scroll`, `resize`, `signal` / `kill`, `state`, `text`, `cells`, `getCommand` / `getOutput` / `getExitCode` / `getCwd` / `getCursor` / `getSize` / `getTitle`, `screenshot`, `waitText` / `waitTitle` / `waitIdle` / `waitCommand` / `waitExit` / `waitReady`, `expectText` / `expectTitle` / `expectExitCode` / `expectOutput` / `expectSnapshot`, `close`, and `closeQuiet`.
+`new TuiTest(session?, { profile?, timeouts?, artifacts? })` mirrors the cli: `open` / `run`, `type` / `write`, `submit`, `press` / `keys`, `mouse.click|move|down|up|drag|scroll`, `resize`, `signal` / `kill`, `state`, `text`, `findText`, `cells`, `getCommand` / `getOutput` / `getExitCode` / `getCwd` / `getCursor` / `getSize` / `getTitle`, `screenshot`, `waitText` / `waitTitle` / `waitIdle` / `waitCommand` / `waitExit` / `waitReady`, `expectText` / `expectTitle` / `expectExitCode` / `expectOutput` / `expectSnapshot`, `close`, and `closeQuiet`.
+
+`findText(text, options)` returns zero-based row/column spans and supports
+normalized whitespace, `after` / `before` anchors, and any/unique/first/last/nth
+occurrences. `expectText` accepts the same selector options plus `style` checks
+for colors, bold, dim, italic, underline, inverse, hidden, strikethrough, and blink.
 
 Module-level helpers: `sessions()`, `closeAll()`, `getRecording()`, `uniqueSession()`.
 

bindings/js/native/index.d.ts

@@ -8,6 +8,7 @@ export declare class NativeSession {
   close(): Promise<void>
   state(): Promise<State>
   text(full?: boolean | undefined | null): Promise<string>
+  findText(text: string, options?: TextSelectorOptions | undefined | null): Promise<Array<TextMatch>>
   packedScreen(full?: boolean | undefined | null): Promise<PackedScreen>
   cells(x: number, y: number, w?: number | undefined | null, h?: number | undefined | null): Promise<Array<Cell>>
   getCommand(): Promise<string | null>
@@ -86,9 +87,29 @@ export interface ExpectTextOptions {
   regex?: boolean
   full?: boolean
   strict?: boolean
+  whitespace?: string
+  occurrence?: string
+  nth?: number
+  afterText?: string
+  afterRegex?: boolean
+  afterOccurrence?: string
+  afterNth?: number
+  beforeText?: string
+  beforeRegex?: boolean
+  beforeOccurrence?: string
+  beforeNth?: number
   not?: boolean
   fg?: string
   bg?: string
+  bold?: boolean
+  dim?: boolean
+  italic?: boolean
+  underlineStyle?: string
+  underlineColor?: string
+  inverse?: boolean
+  hidden?: boolean
+  strikethrough?: boolean
+  blink?: boolean
   timeoutMs?: number
 }
 
@@ -202,6 +223,40 @@ export interface State {
   text: string
 }
 
+export interface TextMatch {
+  text: string
+  start: TextPosition
+  end: TextPosition
+  spans: Array<TextSpan>
+}
+
+export interface TextPosition {
+  row: number
+  column: number
+}
+
+export interface TextSelectorOptions {
+  regex?: boolean
+  full?: boolean
+  whitespace?: string
+  occurrence?: string
+  nth?: number
+  afterText?: string
+  afterRegex?: boolean
+  afterOccurrence?: string
+  afterNth?: number
+  beforeText?: string
+  beforeRegex?: boolean
+  beforeOccurrence?: string
+  beforeNth?: number
+}
+
+export interface TextSpan {
+  row: number
+  start: number
+  end: number
+}
+
 export interface Timeouts {
   text?: number
   idle?: number