Interface: ResolvedTarget

Interface: ResolvedTarget<D>

@termwright/driver — PTY + VT sessions, locators, actions and waits.

The normative public API lives in api.ts; this module is the only entry point and re-exports the types from there together with their runtime implementations.

Example

import { launchTerminal } from '@termwright/driver';

const terminal = await launchTerminal({ command: ['node', 'app.js'] });
await terminal.waitForText('Ready');
await terminal.getByRole('button', { name: 'Approve' }).activate();
await terminal.close();

Type Parameters

D

D extends LocatorDomain = LocatorDomain

Properties

frameworkType?

readonly optional frameworkType?: string

Defined in: driver/src/api.ts:804

The framework’s own name for the widget, when the node carries one.

Required on generic nodes by the protocol, and the reason a generic node is worth having: without it an unrecognised widget says only “something was here”.

identity

readonly identity: "stable" | "frame-local"

Defined in: driver/src/api.ts:796

Whether a resolved target’s ref means anything after this revision.

'stable' — the identity survives across frames, so the ref can be re-resolved later and locatorForRef works. 'frame-local' — the id is an index into one frame and means nothing in the next; a probe for a framework with no stable identity (Ratatui) says so at handshake time.

Re-resolving a frame-local ref would not answer “did this node change?” but “what holds that number now?”, which is how a passing test ends up asserting about a widget it never selected.

name?

readonly optional name?: string

Defined in: driver/src/api.ts:783

occlusion?

readonly optional occlusion?: "known" | "unknown"

Defined in: driver/src/api.ts:815

Whether the producer could tell what covers these cells.

'known' — paint order was observable, so ResolvedTarget.rect is geometry the user can actually reach. Anything else, absence included, means the rectangle is where the widget asked to draw and something may be on top of it. Pointer actions refuse on anything but 'known'.

provenance?

readonly optional provenance?: "application" | "annotation" | "recognizer" | "framework" | "correlation" | "heuristic"

Defined in: driver/src/api.ts:806

Where this node’s facts came from, when the producer reported it.

rect

readonly rect: Rect | null

Defined in: driver/src/api.ts:781

Rectangle used by the resolution/action pipeline. A semantic target only exposes an evidence-qualified visible rectangle here; intended geometry is never promoted to pointer ownership. Use the locator’s geometry(), visibility(), or hitTest() observations for assertions.

ref

readonly ref: D extends "semantic" ? `semantic:${string}@${number}` : `screen:${number},${number},${number},${number}@${number}`

Defined in: driver/src/api.ts:772

Explicitly domain-tagged, revision-bound identity.

revision

readonly revision: number

Defined in: driver/src/api.ts:773

role?

readonly optional role?: "application" | "region" | "dialog" | "alert" | "status" | "list" | "listitem" | "menu" | "menuitem" | "button" | "checkbox" | "radio" | "tab" | "textbox" | "heading" | "text" | "progressbar" | "separator" | "scrollbar" | "table" | "row" | "cell" | "generic"

Defined in: driver/src/api.ts:782

semantic

readonly semantic: boolean

Defined in: driver/src/api.ts:774