@oniroproject/core 0.12.0 → 0.13.0

package/README.md

@@ -206,17 +206,23 @@ The injection-safe primitives every device operation builds on (`spawn` with `sh
 | `takeScreenshot` | `(ScreenshotOptions) => Promise<Screenshot>` | `{ pixels: Buffer, width, height }` — raw JPEG, no decode. |
 | `captureBurst` | `(CaptureBurstOptions) => Promise<Buffer[]>` | N frames `intervalMs` apart, pulled back in order. |
 | `getDisplaySize` | `(config, opts?) => Promise<DisplaySize \| null>` | Render resolution from `hidumper` (no image work). |
-| `dumpLayout` | `(DumpLayoutOptions) => Promise<DumpLayoutResult>` | `uitest dumpLayout` → pruned, 0–1-normalized `LayoutNode` tree. |
-| `parseBounds` / `pruneLayout` | — | Pure helpers behind `dumpLayout`. |
+| `dumpLayout` | `(DumpLayoutOptions) => Promise<DumpLayoutResult>` | `uitest dumpLayout` → pruned, 0–1-normalized `LayoutNode` tree, with `hint`, `disabled`, and `covered` (painted over by a later filled layer). `detectKeyboard` adds `keyboard: KeyboardState`. |
+| `parseBounds` / `pruneLayout` / `findCoveredNodes` | — | Pure helpers behind `dumpLayout`. |
+| `flattenLayout` / `findLayoutNodes` / `pickTarget` | — | Pure: flatten a tree (nodes tagged with their `window`), match a `LayoutSelector` (`text` / `id` / `type`), and choose one uncovered, preferably clickable node (throws `TargetNotFoundError` with `reason` `none` / `covered` / `ambiguous`). |
+| `getImeBundles` / `parseImeBundles` / `findKeyboardWindow` | — | Installed input methods (`hidumper -s 3703`) and the soft-keyboard window in a layout. |
 
 ### hdc — input injection
 
 | Export | Signature | Description |
 | --- | --- | --- |
-| `sendInput` | `(SendInputOptions) => Promise<void>` | One `uitest uiInput` action in **pixel** space (`InputType`: click/doubleClick/longClick/swipe/drag/fling/keyEvent/inputText). |
+| `sendInput` | `(SendInputOptions) => Promise<void>` | One `uitest uiInput` action in **pixel** space (`InputType`: click/doubleClick/longClick/swipe/drag/fling/keyEvent/inputText). `key` accepts names and combos (see `resolveKeyEvent`). |
+| `performInput` | `(PerformInputOptions) => Promise<PerformInputResult>` | `sendInput` plus a start point from an element selector (`target`), 0–1 fractions, or pixels; `clearText`, `inputText` with `clear`, and keyboard-aware `hideKeyboard`. |
+| `locateTarget` | `(LocateTargetOptions) => Promise<LocatedTarget>` | Resolve a selector against the live layout to one element and its pixel center, dismissing the keyboard if it hides the element. |
+| `hideKeyboard` | `(opts) => Promise<boolean>` | Press Back only when the soft keyboard is shown. |
+| `waitForTarget` | `(WaitForTargetOptions) => Promise<FlatLayoutNode \| null>` | Poll the layout until an uncovered element matches (or, with `gone`, until none does). |
 | `sendGesture` | `(SendGestureOptions) => Promise<void>` | Multi-`Waypoint` path; routes through `uinput` when `holdStartMs`/`holdEndMs` need real press timing. |
 | `sendRawTouch` | `(SendRawTouchOptions) => Promise<void>` | Low-level `uinput -T` down/move/up events. |
-| `buildInputCommand` / `buildGestureCommands` / `buildRawTouchCommand` | — | Pure command builders (unit-testable). |
+| `buildInputCommand` / `buildGestureCommands` / `buildRawTouchCommand` / `resolveKeyEvent` | — | Pure command builders (unit-testable). |
 
 ### hdc — logging (hilog)
 

package/dist/index.cjs

@@ -47,9 +47,11 @@ __export(index_exports, {
   SIGNING_ERRORS: () => SIGNING_ERRORS,
   SdkNotInstalledError: () => SdkNotInstalledError,
   TMP_DIR_HINT: () => TMP_DIR_HINT,
+  TargetNotFoundError: () => TargetNotFoundError,
   UnsupportedPlatformError: () => UnsupportedPlatformError,
   VERSION: () => VERSION,
   applyChanges: () => applyChanges,
+  assertLayoutSelector: () => assertLayoutSelector,
   attemptHdcConnection: () => attemptHdcConnection,
   buildCmdWrapper: () => buildCmdWrapper,
   buildGestureCommands: () => buildGestureCommands,
@@ -72,6 +74,7 @@ __export(index_exports, {
   dedupEntries: () => dedupEntries,
   defaultContext: () => defaultContext,
   defaultPaths: () => defaultPaths,
+  describeLayoutNode: () => describeLayoutNode,
   detectAaStartFailure: () => detectAaStartFailure,
   detectProjectSdkVersion: () => detectProjectSdkVersion,
   detectRuntimeOs: () => detectRuntimeOs,
@@ -97,8 +100,12 @@ __export(index_exports, {
   extractZipWithProgress: () => extractZipWithProgress,
   findAppProcessId: () => findAppProcessId,
   findCmdToolsSourceDir: () => findCmdToolsSourceDir,
+  findCoveredNodes: () => findCoveredNodes,
   findHarmonyOsSdk: () => findHarmonyOsSdk,
+  findKeyboardWindow: () => findKeyboardWindow,
+  findLayoutNodes: () => findLayoutNodes,
   findRunningProcess: () => findRunningProcess,
+  flattenLayout: () => flattenLayout,
   forceStop: () => forceStop,
   formatBytes: () => formatBytes,
   generateSigningConfigs: () => generateSigningConfigs,
@@ -113,6 +120,7 @@ __export(index_exports, {
   getFreeSpaceBytes: () => getFreeSpaceBytes,
   getHdcPath: () => getHdcPath,
   getHvigorwPath: () => getHvigorwPath,
+  getImeBundles: () => getImeBundles,
   getInstalledSdks: () => getInstalledSdks,
   getKey: () => getKey,
   getMainAbility: () => getMainAbility,
@@ -125,6 +133,7 @@ __export(index_exports, {
   harmonyOsAutoSign: () => harmonyOsAutoSign,
   harmonyOsSdkLabelForApi: () => harmonyOsSdkLabelForApi,
   hdcExec: () => hdcExec,
+  hideKeyboard: () => hideKeyboard,
   installApp: () => installApp,
   installCmdTools: () => installCmdTools,
   installEmulator: () => installEmulator,
@@ -141,6 +150,7 @@ __export(index_exports, {
   listModules: () => listModules,
   listRunningProcesses: () => listRunningProcesses,
   listTemplates: () => listTemplates,
+  locateTarget: () => locateTarget,
   needsCmdWrapper: () => needsCmdWrapper,
   nonInteractivePrompter: () => nonInteractivePrompter,
   noopLogger: () => noopLogger,
@@ -151,9 +161,12 @@ __export(index_exports, {
   parseCodelinterFindings: () => parseCodelinterFindings,
   parseDeviceList: () => parseDeviceList,
   parseHilogLine: () => parseHilogLine,
+  parseImeBundles: () => parseImeBundles,
   parseMainAbilityFromBmDump: () => parseMainAbilityFromBmDump,
   parseRemoteExit: () => parseRemoteExit,
+  performInput: () => performInput,
   pickSigningKind: () => pickSigningKind,
+  pickTarget: () => pickTarget,
   prepareSigning: () => prepareSigning,
   pruneLayout: () => pruneLayout,
   readJson5File: () => readJson5File,
@@ -166,6 +179,7 @@ __export(index_exports, {
   removeSdk: () => removeSdk,
   removeTempWorkDir: () => removeTempWorkDir,
   requireHarmonyOsSdk: () => requireHarmonyOsSdk,
+  resolveKeyEvent: () => resolveKeyEvent,
   resolveTmpRoot: () => resolveTmpRoot,
   runCodelinter: () => runCodelinter,
   runHvigorw: () => runHvigorw,
@@ -195,8 +209,10 @@ __export(index_exports, {
   waitForBundle: () => waitForBundle,
   waitForCondition: () => waitForCondition,
   waitForLog: () => waitForLog,
+  waitForTarget: () => waitForTarget,
   watchLog: () => watchLog,
   waypointsToRawEvents: () => waypointsToRawEvents,
+  withoutWindow: () => withoutWindow,
   writeJson5File: () => writeJson5File,
   writeJsonFile: () => writeJsonFile
 });
@@ -2619,6 +2635,55 @@ async function captureBurst(opts) {
 }
 
 // src/hdc/input.ts
+var UITEST_KEY_NAMES = ["Back", "Home", "Power"];
+var KEY_IDS = {
+  back: 2,
+  home: 1,
+  power: 18,
+  volumeup: 16,
+  volumedown: 17,
+  up: 2012,
+  down: 2013,
+  left: 2014,
+  right: 2015,
+  alt: 2045,
+  shift: 2047,
+  tab: 2049,
+  space: 2050,
+  enter: 2054,
+  delete: 2055,
+  backspace: 2055,
+  pageup: 2068,
+  pagedown: 2069,
+  escape: 2070,
+  esc: 2070,
+  forwarddelete: 2071,
+  ctrl: 2072,
+  meta: 2076,
+  movehome: 2081,
+  moveend: 2082
+};
+function keyId(name) {
+  const k = name.trim().toLowerCase();
+  if (/^\d+$/.test(k)) return Number(k);
+  if (/^[a-z]$/.test(k)) return 2017 + (k.charCodeAt(0) - 97);
+  const id = KEY_IDS[k];
+  if (id === void 0) {
+    throw new OniroError(
+      `Unknown key "${name}". Use a numeric KeyCode id, a letter, or one of: ${Object.keys(KEY_IDS).join(", ")}. Combine up to three with "+", e.g. Ctrl+A.`
+    );
+  }
+  return id;
+}
+function resolveKeyEvent(key) {
+  const spec = String(key).trim();
+  if (spec === "") throw new OniroError('send input "keyEvent" requires a key.');
+  const native = UITEST_KEY_NAMES.find((n) => n.toLowerCase() === spec.toLowerCase());
+  if (native) return native;
+  const parts = spec.includes("+") ? spec.split("+") : spec.split(/\s+/);
+  if (parts.length > 3) throw new OniroError(`uitest injects at most three keys at once; got "${spec}".`);
+  return parts.map(keyId).join(" ");
+}
 function reqNum(value, name, type) {
   if (value === void 0 || Number.isNaN(value)) {
     throw new OniroError(`send input "${type}" requires a numeric ${name}.`);
@@ -2639,7 +2704,7 @@ function buildInputCommand(opts) {
     }
     case "keyEvent":
       if (opts.key === void 0 || opts.key === "") throw new OniroError('send input "keyEvent" requires a key.');
-      return `uitest uiInput keyEvent ${opts.key}`;
+      return `uitest uiInput keyEvent ${resolveKeyEvent(opts.key)}`;
     case "inputText": {
       const t = String(opts.text ?? "").replace(/'/g, `'\\''`);
       if (opts.pxX !== void 0 && opts.pxY !== void 0) {
@@ -2737,6 +2802,48 @@ var fs20 = __toESM(require("fs"), 1);
 var os10 = __toESM(require("os"), 1);
 var path20 = __toESM(require("path"), 1);
 var import_node_crypto2 = require("crypto");
+
+// src/hdc/ime.ts
+var INPUT_METHOD_SA_ID = 3703;
+var IME_BUNDLE_FALLBACK = /inputmethod|keyboard|(^|\.)ime(\.|$)/i;
+function parseImeBundles(output) {
+  const current = [];
+  const others = [];
+  const entry = /\{[^{}]*"ime"\s*:\s*"([^"/]+)\/[^"]*"[^{}]*\}/g;
+  for (const m of output.matchAll(entry)) {
+    const bundle = m[1];
+    const list = /"isCurrentIme"\s*:\s*"true"/.test(m[0]) ? current : others;
+    if (!current.includes(bundle) && !others.includes(bundle)) list.push(bundle);
+  }
+  return [...current, ...others];
+}
+async function getImeBundles(config, opts = {}) {
+  try {
+    const res = await shell({
+      config,
+      command: `hidumper -s ${INPUT_METHOD_SA_ID} -a '-a'`,
+      deviceSerial: opts.deviceSerial,
+      timeoutMs: 1e4,
+      logger: opts.logger
+    });
+    if (res.code === 0) return parseImeBundles(res.stdout);
+  } catch (err) {
+    opts.logger?.debug(`could not list input methods: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return [];
+}
+function findKeyboardWindow(tree, imeBundles) {
+  const isIme = (bundle) => imeBundles.length > 0 ? imeBundles.includes(bundle) : IME_BUNDLE_FALLBACK.test(bundle);
+  const stack = [tree];
+  while (stack.length > 0) {
+    const n = stack.shift();
+    if (n.bundle && isIme(n.bundle)) return n;
+    stack.push(...n.children ?? []);
+  }
+  return null;
+}
+
+// src/hdc/dump.ts
 function parseBounds(s) {
   const m = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/.exec(s ?? "");
   if (!m) return null;
@@ -2771,7 +2878,46 @@ var FLAG_MAP = [
   ["scrollable", "scroll"],
   ["longClickable", "longClick"]
 ];
-function pruneLayout(node, display) {
+function colorAlpha(color) {
+  const m = /^#([0-9a-f]{2})?[0-9a-f]{6}$/i.exec(color ?? "");
+  if (!m) return 0;
+  return m[1] === void 0 ? 255 : parseInt(m[1], 16);
+}
+function paintsFill(a) {
+  if (a.visible === "false") return false;
+  if (a.opacity !== void 0 && a.opacity !== "" && !(Number(a.opacity) > 0)) return false;
+  return colorAlpha(a.backgroundColor) > 0;
+}
+function findCoveredNodes(root) {
+  const order = [];
+  const fills = [];
+  const visit = (n) => {
+    const a = n.attributes ?? {};
+    const entry = { node: n, bounds: parseBounds(a.bounds), end: 0 };
+    if (entry.bounds && paintsFill(a)) fills.push(order.length);
+    order.push(entry);
+    const kids = (n.children ?? []).map((c, i) => ({ c, i, z: Number(c.attributes?.zIndex) || 0 })).sort((p, q) => p.z - q.z || p.i - q.i);
+    for (const k of kids) visit(k.c);
+    entry.end = order.length;
+  };
+  visit(root);
+  const covered = /* @__PURE__ */ new Set();
+  for (const p of order) {
+    if (!p.bounds) continue;
+    const cx = (p.bounds[0] + p.bounds[2]) / 2;
+    const cy = (p.bounds[1] + p.bounds[3]) / 2;
+    for (const j of fills) {
+      if (j < p.end) continue;
+      const q = order[j].bounds;
+      if (cx >= q[0] && cx < q[2] && cy >= q[1] && cy < q[3]) {
+        covered.add(p.node);
+        break;
+      }
+    }
+  }
+  return covered;
+}
+function pruneLayout(node, display, covered) {
   const a = node.attributes ?? {};
   const px = parseBounds(a.bounds);
   const out = {};
@@ -2789,28 +2935,125 @@ function pruneLayout(node, display) {
   if (a.type && !STRUCTURAL_TYPES.has(a.type)) out.type = a.type;
   if (a.text) out.text = a.text;
   if (a.description) out.desc = a.description;
+  if (a.hint) out.hint = a.hint;
   if (a.id) out.id = a.id;
   if (a.key && a.key !== a.id) out.key = a.key;
   if (a.bundleName) out.bundle = a.bundleName;
   for (const [attr, short] of FLAG_MAP) {
     if (a[attr] === "true") out[short] = true;
   }
+  if (a.enabled === "false") out.disabled = true;
+  if (covered?.has(node)) out.covered = true;
   const children = [];
   for (const c of node.children ?? []) {
-    const pc = pruneLayout(c, display);
+    const pc = pruneLayout(c, display, covered);
     if (pc) {
       if (Array.isArray(pc)) children.push(...pc);
       else children.push(pc);
     }
   }
   const hasSignal = Boolean(
-    out.text || out.desc || out.id || out.key || out.click || out.scroll || out.check || out.longClick || out.bundle || out.type && out.type !== "root"
+    out.text || out.desc || out.hint || out.id || out.key || out.click || out.scroll || out.check || out.longClick || out.bundle || out.type && out.type !== "root"
   );
   if (!hasSignal && children.length === 0) return null;
   if (!hasSignal) return children.length === 1 ? children[0] : children;
   if (children.length) out.children = children;
   return out;
 }
+function flattenLayout(tree) {
+  const out = [];
+  const visit = (n, window) => {
+    const { children, ...rest } = n;
+    const win = n.bundle ?? window;
+    if (Object.keys(rest).length > 0) out.push({ ...rest, ...win ? { window: win } : {} });
+    for (const c of children ?? []) visit(c, win);
+  };
+  visit(tree, void 0);
+  return out;
+}
+function assertLayoutSelector(selector) {
+  if (selector.text === void 0 && selector.id === void 0 && selector.type === void 0) {
+    throw new OniroError("A layout selector needs a text, id, or type.");
+  }
+  if (selector.text !== void 0 && selector.text.trim() === "") {
+    throw new OniroError("A layout selector text must not be blank.");
+  }
+}
+function withoutWindow(tree, bundle) {
+  const children = (tree.children ?? []).filter((c) => c.bundle !== bundle).map((c) => withoutWindow(c, bundle));
+  return tree.children ? { ...tree, children } : tree;
+}
+function findLayoutNodes(tree, selector) {
+  assertLayoutSelector(selector);
+  const type = selector.type?.toLowerCase();
+  const nodes = flattenLayout(tree).filter(
+    (n) => (type === void 0 || n.type?.toLowerCase() === type) && (selector.id === void 0 || n.id === selector.id || n.key === selector.id)
+  );
+  if (selector.text === void 0) return nodes;
+  const want = selector.text.trim().toLowerCase();
+  const labels = (n) => [n.text, n.desc, n.hint].filter((s) => !!s).map((s) => s.trim().toLowerCase());
+  const exact = nodes.filter((n) => labels(n).some((l) => l === want));
+  if (exact.length > 0) return exact;
+  return nodes.filter((n) => labels(n).some((l) => l.includes(want)));
+}
+function describeSelector(s) {
+  const parts = [];
+  if (s.text !== void 0) parts.push(`text "${s.text}"`);
+  if (s.id !== void 0) parts.push(`id "${s.id}"`);
+  if (s.type !== void 0) parts.push(`type ${s.type}`);
+  return parts.join(", ");
+}
+function describeLayoutNode(n) {
+  const label = n.text ?? n.desc ?? (n.hint !== void 0 ? `hint: ${n.hint}` : void 0);
+  const at = n.c ? ` at ${n.c[0].toFixed(3)},${n.c[1].toFixed(3)}` : "";
+  return `${n.type ?? "node"}${label !== void 0 ? ` "${label}"` : ""}${n.id ? ` #${n.id}` : ""}${at}`;
+}
+var area = (b) => b ? (b[2] - b[0]) * (b[3] - b[1]) : 0;
+function enclosesTarget(outer, inner) {
+  const b = outer.b;
+  const c = inner.c;
+  if (!b || !c) return false;
+  return c[0] >= b[0] && c[0] <= b[2] && c[1] >= b[1] && c[1] <= b[3] && area(b) > area(inner.b);
+}
+var TargetNotFoundError = class extends OniroError {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "TargetNotFoundError";
+  }
+  reason;
+};
+function pickTarget(tree, selector, index) {
+  const matches = findLayoutNodes(tree, selector).filter((n) => n.c !== void 0);
+  const what = describeSelector(selector);
+  if (matches.length === 0) {
+    throw new TargetNotFoundError(`No on-screen element matches ${what}. Run \`oniro-app dump layout --flat\` to see what is there.`, "none");
+  }
+  const visible = matches.filter((n) => !n.covered);
+  if (visible.length === 0) {
+    throw new TargetNotFoundError(
+      `Found ${matches.length} element(s) matching ${what}, but each is covered by an overlay (dialog, keyboard, or another layer): ${matches.map(describeLayoutNode).join("; ")}.`,
+      "covered"
+    );
+  }
+  const clickable = visible.filter((n) => n.click);
+  const preferred = clickable.length > 0 ? clickable : visible;
+  const candidates = preferred.filter((n) => !preferred.some((o) => o !== n && o.click && enclosesTarget(o, n)));
+  if (index !== void 0) {
+    const picked = candidates[index];
+    if (!picked) {
+      throw new TargetNotFoundError(`Index ${index} is out of range: ${candidates.length} element(s) match ${what}.`, "ambiguous");
+    }
+    return picked;
+  }
+  if (candidates.length > 1) {
+    throw new TargetNotFoundError(
+      `${candidates.length} elements match ${what}; pass an index to choose: ` + candidates.map((n, i) => `[${i}] ${describeLayoutNode(n)}`).join("; "),
+      "ambiguous"
+    );
+  }
+  return candidates[0];
+}
 async function dumpLayout(opts) {
   const timeoutMs = opts.timeoutMs ?? 3e4;
   const bundleArg = opts.bundleName ? ` -b '${opts.bundleName.replace(/'/g, `'\\''`)}'` : "";
@@ -2828,9 +3071,13 @@ ${dump.stdout}`);
     if (opts.prune === false) {
       return { display, tree: parsed };
     }
-    const prunedRaw = pruneLayout(parsed, display);
+    const prunedRaw = pruneLayout(parsed, display, findCoveredNodes(parsed));
     const tree = Array.isArray(prunedRaw) ? { children: prunedRaw } : prunedRaw ?? { children: [] };
-    return { display, tree };
+    if (!opts.detectKeyboard || opts.bundleName) return { display, tree };
+    const imeBundles = await getImeBundles(opts.config, { deviceSerial: opts.deviceSerial, logger: opts.logger });
+    const kb = findKeyboardWindow(tree, imeBundles);
+    const keyboard = kb ? { shown: true, bundle: kb.bundle, ...kb.b ? { b: kb.b } : {} } : { shown: false };
+    return { display, tree, keyboard };
   } finally {
     fs20.promises.unlink(local).catch(() => {
     });
@@ -2839,6 +3086,161 @@ ${dump.stdout}`);
   }
 }
 
+// src/hdc/uiActions.ts
+var FOCUS_SETTLE_MS = 400;
+var KEYBOARD_SETTLE_MS = 400;
+var sleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
+function targetTree(layout) {
+  const kb = layout.keyboard;
+  return kb?.shown && kb.bundle ? withoutWindow(layout.tree, kb.bundle) : layout.tree;
+}
+function fractionToPixel(f, size) {
+  return Math.min(size - 1, Math.round(f * size));
+}
+function pressBack(opts) {
+  return sendInput({ config: opts.config, type: "keyEvent", key: "Back", deviceSerial: opts.deviceSerial, logger: opts.logger });
+}
+async function hideKeyboard(opts) {
+  const { keyboard } = await dumpLayout({ ...opts, detectKeyboard: true });
+  if (!keyboard?.shown) return false;
+  await pressBack(opts);
+  await sleep(KEYBOARD_SETTLE_MS);
+  return true;
+}
+async function locateTarget(opts) {
+  assertLayoutSelector(opts.selector);
+  const dumpOpts = { config: opts.config, detectKeyboard: true, deviceSerial: opts.deviceSerial, logger: opts.logger };
+  let layout = await dumpLayout(dumpOpts);
+  if (!layout.display) throw new OniroError("Could not read the display size to locate the element.");
+  let keyboardHidden = false;
+  let node;
+  let failure;
+  try {
+    node = pickTarget(targetTree(layout), opts.selector, opts.index);
+  } catch (err) {
+    if (!(err instanceof TargetNotFoundError) || err.reason === "ambiguous") throw err;
+    failure = err;
+  }
+  if ((!node || !node.click) && layout.keyboard?.shown && opts.hideKeyboard !== false) {
+    opts.logger?.debug("target not reachable while the keyboard is up; dismissing it and looking again");
+    await pressBack(opts);
+    await sleep(KEYBOARD_SETTLE_MS);
+    keyboardHidden = true;
+    layout = await dumpLayout(dumpOpts);
+    if (!layout.display) throw new OniroError("Could not read the display size to locate the element.");
+    node = pickTarget(targetTree(layout), opts.selector, opts.index);
+  }
+  if (!node) throw failure;
+  if (!node.c) throw new OniroError("The element has no on-screen position.");
+  const x2 = fractionToPixel(node.c[0], layout.display.width);
+  const y = fractionToPixel(node.c[1], layout.display.height);
+  return { node, x: x2, y, display: layout.display, keyboardHidden };
+}
+function fraction(value, name) {
+  if (value === void 0) return void 0;
+  if (!(value >= 0 && value <= 1)) throw new OniroError(`${name} must be a fraction between 0 and 1; got ${value}.`);
+  return value;
+}
+function pair(a, b, names) {
+  if (a === void 0 && b === void 0) return void 0;
+  if (a === void 0 || b === void 0) throw new OniroError(`Give both ${names}.`);
+  return [a, b];
+}
+async function performInput(opts) {
+  const device = { config: opts.config, deviceSerial: opts.deviceSerial, logger: opts.logger };
+  const startFx = pair(fraction(opts.fx, "--fx"), fraction(opts.fy, "--fy"), "--fx and --fy");
+  const startPx = pair(opts.pxX, opts.pxY, "--x and --y");
+  const endFx = pair(fraction(opts.fx2, "--fx2"), fraction(opts.fy2, "--fy2"), "--fx2 and --fy2");
+  const endPx = pair(opts.pxX2, opts.pxY2, "--x2 and --y2");
+  if ([opts.target, startFx, startPx].filter((s) => s !== void 0).length > 1) {
+    throw new OniroError("Give the start point one way: a target, fractions (--fx/--fy), or pixels (--x/--y).");
+  }
+  if (endFx && endPx) throw new OniroError("Give the end point one way: fractions (--fx2/--fy2) or pixels (--x2/--y2).");
+  let display;
+  const toPx = async ([fx, fy]) => {
+    display ??= await getDisplaySize(opts.config, { deviceSerial: opts.deviceSerial, logger: opts.logger });
+    if (!display) throw new OniroError("Could not read the display size to convert fractions to pixels.");
+    return [fractionToPixel(fx, display.width), fractionToPixel(fy, display.height)];
+  };
+  const result = { keyboardHidden: false };
+  let start = startPx;
+  if (opts.target) {
+    const located = await locateTarget({ ...device, selector: opts.target, index: opts.targetIndex });
+    display = located.display;
+    start = [located.x, located.y];
+    result.target = located.node;
+    result.keyboardHidden = located.keyboardHidden;
+  } else if (startFx) {
+    start = await toPx(startFx);
+  }
+  const end = endFx ? await toPx(endFx) : endPx;
+  if (start) [result.x, result.y] = start;
+  const tapToFocus = async () => {
+    if (!start) return;
+    await sendInput({ ...device, type: "click", pxX: start[0], pxY: start[1] });
+    await sleep(FOCUS_SETTLE_MS);
+  };
+  const clearFocused = async () => {
+    await sendInput({ ...device, type: "keyEvent", key: "Ctrl+A" });
+    await sendInput({ ...device, type: "keyEvent", key: "Delete" });
+  };
+  switch (opts.type) {
+    case "hideKeyboard":
+      result.keyboardHidden = await hideKeyboard(device) || result.keyboardHidden;
+      return result;
+    case "clearText":
+      await tapToFocus();
+      await clearFocused();
+      break;
+    case "inputText":
+      if (opts.clear) {
+        await tapToFocus();
+        await clearFocused();
+        await sendInput({ ...device, type: "inputText", text: opts.text });
+      } else {
+        await sendInput({ ...device, type: "inputText", pxX: start?.[0], pxY: start?.[1], text: opts.text });
+      }
+      break;
+    default:
+      await sendInput({
+        ...device,
+        type: opts.type,
+        pxX: start?.[0],
+        pxY: start?.[1],
+        pxX2: end?.[0],
+        pxY2: end?.[1],
+        speed: opts.speed,
+        key: opts.key,
+        text: opts.text
+      });
+  }
+  if (opts.hideKeyboard) result.keyboardHidden = await hideKeyboard(device) || result.keyboardHidden;
+  return result;
+}
+async function waitForTarget(opts) {
+  const { selector } = opts;
+  assertLayoutSelector(selector);
+  let found = null;
+  await waitForCondition({
+    probe: async () => {
+      const layout = await dumpLayout({
+        config: opts.config,
+        detectKeyboard: true,
+        deviceSerial: opts.deviceSerial,
+        logger: opts.logger
+      });
+      found = findLayoutNodes(targetTree(layout), selector).find((n) => !n.covered) ?? null;
+      return opts.gone ? found === null : found !== null;
+    },
+    timeoutMs: opts.timeoutMs,
+    pollMs: opts.pollMs ?? 500,
+    abortSignal: opts.abortSignal,
+    logger: opts.logger,
+    timeoutMessage: opts.gone ? `An element matching the selector was still on screen after ${opts.timeoutMs}ms.` : `No element matching the selector appeared within ${opts.timeoutMs}ms.`
+  });
+  return opts.gone ? null : found;
+}
+
 // src/hdc/hilog.ts
 function setHilogLevel(opts) {
   const logger = opts.logger ?? noopLogger;
@@ -4971,7 +5373,7 @@ async function harmonyOsAutoSign(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.12.0";
+var VERSION = "0.13.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALL_SDKS,
@@ -4991,9 +5393,11 @@ var VERSION = "0.12.0";
   SIGNING_ERRORS,
   SdkNotInstalledError,
   TMP_DIR_HINT,
+  TargetNotFoundError,
   UnsupportedPlatformError,
   VERSION,
   applyChanges,
+  assertLayoutSelector,
   attemptHdcConnection,
   buildCmdWrapper,
   buildGestureCommands,
@@ -5016,6 +5420,7 @@ var VERSION = "0.12.0";
   dedupEntries,
   defaultContext,
   defaultPaths,
+  describeLayoutNode,
   detectAaStartFailure,
   detectProjectSdkVersion,
   detectRuntimeOs,
@@ -5041,8 +5446,12 @@ var VERSION = "0.12.0";
   extractZipWithProgress,
   findAppProcessId,
   findCmdToolsSourceDir,
+  findCoveredNodes,
   findHarmonyOsSdk,
+  findKeyboardWindow,
+  findLayoutNodes,
   findRunningProcess,
+  flattenLayout,
   forceStop,
   formatBytes,
   generateSigningConfigs,
@@ -5057,6 +5466,7 @@ var VERSION = "0.12.0";
   getFreeSpaceBytes,
   getHdcPath,
   getHvigorwPath,
+  getImeBundles,
   getInstalledSdks,
   getKey,
   getMainAbility,
@@ -5069,6 +5479,7 @@ var VERSION = "0.12.0";
   harmonyOsAutoSign,
   harmonyOsSdkLabelForApi,
   hdcExec,
+  hideKeyboard,
   installApp,
   installCmdTools,
   installEmulator,
@@ -5085,6 +5496,7 @@ var VERSION = "0.12.0";
   listModules,
   listRunningProcesses,
   listTemplates,
+  locateTarget,
   needsCmdWrapper,
   nonInteractivePrompter,
   noopLogger,
@@ -5095,9 +5507,12 @@ var VERSION = "0.12.0";
   parseCodelinterFindings,
   parseDeviceList,
   parseHilogLine,
+  parseImeBundles,
   parseMainAbilityFromBmDump,
   parseRemoteExit,
+  performInput,
   pickSigningKind,
+  pickTarget,
   prepareSigning,
   pruneLayout,
   readJson5File,
@@ -5110,6 +5525,7 @@ var VERSION = "0.12.0";
   removeSdk,
   removeTempWorkDir,
   requireHarmonyOsSdk,
+  resolveKeyEvent,
   resolveTmpRoot,
   runCodelinter,
   runHvigorw,
@@ -5139,8 +5555,10 @@ var VERSION = "0.12.0";
   waitForBundle,
   waitForCondition,
   waitForLog,
+  waitForTarget,
   watchLog,
   waypointsToRawEvents,
+  withoutWindow,
   writeJson5File,
   writeJsonFile
 });