silvery 0.21.0 → 0.23.0

package/dist/test.d.mts

@@ -0,0 +1,673 @@
+import { F as TerminalCaps, Z as ColorScheme, ht as Theme } from "./index-377zdPLP.mjs";
+import { $ as bufferToHTML, Qt as CODE_TO_KEY, S as Term, Y as Cell, Z as TerminalBuffer, _ as BoundTerm, an as keyToKittyAnsi, et as bufferToStyledText, ht as AgNode, in as keyToAnsi, jt as Rect, nt as FrameCell, rt as TextFrame, tt as bufferToText } from "./mouse-events-B2z5tbsL.mjs";
+import { Bt as App, Gt as LayoutShift, Ht as FilterOptions, It as LayoutEngine, Kt as ReasonClassifier, Ut as createAutoLocator, Vt as AutoLocator, Wt as CLSReport, hr as stripAnsi, qt as ReflowReason } from "./wrap-measurer-registration-IV2HtcCd.mjs";
+import React, { ReactElement } from "react";
+
+//#region packages/ag-term/src/strict-cls.d.ts
+/** SILVERY_STRICT slug for the CLS check. Tier 2 by design. */
+declare const CLS_STRICT_SLUG = "cls";
+declare const CLS_STRICT_MIN_TIER = 2;
+/** Returns true when SILVERY_STRICT=cls (or =2 / =3 / etc.) is enabled. */
+declare function isClsStrictEnabled(): boolean;
+/**
+ * Thrown when SILVERY_STRICT=cls is enabled and a capture window saw at
+ * least one shift with reflowReason="unexpected".
+ *
+ * Carries the offending shifts AND the cumulative unexpected-only score
+ * so failing tests can point at the worst offenders without rerunning.
+ * `.message` is human-readable; `.shifts` + `.score` are for programmatic
+ * inspection.
+ */
+declare class UnexpectedLayoutShiftError extends Error {
+  readonly shifts: readonly LayoutShift[];
+  readonly score: number;
+  constructor(shifts: readonly LayoutShift[], score: number);
+}
+//#endregion
+//#region packages/test/src/debug.d.ts
+interface DebugTreeOptions {
+  /** Maximum depth to traverse (default: unlimited) */
+  depth?: number;
+  /** Include layout rectangles (default: true) */
+  showRects?: boolean;
+  /** Include text content (default: true) */
+  showText?: boolean;
+}
+/**
+ * Pretty-print SilveryNode tree for debugging.
+ *
+ * @param node - Root node to inspect
+ * @param options - Display options
+ * @returns Formatted tree string
+ */
+declare function debugTree(node: AgNode, options?: DebugTreeOptions): string;
+//#endregion
+//#region packages/test/src/diagnostic-theme.d.ts
+/**
+ * Maximally-distinct ColorScheme for diagnostic rendering tests.
+ *
+ * Pure black canvas, pure white fg, saturated ANSI primaries. Every derived
+ * token gets a unique visible RGB.
+ */
+declare const diagnosticScheme: ColorScheme;
+/**
+ * Pre-derived diagnostic theme. Pass to `createRenderer({ theme })` or
+ * `testBoard({ theme })` for pipeline regression coverage.
+ */
+declare const diagnosticTheme: Theme;
+//#endregion
+//#region packages/test/src/compare-buffers.d.ts
+/**
+ * A single cell mismatch between two buffers.
+ */
+interface BufferMismatch {
+  /** Column of the mismatched cell */
+  x: number;
+  /** Row of the mismatched cell */
+  y: number;
+  /** Cell from buffer A (e.g., incremental render) */
+  cellA: Cell;
+  /** Cell from buffer B (e.g., fresh render) */
+  cellB: Cell;
+}
+/**
+ * Compare two terminal buffers cell-by-cell.
+ *
+ * @returns The first mismatch found, or null if buffers are identical.
+ */
+declare function compareBuffers(a: TerminalBuffer, b: TerminalBuffer): BufferMismatch | null;
+/**
+ * Format a buffer mismatch for human-readable error output.
+ */
+declare function formatMismatch(mismatch: BufferMismatch, context?: {
+  incrementalText?: string;
+  freshText?: string;
+  seed?: number;
+  iteration?: number;
+  key?: string;
+}): string;
+//#endregion
+//#region packages/test/src/cell-inspector.d.ts
+interface TestCellSnapshot extends Cell {
+  readonly x: number;
+  readonly y: number;
+  readonly selectable: boolean;
+}
+declare function readCellSnapshot(buffer: TerminalBuffer, x: number, y: number): TestCellSnapshot;
+declare function readCellRow(buffer: TerminalBuffer, y: number): TestCellSnapshot[];
+declare function formatSelectableCells(buffer: TerminalBuffer): string;
+//#endregion
+//#region packages/test/src/frame-recorder.d.ts
+/**
+ * A single cell change between two frames at the same (col, row).
+ *
+ * `from` and `to` are the cell states in the "before" and "after" frames.
+ * Both are always present — to detect appearance/disappearance, compare
+ * `char`, `fg`, or `bg` against the blank-cell defaults.
+ */
+interface CellChange {
+  readonly col: number;
+  readonly row: number;
+  readonly from: FrameCell;
+  readonly to: FrameCell;
+}
+/**
+ * A predicate over three consecutive frames. Returns true when the cell at
+ * some coordinate changes in frame B and reverts in frame C — the signature
+ * of a 1-frame transient flicker.
+ */
+type TransientPredicate = (a: TextFrame, b: TextFrame, c: TextFrame) => boolean;
+/**
+ * A live recording of rendered frames.
+ *
+ * `frames` is an append-only array of immutable TextFrame snapshots. Each
+ * entry captures the terminal state after one render pass. Subsequent renders
+ * push new entries without mutating existing ones, so tests can safely iterate
+ * and diff across history.
+ */
+interface FrameRecording {
+  /** All captured frames, in render order. */
+  readonly frames: readonly TextFrame[];
+  /** Convenience: `frames.length`. */
+  readonly count: number;
+  /**
+   * Cells that differ between frames `i` and `j`. Returns an empty array when
+   * the frames are identical. Size mismatches (frames captured at different
+   * terminal dimensions) are diffed over the intersection.
+   */
+  diff(i: number, j: number): CellChange[];
+  /**
+   * Scan every 3-frame window for transient changes. Returns true when the
+   * predicate fires on any `(frames[i], frames[i+1], frames[i+2])` triple.
+   *
+   * A transient change is a cell that changes in one frame and reverts in the
+   * next — the visual signature of a flicker, stale overlay, or one-frame
+   * paint bug.
+   */
+  hasTransientChange(predicate: TransientPredicate): boolean;
+  /** Clear all recorded frames. Useful between test phases. */
+  clear(): void;
+  /** Stop recording. Frames already captured remain accessible. */
+  stop(): void;
+}
+/**
+ * A handle-like object that exposes a Term. Accepted by `recordFrames()` in
+ * addition to a bare Term.
+ */
+interface FrameRecordable {
+  readonly term: Term;
+}
+/**
+ * Start recording frames from a Term (or any object exposing `.term`).
+ *
+ * The recorder observes the emulator's ANSI feed so that every render patch
+ * triggers a fresh TextFrame snapshot. Only calls made AFTER `recordFrames()`
+ * returns are captured — the initial render is not retroactively recorded.
+ * Call `recording.stop()` to end recording early.
+ *
+ * For emulator-backed terms created via `createTermless()`, snapshots reflect
+ * the real terminal state including resolved colors and wide characters. For
+ * other Term types, this function throws — cell-level recording requires an
+ * emulator.
+ */
+declare function recordFrames(target: Term | FrameRecordable): FrameRecording;
+//#endregion
+//#region packages/ag-term/src/renderer.d.ts
+/**
+ * Options for headless render (no terminal).
+ */
+interface RenderOptions {
+  /** Terminal width for layout. Default: 80 */
+  cols?: number;
+  /** Terminal height for layout. Default: 24 */
+  rows?: number;
+  /** Layout engine to use. Default: current global engine */
+  layoutEngine?: LayoutEngine;
+  /** Enable debug output. Default: false */
+  debug?: boolean;
+  /** Enable incremental rendering. Default: true */
+  incremental?: boolean;
+  /** Use Kitty keyboard protocol encoding for press(). When true, press() uses keyToKittyAnsi. */
+  kittyMode?: boolean;
+  /**
+   * Handle Tab / Shift+Tab as focus-cycling keystrokes in `sendInput`/`press`.
+   * When `false`, Tab and Shift+Tab reach `useInput` instead of being consumed
+   * by the focus manager — matching the production `run()` option of the same
+   * name (Claude-Code-style "Shift+Tab cycles permission mode" apps).
+   *
+   * Default: true.
+   */
+  handleTabCycling?: boolean;
+  /**
+   * Maximum layout-pass iterations per render. Each pass: runPipeline +
+   * flushSyncWork. Loop exits when no React commit happens (converged) or
+   * when the cap is reached.
+   *
+   * Default: `MAX_CONVERGENCE_PASSES` (2 — production-derived structural
+   * bound: 1 initial + 1 settle for measurement feedback).
+   *
+   * Tests that depend on multi-iteration stabilization (e.g. legacy
+   * scrollable-list virtualization that previously relied on the classic
+   * 5-iteration loop) can opt into a higher cap via `maxLayoutPasses: 5`.
+   *
+   * See pass-cause.ts:MAX_CONVERGENCE_PASSES for the structural derivation
+   * and bead `@km/silvery/renderer-convergence-by-design` for the convergence
+   * theorem.
+   */
+  maxLayoutPasses?: number;
+  /**
+   * Auto-render on async React commits (e.g., setTimeout → setState).
+   *
+   * When true, the renderer schedules a microtask re-render whenever React
+   * commits new work outside of explicit render/sendInput/rerender calls.
+   * This enables test components with async state updates to produce new
+   * frames automatically.
+   *
+   * Default: false (renderer only renders on explicit triggers).
+   */
+  autoRender?: boolean;
+  /**
+   * Callback fired after each frame render.
+   *
+   * Called with the frame output string and the underlying TerminalBuffer.
+   * Fires after initial render, sendInput, rerender, and (if autoRender)
+   * async state changes.
+   */
+  onFrame?: (frame: string, buffer: TerminalBuffer, contentHeight?: number) => void;
+  /**
+   * Callback fired after each pipeline execution, before React effects flush.
+   *
+   * Called inside act() after runPipeline produces the buffer but before
+   * useLayoutEffect/useEffect callbacks run. Use this to make pipeline output
+   * available to effects (e.g., Ink compat debug mode where useStdout().write()
+   * needs to replay the latest frame).
+   */
+  onBufferReady?: (frame: string, buffer: TerminalBuffer, contentHeight?: number) => void;
+  /**
+   * Wrap the root element with additional providers.
+   * Called with the element after silvery's internal contexts are applied.
+   * Use this to inject additional context providers (e.g., Ink compatibility wrappers).
+   * The wrapper is applied INSIDE silvery's contexts, so wrapped providers
+   * can access silvery's Term, Stdout, FocusManager, and Runtime contexts.
+   */
+  wrapRoot?: (element: React.ReactElement) => React.ReactElement;
+  /**
+   * External stdin stream to bridge to the renderer's input.
+   * When provided, readable data from this stream is forwarded to the renderer's
+   * input handler (equivalent to calling app.stdin.write()).
+   */
+  stdin?: NodeJS.ReadStream;
+}
+/**
+ * Store — the TermDef-like environment for render().
+ * Provides cols, rows, and optionally an event stream for interactive mode.
+ */
+interface Store {
+  /** Terminal columns */
+  readonly cols: number;
+  /** Terminal rows */
+  readonly rows: number;
+  /** Async event stream (if present, enables interactive mode) */
+  events?(): AsyncIterable<StoreEvent>;
+}
+/**
+ * Event from a store's event stream.
+ */
+interface StoreEvent {
+  type: string;
+  data: unknown;
+}
+/**
+ * Provider options for createStore().
+ */
+interface StoreOptions {
+  /** Terminal columns. Default: 80 */
+  cols?: number;
+  /** Terminal rows. Default: 24 */
+  rows?: number;
+  /** Event source for interactive mode */
+  events?: AsyncIterable<StoreEvent>;
+}
+/**
+ * Ensure layout engine is initialized (async, cached).
+ */
+declare function ensureEngine(): Promise<void>;
+/**
+ * Render a React element synchronously. Returns a full App with locators,
+ * press(), text, ansi, etc.
+ *
+ * Layout engine must be initialized before calling (use ensureEngine() or
+ * the top-level await in testing module).
+ *
+ * Overloads:
+ * - render(element, { cols, rows }) — headless with dimensions
+ * - render(element, store) — with a Store from createStore()
+ *
+ * @example
+ * ```tsx
+ * const app = render(<Counter />, { cols: 80, rows: 24 })
+ * expect(app.text).toContain('Count: 0')
+ * await app.press('j')
+ * expect(app.text).toContain('Count: 1')
+ * ```
+ */
+declare function render(element: ReactElement, optsOrStore?: RenderOptions | Store): App;
+/**
+ * Create a Store from provider options.
+ *
+ * A Store is the TermDef-like environment: cols, rows, and optionally events.
+ *
+ * @example
+ * ```tsx
+ * const store = createStore({ cols: 80, rows: 24 })
+ * const app = render(<App />, store)
+ * ```
+ */
+declare function createStore(options?: StoreOptions): Store;
+/**
+ * Per-render overrides for createRenderer's returned function.
+ */
+interface PerRenderOptions {
+  /** Enable incremental rendering for this render. */
+  incremental?: boolean;
+  /** Max layout-pass iterations per render. See RenderOptions.maxLayoutPasses. */
+  maxLayoutPasses?: number;
+  /** Use Kitty keyboard protocol encoding for press(). */
+  kittyMode?: boolean;
+}
+/**
+ * Create a render function that auto-cleans previous renders.
+ *
+ * By default, incremental rendering is ENABLED for test renders.
+ * This matches production behavior (live scheduler uses incremental)
+ * and enables withDiagnostics to catch incremental vs fresh mismatches.
+ *
+ * **Instance reuse:** When the same renderer is called repeatedly with a
+ * compatible element (no overrides that would require fresh state), the
+ * returned function calls `current.rerender(element)` instead of
+ * unmount+remount. This avoids paying the full React reconciler init +
+ * fiberRoot creation cost on each iteration — which otherwise dominates
+ * cold-render microbenchmarks. See bead `km-silvery.renderer-reuse`.
+ *
+ * Reuse is skipped (forcing fresh mount) when:
+ * - The previous instance has been unmounted (rerender would throw)
+ * - Per-render overrides are supplied that conflict with baseOpts
+ *   (e.g., flipping `incremental`, `maxLayoutPasses`, or `kittyMode`)
+ * - The base options are a Store (store-mode renders manage their own
+ *   lifecycle and we conservatively force a fresh mount)
+ *
+ * @example
+ * ```tsx
+ * const render = createRenderer({ cols: 80, rows: 24 })
+ * const app1 = render(<Foo />)  // fresh mount
+ * const app2 = render(<Bar />)  // reuses app1 via rerender()
+ * // app1 === app2 when reuse kicks in
+ *
+ * // Explicitly disable incremental if needed
+ * const render2 = createRenderer({ cols: 80, rows: 24, incremental: false })
+ * ```
+ */
+declare function createRenderer(optsOrStore?: RenderOptions | Store): (el: ReactElement, overrides?: PerRenderOptions) => App;
+/**
+ * Result of run() with sync events — iterable over events.
+ */
+interface SyncRunResult extends Iterable<string> {
+  /** Current rendered text */
+  readonly text: string;
+  /** The app being driven */
+  readonly app: App;
+}
+/**
+ * Result of run() with async events — async iterable and awaitable.
+ */
+interface AsyncRunResult extends AsyncIterable<string>, PromiseLike<void> {
+  /** Current rendered text */
+  readonly text: string;
+  /** The app being driven */
+  readonly app: App;
+  /** Unmount and stop the event loop */
+  unmount(): void;
+}
+/**
+ * Drive an App with events.
+ *
+ * - `run(app, ['j', 'k', 'Enter'])` — sync, explicit key events
+ * - `run(app, syncIterable)` — sync iteration over events
+ * - `await run(app)` — async, reads events from store (if rendered with one)
+ * - `for await (const text of run(app, asyncEvents))` — async iteration
+ *
+ * @example
+ * ```tsx
+ * const app = render(<Counter />, { cols: 80, rows: 24 })
+ * run(app, ['j', 'k', 'Enter'])
+ * expect(app.text).toContain('Count: 2')
+ * ```
+ */
+declare function run(app: App, events: string[]): SyncRunResult;
+declare function run(app: App, events: Iterable<string>): SyncRunResult;
+declare function run(app: App, events?: AsyncIterable<string>): AsyncRunResult;
+/**
+ * Get the number of currently active (mounted) render instances.
+ * Useful for tests to verify cleanup.
+ */
+declare function getActiveRenderCount(): number;
+//#endregion
+//#region packages/test/src/index.d.ts
+/**
+ * Return the current count of live (un-GC'd) termless Term instances.
+ * Exported for tests that want to assert cleanup happened.
+ */
+declare function getActiveTermlessCount(): number;
+/** Modifier keys for synthetic mouse events (matches termless MouseModifiers). */
+interface TermlessMouseModifiers {
+  ctrl?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+  /** SGR mouse uses the same modifier bit for Meta and Alt. */
+  meta?: boolean;
+}
+/** Options for a mouse event (button + modifiers). */
+interface TermlessMouseOptions extends TermlessMouseModifiers {
+  /** 0=left (default), 1=middle, 2=right */
+  button?: 0 | 1 | 2;
+}
+/** Pixel-coordinate pair, 0-indexed. */
+type TermlessPoint = [x: number, y: number];
+type TermlessMouseCoordinateMode = "auto" | "cell" | "pixel";
+type TermlessWheelDirection = "up" | "down";
+interface TermlessMouseCellSize {
+  width: number;
+  height: number;
+}
+interface TermlessTrackpadFlickPacket {
+  /** Relative delivery time from gesture start. Packets with the same value are one stdin chunk. */
+  atMs: number;
+  /** Number of identical wheel reports in this packet. Preferred spelling for new tests. */
+  count?: number;
+  /** Compatibility alias for older gesture fixtures. */
+  events?: number;
+  /** Wheel delta sign; negative = up, positive = down. Also supplies count when count/events are omitted. */
+  delta?: number;
+  /** Exact SGR wheel button byte for terminal captures: 64 up, 65 down, 66 left, 67 right. */
+  button?: number;
+  /** Direction override for this packet. */
+  direction?: TermlessWheelDirection;
+  /** Cell coordinate override for this packet. */
+  x?: number;
+  /** Cell coordinate override for this packet. */
+  y?: number;
+}
+interface TermlessTrackpadFlickProfile {
+  /** Cell coordinate under the pointer. Pixel mode converts this through cellSize. */
+  x: number;
+  /** Cell coordinate under the pointer. Pixel mode converts this through cellSize. */
+  y: number;
+  direction?: TermlessWheelDirection;
+  /**
+   * Coordinate mode for encoded SGR reports.
+   * - auto: mirror the app's negotiated SGR/SGR-Pixels mode
+   * - cell: force SGR cell coordinates
+   * - pixel: force SGR-Pixels coordinates using cellSize
+   */
+  coordinateMode?: TermlessMouseCoordinateMode;
+  cellSize?: TermlessMouseCellSize;
+  settleMs?: number;
+  packets: readonly TermlessTrackpadFlickPacket[];
+}
+interface TermlessWheelOptions extends TermlessMouseModifiers {
+  /** Horizontal wheel delta. Negative = left, positive = right. */
+  deltaX?: number;
+  /** Vertical wheel delta. Negative = up, positive = down. */
+  deltaY?: number;
+  /** Compatibility alias for vertical wheel delta. */
+  lines?: number;
+  /** Delay between repeated reports. Default: 8ms, matching ~120Hz trackpad cadence. */
+  cadenceMs?: number;
+  /** Coordinate mode for encoded SGR reports. Defaults to auto-detect. */
+  coordinateMode?: TermlessMouseCoordinateMode;
+  cellSize?: TermlessMouseCellSize;
+}
+interface TermlessTrackpadFlickGroup {
+  index: number;
+  atMs: number;
+  packetCount: number;
+  eventCount: number;
+  deltaSum: number;
+}
+interface TermlessTrackpadFlickResult {
+  eventCount: number;
+  durationMs: number;
+  groups: readonly TermlessTrackpadFlickGroup[];
+}
+interface TermlessTrackpadFlickDebugLogOptions {
+  /** Default: "pixel" when SGR-Pixels cell size can be inferred, otherwise "cell". */
+  coordinateMode?: TermlessMouseCoordinateMode;
+  /** Override inferred cell size for SGR-Pixels logs. */
+  cellSize?: TermlessMouseCellSize;
+  /** Override profile x. Defaults to first parsed wheel event x. */
+  x?: number;
+  /** Override profile y. Defaults to first parsed wheel event y. */
+  y?: number;
+}
+declare function parseTermlessTrackpadFlickProfileFromDebugLog(logText: string, options?: TermlessTrackpadFlickDebugLogOptions): TermlessTrackpadFlickProfile;
+interface TermlessTrackpadFlickOptions {
+  /** Called after each timed stdin chunk is delivered and the event loop yields once. */
+  afterGroup?: (group: TermlessTrackpadFlickGroup) => void | Promise<void>;
+}
+interface TermlessMouse {
+  /** Fire a mousedown (press only — no release). */
+  down(x: number, y: number, options?: TermlessMouseOptions): Promise<void>;
+  /** Fire a mouseup (release only — no press). */
+  up(x: number, y: number, options?: TermlessMouseOptions): Promise<void>;
+  /** Fire a mouse move to (x,y). Stateless — no press implied. */
+  move(x: number, y: number, options?: TermlessMouseOptions): Promise<void>;
+  /** Down then up at the same coordinate — a plain click, no drag. */
+  click(x: number, y: number, options?: TermlessMouseOptions): Promise<void>;
+  /** Two consecutive clicks at the same coordinate. */
+  dblclick(x: number, y: number, options?: TermlessMouseOptions): Promise<void>;
+  /**
+   * Drag from one cell to another with N intermediate moves. Dispatches
+   * `down(from)` → `move(...via)` → `move(to)` → `up(to)`. Waits briefly
+   * between steps so the event loop can process each before the next.
+   *
+   * @example drag(from: [5, 2], to: [20, 2]) // simple drag
+   * @example drag(from: [10, 0], to: [5, 0], via: [[20, 0]]) // forward then shrink back
+   */
+  drag(opts: {
+    from: TermlessPoint;
+    to: TermlessPoint;
+    via?: TermlessPoint[];
+    options?: TermlessMouseOptions; /** ms between dispatch steps. Default: 20 */
+    stepDelay?: number;
+  }): Promise<void>;
+  /** Fire mouse wheel events at (x,y). Positive vertical delta = scroll down. */
+  wheel(x: number, y: number, deltaOrOptions: number | TermlessWheelOptions, options?: TermlessWheelOptions): Promise<void>;
+  /**
+   * Replay a real trackpad-style wheel gesture: timestamped packet groups,
+   * optional SGR-Pixels coordinates, and many wheel reports in one stdin chunk.
+   */
+  trackpadFlick(profile: TermlessTrackpadFlickProfile, options?: TermlessTrackpadFlickOptions): Promise<TermlessTrackpadFlickResult>;
+}
+/** OSC 52 clipboard capture — every clipboard write during the Term's life. */
+interface TermlessClipboard {
+  /** Last OSC 52 payload captured, or null if none. */
+  readonly last: string | null;
+  /** All OSC 52 payloads captured, in order. */
+  readonly all: readonly string[];
+  /** Drop all captured payloads (useful between test phases). */
+  clear(): void;
+}
+interface TermlessOutput {
+  getText(): string;
+  getChunks(): readonly string[];
+  containsOutput(text: string): boolean;
+  clear(): void;
+}
+interface TermlessReflowResidue {
+  /** Visible marker injected by the residue simulator when an app repaints without ED2. */
+  readonly marker: string;
+  /**
+   * Arm the residue simulator for the next terminal write. Resizes arm this
+   * automatically; call this to model cmux workspace/alt-screen restoration
+   * that reflows the terminal without changing dimensions.
+   */
+  arm(): void;
+  /** Disarm the simulator without requiring a clear. */
+  clear(): void;
+  /** Whether the next non-clearing write will inject the marker. */
+  readonly armed: boolean;
+}
+/**
+ * Term augmented with mouse + clipboard test helpers.
+ *
+ * `createTermless()` always returns an emulator-backed term, so `screen`,
+ * `scrollback`, and `cell()` are guaranteed defined here (the `Term`
+ * interface marks them optional because non-emulator-backed Terms — Node
+ * stdout, headless — don't have them). Narrowing them to required removes
+ * the need for `!` non-null assertions at every test callsite.
+ */
+interface TermlessTerm extends Term {
+  readonly mouse: TermlessMouse;
+  readonly clipboard: TermlessClipboard;
+  readonly out: TermlessOutput;
+  readonly reflowResidue?: TermlessReflowResidue;
+  readonly screen: NonNullable<Term["screen"]>;
+  readonly scrollback: NonNullable<Term["scrollback"]>;
+  cell(row: number, col: number): {
+    readonly fg: unknown;
+    readonly bg: unknown;
+    readonly char: string;
+  };
+}
+type TermlessBackendChoice = "xterm" | "ghostty" | "ghostty-native";
+/**
+ * Create a Term backed by a termless xterm.js emulator for full ANSI testing.
+ *
+ * Convenience wrapper around `createTerm(createXtermBackend(), dims)` that
+ * handles the xterm.js backend import. Use with `run()` to render components
+ * into a real terminal emulator in-process — no PTY, no timing issues.
+ *
+ * The returned Term exposes two testing conveniences:
+ * - `term.mouse.*` — ergonomic mouse API (click, drag, down/up/move, wheel)
+ * - `term.clipboard` — OSC 52 capture (`term.clipboard.last`, `.all`)
+ *
+ * **Always dispose with `using` or an explicit `term[Symbol.dispose]()`.**
+ * Without disposal, each call leaks the xterm.js Terminal (~1 MB scrollback
+ * per instance). This accumulated to 18-28 GB per vitest worker in CI before
+ * `km-silvery.termless-memleak` was fixed.
+ *
+ * @example Mouse drag + clipboard capture
+ * ```tsx
+ * using term = createTermless({ cols: 40, rows: 10 })
+ * const handle = await run(<App />, term, { selection: true, mouse: true })
+ *
+ * await term.mouse.drag({ from: [5, 2], to: [20, 2] })
+ * expect(term.clipboard.last).toContain("selected text")
+ * ```
+ *
+ * @example Plain click
+ * ```tsx
+ * await term.mouse.click(10, 5)
+ * await term.mouse.click(10, 5, { shift: true })
+ * ```
+ *
+ * @example Override capabilities (defaults-contract tests)
+ * ```tsx
+ * using term = createTermless({ cols: 80, rows: 24, caps: { colorLevel: '256' } })
+ * ```
+ *
+ * Without a `caps` override, `term.caps` is populated from `defaultCaps()`
+ * (truecolor / unicode / mouse). Callers that want a specific terminal
+ * profile for a test — Apple_Terminal's lack of `maybeWideEmojis`, Kitty's
+ * `kittyKeyboard`, etc. — can pass a `Partial<TerminalCaps>` here.
+ */
+declare function createTermless(dims?: {
+  cols: number;
+  rows: number;
+  caps?: Partial<TerminalCaps>;
+  backend?: TermlessBackendChoice;
+  reflowResidue?: boolean | {
+    marker?: string;
+  };
+}): TermlessTerm;
+/**
+ * Normalize frame output for comparison.
+ * - Strips ANSI codes
+ * - Trims trailing whitespace from lines
+ * - Removes empty trailing lines
+ */
+declare function normalizeFrame(frame: string): string;
+/**
+ * Wait for a condition to be true, polling at intervals.
+ * Useful for waiting for async state updates.
+ */
+declare function waitFor(condition: () => boolean, {
+  timeout,
+  interval
+}?: {
+  timeout?: number | undefined;
+  interval?: number | undefined;
+}): Promise<void>;
+//#endregion
+export { type App, type AutoLocator, type BoundTerm, type BufferMismatch, type CLSReport, CLS_STRICT_MIN_TIER, CLS_STRICT_SLUG, CODE_TO_KEY, type CellChange, type DebugTreeOptions, type FilterOptions, type FrameRecordable, type FrameRecording, type LayoutShift, type PerRenderOptions, type ReasonClassifier, type Rect, type ReflowReason, type RenderOptions, type Store, type StoreOptions, type TerminalBuffer, TermlessClipboard, TermlessMouse, TermlessMouseCellSize, TermlessMouseCoordinateMode, TermlessMouseModifiers, TermlessMouseOptions, TermlessOutput, TermlessPoint, TermlessReflowResidue, TermlessTerm, TermlessTrackpadFlickDebugLogOptions, TermlessTrackpadFlickGroup, TermlessTrackpadFlickOptions, TermlessTrackpadFlickPacket, TermlessTrackpadFlickProfile, TermlessTrackpadFlickResult, TermlessWheelDirection, TermlessWheelOptions, type TestCellSnapshot, type TransientPredicate, UnexpectedLayoutShiftError, bufferToHTML, bufferToStyledText, bufferToText, compareBuffers, createAutoLocator, createRenderer, createStore, createTermless, debugTree, diagnosticScheme, diagnosticTheme, ensureEngine, formatMismatch, formatSelectableCells, getActiveRenderCount, getActiveTermlessCount, isClsStrictEnabled, keyToAnsi, keyToKittyAnsi, normalizeFrame, parseTermlessTrackpadFlickProfileFromDebugLog, readCellRow, readCellSnapshot, recordFrames, render, run, stripAnsi, waitFor };
+//# sourceMappingURL=test.d.mts.map

package/dist/test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.mts","names":[],"sources":["../packages/ag-term/src/strict-cls.ts","../packages/test/src/debug.ts","../packages/test/src/diagnostic-theme.ts","../packages/test/src/compare-buffers.ts","../packages/test/src/cell-inspector.ts","../packages/test/src/frame-recorder.ts","../packages/ag-term/src/renderer.ts","../packages/test/src/index.tsx"],"mappings":"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"}