@oniroproject/core 0.16.0 → 0.18.0

package/dist/index.d.cts

@@ -28,7 +28,7 @@ declare const noopProgress: ProgressReporter;
  * Keys read from the ConfigProvider by core. Frontends (CLI, VS Code extension)
  * implement the provider however they like (env vars, settings.json, etc.).
  */
-type ConfigKey = 'sdkRootDir' | 'cmdToolsPath' | 'hdcPath' | 'emulatorDir' | 'hapPath' | 'cmdToolsUrlLinux' | 'cmdToolsUrlWindows' | 'cmdToolsUrlMac' | 'emulatorUrl' | 'tmpDir' | 'sdkUrlBase' | 'applicationCertPath' | 'harmonyosSdkPath' | 'harmonyosAuthDir' | 'harmonyosSigningDir';
+type ConfigKey = 'sdkRootDir' | 'cmdToolsPath' | 'hdcPath' | 'emulatorDir' | 'hapPath' | 'cmdToolsUrlLinux' | 'cmdToolsUrlWindows' | 'cmdToolsUrlMac' | 'emulatorUrl' | 'tmpDir' | 'sdkUrlBase' | 'applicationCertPath' | 'harmonyosSdkPath' | 'harmonyosAuthDir' | 'harmonyosSigningDir' | 'cacheDir' | 'docsDir';
 interface ConfigProvider {
     /**
      * Get the configured value for `key`, or `fallback` if unset/empty.
@@ -46,6 +46,7 @@ declare const defaultPaths: {
     readonly emulatorDir: () => string;
     readonly harmonyosAuthDir: () => string;
     readonly harmonyosSigningDir: () => string;
+    readonly cacheDir: () => string;
     readonly hapPath: "entry/build/default/outputs/default/entry-default-signed.hap";
     readonly emulatorUrl: "https://github.com/eclipse-oniro4openharmony/device_board_oniro/releases/latest/download/oniro_emulator.zip";
     readonly cmdToolsUrlLinux: "https://repo.huaweicloud.com/harmonyos/ohpm/5.1.0/commandline-tools-linux-x64-5.1.0.840.zip";
@@ -257,6 +258,12 @@ declare function getHvigorwPath(config: ConfigProvider, projectDir: string, plat
  * `00308018 SDK path does not exist` / "SDK license agreement is not accepted".
  */
 declare function findMissingProjectSdk(config: ConfigProvider, projectRoot: string): SdkNotInstalledError | null;
+/**
+ * The SDK API directory an OpenHarmony project builds against, as hvigor finds it:
+ * `<sdk home>/<compileSdkVersion>`, else under the project's `local.properties`
+ * `sdk.dir`. Undefined when neither holds it or the project names no numeric API.
+ */
+declare function resolveProjectSdkDir(config: ConfigProvider, projectRoot: string): string | undefined;
 /**
  * Detect the SDK API a project targets by reading `build-profile.json5`.
  * Returns the `compileSdkVersion` of the first declared product, or undefined
@@ -426,6 +433,64 @@ interface ZipEntry {
     attr?: number;
 }
 
+/**
+ * A HarmonyOS SDK install. Unlike the OpenHarmony SDK, which `oniro-app sdk install`
+ * downloads, the HarmonyOS SDK only ships inside DevEco Studio or the login-gated
+ * HarmonyOS command-line tools, so oniro-app locates an existing install.
+ */
+interface HarmonyOsSdk {
+    /** The directory containing `default/`; hvigor receives it as `DEVECO_SDK_HOME`. */
+    sdkPath: string;
+    /** The DevEco Studio or command-line-tools install holding the SDK, its tools and JBR. */
+    installRoot: string;
+    /** From `default/sdk-pkg.json`, e.g. `HarmonyOS 6.1.1`. */
+    displayName?: string;
+    /**
+     * The release as `compileSdkVersion` names it, e.g. `6.1.1(24)`, from
+     * `default/sdk-pkg.json`. hvigor builds only projects that name this release.
+     */
+    version?: string;
+    /** The API level, e.g. `24`, from `default/sdk-pkg.json`. */
+    apiVersion?: string;
+    /**
+     * Where it was found: `configured` (ONIRO_HARMONYOS_SDK_PATH), `deveco-studio`,
+     * or `cmdtools` (the HarmonyOS edition of the command-line tools at `cmdToolsPath`).
+     */
+    source?: HarmonyOsSdkSource;
+}
+type HarmonyOsSdkSource = 'configured' | 'deveco-studio' | 'cmdtools';
+/** What `default/sdk-pkg.json` says about an SDK. */
+interface SdkPkgInfo {
+    /** e.g. `HarmonyOS 6.1.1`. */
+    displayName?: string;
+    /** `<platformVersion>(<apiVersion>)`, e.g. `6.1.1(24)`. */
+    version?: string;
+    /** e.g. `6.1.1`. */
+    platformVersion?: string;
+    /** e.g. `24`. */
+    apiVersion?: string;
+    /** The SDK build, e.g. `6.1.1.125`. */
+    build?: string;
+}
+/** {@link SdkPkgInfo} from `<sdkPath>/default/sdk-pkg.json`; empty when it is missing or unreadable. */
+declare function readSdkPkg(sdkPath: string): SdkPkgInfo;
+/**
+ * Locate a HarmonyOS SDK, or return null when none is installed.
+ *
+ * Order: `harmonyosSdkPath` (`ONIRO_HARMONYOS_SDK_PATH`, an install root or its
+ * `sdk` directory), then DevEco Studio in its default location, then the
+ * command-line tools at `cmdToolsPath` when they are the HarmonyOS edition.
+ */
+declare function findHarmonyOsSdk(opts: {
+    config: ConfigProvider;
+    logger?: Logger;
+}): HarmonyOsSdk | null;
+/** Like `findHarmonyOsSdk`, but throws an actionable error when none is installed. */
+declare function requireHarmonyOsSdk(opts: {
+    config: ConfigProvider;
+    logger?: Logger;
+}): HarmonyOsSdk;
+
 interface SdkInfo {
     version: string;
     api: string;
@@ -436,6 +501,27 @@ interface SdkInfo {
  * Sorted by API descending (newest first).
  */
 declare function getSupportedSdksForUi(config: ConfigProvider): SdkInfo[];
+/** The HarmonyOS SDK on this machine, in the shape `sdk list` prints. */
+interface HarmonyOsSdkListing {
+    flavour: 'HarmonyOS';
+    /** e.g. `HarmonyOS 6.1.1`. */
+    displayName?: string;
+    /** The release, e.g. `6.1.1`. */
+    version?: string;
+    /** e.g. `24`. */
+    api?: string;
+    installed: true;
+    /** The SDK directory hvigor receives as `DEVECO_SDK_HOME`. */
+    path: string;
+    /** Where it was found; `cmdtools` for the command-line tools at `cmdToolsPath`. */
+    source?: HarmonyOsSdkSource;
+}
+/**
+ * The HarmonyOS SDK a HarmonyOS build would use, or null. `sdk install` does not
+ * manage it: it ships with the HarmonyOS command-line tools (`cmdtools`) or
+ * DevEco Studio (#21).
+ */
+declare function getHarmonyOsSdkListing(config: ConfigProvider): HarmonyOsSdkListing | null;
 /**
  * Return the SDK versions that have at least one OS-folder install in `sdkRootDir`.
  * Scans `linux`, `darwin`, `windows` so the list is consistent across machines that
@@ -546,12 +632,49 @@ interface InstallCmdToolsOptions {
      * config key and the default location next to the install target.
      */
     tmpDir?: string;
+    /**
+     * Filesystem seams for tests: `move` stages each extracted entry inside the
+     * install directory (default {@link movePath}), `rename` swaps entries in and
+     * out of it (default `fs.renameSync`).
+     * @internal
+     */
+    fsOps?: Partial<CmdToolsFsOps>;
+}
+interface InstallCmdToolsResult {
+    /** The install directory. */
+    path: string;
+    /** What is installed now. */
+    installed: CmdToolsInfo;
+    /** What the install replaced; absent when the directory was missing or empty. */
+    previous?: CmdToolsInfo;
+}
+/**
+ * What `installCmdTools` says when it replaces an install: which release replaces
+ * which, and when hvigor changes major version or the new release is older, that
+ * too. Pure.
+ */
+declare function describeReplacement(previous: CmdToolsInfo, next: CmdToolsInfo): string[];
+/** @internal */
+interface CmdToolsFsOps {
+    move: (src: string, dest: string) => void;
+    rename: (src: string, dest: string) => void;
 }
 /**
  * Install the OpenHarmony command-line tools into `<cmdToolsPath>`.
  * Either downloads from the platform-specific URL or installs from a caller-supplied ZIP.
+ *
+ * The archive is extracted to scratch space and staged inside the install
+ * directory; only once the whole tree is staged are its entries swapped in for the
+ * old ones. A failure before that (a full disk mid-copy, say) leaves the install
+ * directory as it was, and one during the swap rolls it back (#16). A successful
+ * install replaces the directory's contents outright, so it holds exactly what a
+ * clean extraction of the archive holds, whatever an earlier failed attempt or an
+ * older version left there. Entries that are not the tools' (see `TOOL_ENTRIES`) stay.
+ *
+ * When it replaces an install, it logs which release replaces which before the
+ * old one is deleted, and returns both (#25).
  */
-declare function installCmdTools(opts: InstallCmdToolsOptions): Promise<void>;
+declare function installCmdTools(opts: InstallCmdToolsOptions): Promise<InstallCmdToolsResult>;
 interface CmdToolsStatus {
     installed: boolean;
     status: string;
@@ -564,8 +687,50 @@ interface CmdToolsStatus {
         path: string;
         exists: boolean;
     };
+    /** The bundle release, e.g. `6.1.1.280`, as in `status`. Set when known. */
+    version?: string;
+    /** The SDK the tools bundle (the HarmonyOS SDK, in the HarmonyOS edition). Set when installed and present. */
+    sdk?: CmdToolsSdk;
+    /** Versions of the tools inside, from `version.txt`, e.g. `{ hvigor: '6.24.2', ohpm: '6.1.2.268' }`. */
+    tools?: Record<string, string>;
 }
 type CmdToolsFlavour = 'HarmonyOS' | 'OpenHarmony';
+/** The SDK a command-line tools install ships under `sdk/`. */
+interface CmdToolsSdk {
+    /** The `sdk` directory, which HarmonyOS builds receive as `DEVECO_SDK_HOME`. */
+    path: string;
+    /** e.g. `HarmonyOS 6.1.1`. */
+    displayName?: string;
+    /** e.g. `6.1.1`. */
+    platformVersion?: string;
+    /** e.g. `24`. */
+    apiVersion?: string;
+    /** The SDK build, e.g. `6.1.1.125`. */
+    build?: string;
+}
+/** What a command-line tools install holds: its release, flavour, SDK and tool versions. */
+interface CmdToolsInfo {
+    /** From `version.txt` (`# Version: 6.1.1.280`). */
+    version?: string;
+    flavour: CmdToolsFlavour;
+    sdk?: CmdToolsSdk;
+    /** Tool versions `version.txt` lists (`hvigor : 6.24.2`). */
+    tools: Record<string, string>;
+}
+/**
+ * Read what the command-line tools at `cmdToolsPath` are, from `version.txt` and
+ * `sdk/default/sdk-pkg.json`. Fields it cannot find are left out. Pure file reads.
+ */
+declare function readCmdToolsInfo(cmdToolsPath: string): CmdToolsInfo;
+/**
+ * One line naming a tools install: `6.1.1.280 (HarmonyOS 6.1.1, API 24, hvigor 6.24.2)`,
+ * leaving out what is unknown.
+ */
+declare function describeCmdTools(info: {
+    version?: string;
+    sdk?: CmdToolsSdk;
+    tools?: Record<string, string>;
+}): string;
 /**
  * The flavour of a command-line tools install: `HarmonyOS` when it bundles the
  * HarmonyOS SDK (`sdk/default/hms`, as the Huawei developer-portal download
@@ -575,8 +740,9 @@ type CmdToolsFlavour = 'HarmonyOS' | 'OpenHarmony';
 declare function detectCmdToolsFlavour(cmdToolsPath: string): CmdToolsFlavour;
 /**
  * Reports whether ohpm is present at the configured path, and if so its version,
- * flavour, and the hdc binary in use. Prefers reading `version.txt`
- * (`# Version: x.y.z`) before falling back to executing the binary with `-v`.
+ * flavour, the SDK it bundles, its tools' versions (see {@link readCmdToolsInfo})
+ * and the hdc binary in use. The version comes from `version.txt`
+ * (`# Version: x.y.z`), else from running ohpm with `-v`.
  */
 declare function getCmdToolsStatus(config: ConfigProvider): CmdToolsStatus;
 declare function isCmdToolsInstalled(config: ConfigProvider): boolean;
@@ -684,6 +850,25 @@ interface GenerateSigningConfigsOptions {
  * @internal exposed for tests.
  */
 declare function detectSigningConfigNames(projectDir: string): string[];
+/** What the signing material in a `signatures` directory amounts to, for a one-line summary. */
+interface SigningMaterialSummary {
+    /** The profile's type: `release` for the SDK's template. */
+    profileType?: string;
+    apl?: string;
+    /**
+     * The end of the profile's validity window. The SDK's template carries a fixed
+     * one that ended in 2023, which OpenHarmony devices do not enforce.
+     */
+    profileNotAfter?: Date;
+    /** When the certificate that signs HAPs expires. */
+    certificateNotAfter?: Date;
+}
+/** `release profile, apl normal; certificate valid until 2049-12-31 12:21 UTC`. Empty when nothing is known. */
+declare function describeSigningMaterial(summary: SigningMaterialSummary): string;
+interface GenerateSigningConfigsResult extends SigningMaterialSummary {
+    signaturesDir: string;
+    kind: SigningKind;
+}
 /**
  * Generate signing configs for an OpenHarmony project: copies certs, signs the profile,
  * generates the signing material, and writes the resulting `signingConfigs` entry into
@@ -691,7 +876,7 @@ declare function detectSigningConfigNames(projectDir: string): string[];
  *
  * Requires `java` on PATH (the OpenHarmony hap-sign-tool ships as a .jar).
  */
-declare function generateSigningConfigs(options: GenerateSigningConfigsOptions): void;
+declare function generateSigningConfigs(options: GenerateSigningConfigsOptions): GenerateSigningConfigsResult;
 
 /** What signing needs to know about a built HAP. */
 interface HapSigningInfo {
@@ -736,6 +921,8 @@ interface SignOpenHarmonyHapResult {
     /** API level of the SDK whose signing material was used. */
     sdkApi: string;
     kind: SigningKind;
+    /** The profile and certificate the HAP was signed with. */
+    material: SigningMaterialSummary;
 }
 /**
  * Sign a prebuilt HAP, with no project, for OpenHarmony devices: the SDK's
@@ -746,6 +933,109 @@ interface SignOpenHarmonyHapResult {
  */
 declare function signOpenHarmonyHap(opts: SignOpenHarmonyHapOptions): Promise<SignOpenHarmonyHapResult>;
 
+/** One certificate of a signing chain, in a form fit for printing and JSON. */
+interface CertificateInfo {
+    /** `CN=…, OU=…, O=…, C=…`, most specific first, as Java and openssl print it. */
+    subject: string;
+    issuer: string;
+    /** The subject's common name, unescaped. */
+    commonName?: string;
+    notBefore: Date;
+    notAfter: Date;
+    /** SHA-256 fingerprint, colon-separated hex. */
+    fingerprint256: string;
+    selfSigned: boolean;
+}
+
+/**
+ * Who issued the signing material: the OpenHarmony SDK's development certificate
+ * and `pki_internal` profile, which OpenHarmony devices accept and HarmonyOS
+ * devices do not; AppGallery Connect, whose chain ends at `Huawei CBG Root CA G2`;
+ * or neither.
+ */
+type HapSigner = 'openharmony-dev' | 'harmonyos-agc' | 'other';
+/** `valid`: exit 0. `invalid` (unsigned, bad signature, expired, mismatched): 1. `unverified` (no java or hap-sign-tool): 2. */
+type HapVerifyStatus = 'valid' | 'invalid' | 'unverified';
+interface HapProfileReport {
+    /** `debug` or `release`. */
+    type?: string;
+    /** `app_gallery` (AGC) or `pki_internal` (the OpenHarmony SDK's). */
+    issuer?: string;
+    bundleName?: string;
+    developerId?: string;
+    apl?: string;
+    appFeature?: string;
+    /** UDIDs a debug profile is limited to; a release profile names none. */
+    deviceCount: number;
+    notBefore?: Date;
+    notAfter?: Date;
+    expired: boolean;
+    /** Whole days until `notAfter`; negative once past it. */
+    daysLeft?: number;
+    /**
+     * Whether a device refuses the HAP once the profile is out of date. Not for the
+     * OpenHarmony SDK's development profile, whose fixed 2020-2023 window
+     * OpenHarmony devices ignore.
+     */
+    expiryEnforced: boolean;
+    /** Whether the profile names the certificate that signed the HAP; undefined when it names none. */
+    issuedForSigningCertificate?: boolean;
+}
+interface VerifyHapResult {
+    hapPath: string;
+    status: HapVerifyStatus;
+    /** Whether the HAP has a signing block at all. */
+    signed: boolean;
+    /** hap-sign-tool `verify-app` accepted the signature. */
+    signatureValid: boolean;
+    signer?: HapSigner;
+    /** The signing chain, leaf first. */
+    chain: CertificateInfo[];
+    /** Common name (else subject) of the chain's root. */
+    root?: string;
+    profile?: HapProfileReport;
+    /** The bundle name in the HAP's own module.json. */
+    hapBundleName?: string;
+    /** `app.compileSdkType` in the HAP's module.json: `OpenHarmony` or `HarmonyOS`, when the toolchain wrote it. */
+    hapCompileSdkType?: string;
+    /** What makes it `invalid` or `unverified`. Empty when `valid`. */
+    problems: string[];
+    /** Worth knowing; no effect on `status`. */
+    notes: string[];
+    /** hap-sign-tool's own error lines, when it refused the HAP. */
+    toolErrors: string[];
+    signTool?: string;
+    java?: string;
+}
+interface VerifyHapOptions {
+    hapPath: string;
+    config: ConfigProvider;
+    logger?: Logger;
+    /** The time profile and certificate validity is judged at. Default now. */
+    now?: Date;
+    /** Use this `hap-sign-tool.jar` instead of looking for one. */
+    signTool?: string;
+    /** Use this java instead of looking for one. */
+    java?: string;
+}
+/**
+ * A `hap-sign-tool.jar` to verify with: an installed OpenHarmony SDK's, else the
+ * HarmonyOS SDK's, else the command-line tools'. Any of them verifies any HAP.
+ */
+declare function findHapSignTool(config: ConfigProvider, logger?: Logger): string | null;
+/**
+ * Verify a HAP's signature with the SDK's `hap-sign-tool.jar verify-app`, then
+ * read what signed it: the certificate chain, whether it is OpenHarmony
+ * development material or AppGallery Connect's, and the provisioning profile's
+ * type, bundle, APL, devices and validity. Never throws for a HAP that is
+ * unsigned, mis-signed or expired; that is the `status` and `problems`.
+ */
+declare function verifyHap(opts: VerifyHapOptions): Promise<VerifyHapResult>;
+/** 0 valid, 1 invalid (unsigned, bad signature, expired, mismatched), 2 could not verify. */
+declare function verifyHapExitCode(result: Pick<VerifyHapResult, 'status'>): number;
+/** {@link verifyHap}'s result as the lines `oniro-app app verify` prints. */
+declare function formatHapVerification(result: VerifyHapResult): string;
+
 interface InstallEmulatorOptions {
     config: ConfigProvider;
     progress?: ProgressReporter;
@@ -769,6 +1059,223 @@ declare function installEmulator(opts: InstallEmulatorOptions): Promise<void>;
 declare function isEmulatorInstalled(config: ConfigProvider): boolean;
 declare function removeEmulator(config: ConfigProvider): void;
 
+/**
+ * Health of one emulator instance:
+ * - `stopped`: no QEMU process.
+ * - `booting`: QEMU is alive; hdc cannot reach the guest yet, or `bootevent.boot.completed` is not `true`.
+ * - `ready`: `hdc shell param get bootevent.boot.completed` answers `true`.
+ * - `hdc-lost`: the instance was ready during this boot and hdc can no longer reach it.
+ * - `stuck`: QEMU is alive but the boot has not completed within the instance's boot timeout.
+ */
+type EmulatorHealth = 'stopped' | 'booting' | 'ready' | 'hdc-lost' | 'stuck';
+/** Ports of pool instance `n`: hdc 55555+n, VNC display n (5900+n), telnet serial 4444+n. */
+interface PoolInstancePorts {
+    hdc: number;
+    vncDisplay: number;
+    vnc: number;
+    serial: number;
+}
+declare function poolInstancePorts(n: number): PoolInstancePorts;
+/** The writable disks run.sh attaches, in its order (the guest sees them as vda..vdd). */
+declare const POOL_DISKS: readonly ["updater", "system", "vendor", "userdata"];
+/** Every file a pool instance needs in `<emulatorDir>/images`. */
+declare const POOL_REQUIRED_IMAGES: readonly ["bzImage", "ramdisk.img", ...string[]];
+/** run.sh's kernel command line, verbatim. */
+declare const EMULATOR_KERNEL_APPEND: string;
+/** Pool defaults: smaller than run.sh's 6 CPUs / 4 GB so several instances fit on one host. */
+declare const POOL_DEFAULT_SMP = 2;
+declare const POOL_DEFAULT_MEMORY = "2048M";
+declare const POOL_DEFAULT_RESOLUTION = "360x720";
+/** Seconds after launch past which a boot that has not completed counts as `stuck`. */
+declare const DEFAULT_BOOT_TIMEOUT_SECONDS = 300;
+type EmulatorAccel = 'auto' | 'kvm' | 'hvf' | 'whpx' | 'tcg';
+/**
+ * QEMU accelerator and CPU arguments, chosen as run.sh chooses them: KVM on Linux,
+ * HVF on an x86_64 Mac, TCG on Apple Silicon, WHPX on Windows. Pure/testable.
+ */
+declare function emulatorAccelArgs(accel?: EmulatorAccel, platform?: NodeJS.Platform, arch?: string): string[];
+interface PoolQemuSpec {
+    instance: number;
+    /** The instance's state directory, holding `<disk>.qcow2`. */
+    dir: string;
+    /** `<emulatorDir>/images`, holding bzImage and ramdisk.img. */
+    imagesDir: string;
+    smp: number;
+    memory: string;
+    resolution: string;
+    headless: boolean;
+    /** `es1370` or `ES1370`, whichever this QEMU names it. */
+    audioDevice: string;
+    accelArgs: readonly string[];
+    ports: PoolInstancePorts;
+}
+/**
+ * The QEMU command line of a pool instance: run.sh's (q35, kernel/initrd/append,
+ * four virtio-blk disks in the same order, virtio-gpu, user networking forwarding
+ * the guest's hdcd port 55555) with the disks replaced by the instance's qcow2
+ * overlays and every host port bound to 127.0.0.1 at the instance's own number.
+ * Audio goes to a `none` backend so instances do not compete for the host's sound
+ * server. Pure/testable.
+ */
+declare function buildPoolQemuArgs(spec: PoolQemuSpec): string[];
+/** Inputs to {@link classifyEmulatorHealth}. */
+interface HealthInputs {
+    /** QEMU is alive. */
+    alive: boolean;
+    /** hdc ran a shell command on the guest. */
+    hdcReachable: boolean;
+    /** `bootevent.boot.completed` is `true`. */
+    bootCompleted: boolean;
+    /** This boot has been seen ready before. */
+    wasReady: boolean;
+    /** Milliseconds since QEMU was launched, when known. */
+    elapsedMs?: number;
+    bootTimeoutMs: number;
+}
+/** The health code for one probe. Pure/testable. */
+declare function classifyEmulatorHealth(i: HealthInputs): EmulatorHealth;
+interface HdcBootProbe {
+    hdcReachable: boolean;
+    bootCompleted: boolean;
+}
+/**
+ * Ask the guest at `address` whether it has booted: `hdc tconn <address>` (which
+ * adds the target to the running hdc server, never restarting it), then
+ * `hdc -t <address> shell param get bootevent.boot.completed`.
+ */
+declare function probeEmulatorBoot(config: ConfigProvider, address: string, opts?: {
+    logger?: Logger;
+    timeoutMs?: number;
+}): Promise<HdcBootProbe>;
+/** One instance as `emulator status` reports it. */
+interface EmulatorInstanceStatus {
+    /** 0 is the default emulator (run.sh); 1.. are pool instances. */
+    instance: number;
+    state: EmulatorHealth;
+    /** hdc serial: `127.0.0.1:<hdcPort>`. */
+    address: string;
+    hdcPort: number;
+    /** VNC TCP port (headless pool instances). */
+    vncPort?: number;
+    /** Telnet serial console port (pool instances). */
+    serialPort?: number;
+    pid?: number;
+    hdcReachable: boolean;
+    bootCompleted: boolean;
+    /** Pool instance state directory (overlays, instance.json, qemu.log). */
+    dir?: string;
+    logFile?: string;
+    memory?: string;
+    smp?: number;
+    headless?: boolean;
+    startedAt?: string;
+    readyAt?: string;
+    /** Seconds from launch to the first `ready` of this boot. */
+    bootSeconds?: number;
+}
+/**
+ * Status of pool instance `n`, probing hdc when QEMU is alive. Records the first
+ * `ready` (and a later loss of hdc) in the instance's `instance.json`, which is what
+ * tells `hdc-lost` apart from `booting`.
+ */
+declare function getPoolInstanceStatus(config: ConfigProvider, n: number, opts?: {
+    logger?: Logger;
+    probeTimeoutMs?: number;
+}): Promise<EmulatorInstanceStatus>;
+/** Status of every pool instance that has a state directory, probed in parallel. */
+declare function listPoolInstanceStatuses(config: ConfigProvider, opts?: {
+    logger?: Logger;
+    probeTimeoutMs?: number;
+}): Promise<EmulatorInstanceStatus[]>;
+/**
+ * Status of the default emulator (instance 0, launched by run.sh). Without a record
+ * of an earlier `ready`, it is never `hdc-lost`; `stuck` counts from the PID file's
+ * mtime, i.e. the launch.
+ */
+declare function getDefaultInstanceStatus(config: ConfigProvider, opts: {
+    running: boolean;
+    address?: string;
+    logger?: Logger;
+    probeTimeoutMs?: number;
+    bootTimeoutSeconds?: number;
+}): Promise<EmulatorInstanceStatus>;
+/** Whether `port` can be bound on `host` right now. */
+declare function isTcpPortFree(port: number, host?: string): Promise<boolean>;
+declare function readLogTail(filePath: string, bytes: number): string;
+interface StartPoolInstanceOptions {
+    config: ConfigProvider;
+    /** Pool instance number, 1..99. */
+    instance: number;
+    logger?: Logger;
+    /** Virtual CPUs. Default {@link POOL_DEFAULT_SMP}. */
+    smp?: number;
+    /** RAM in QEMU's `-m` syntax. Default {@link POOL_DEFAULT_MEMORY}. */
+    memory?: string;
+    /** Display resolution, WxH. Default {@link POOL_DEFAULT_RESOLUTION}. */
+    resolution?: string;
+    /** VNC on 127.0.0.1:590n instead of a local SDL window. Default true. */
+    headless?: boolean;
+    /** Discard the instance's overlays first: a factory reset. */
+    fresh?: boolean;
+    /** Seconds after launch past which a boot that has not completed is `stuck`. Default 300. */
+    bootTimeoutSeconds?: number;
+    /** If > 0, wait up to this many seconds for `ready`. */
+    waitReadySeconds?: number;
+    /** Poll interval of that wait, ms. Default 5000. */
+    pollIntervalMs?: number;
+    /** QEMU binary. Default `QEMU_BIN`, else `qemu-system-x86_64` from PATH. */
+    qemuBin?: string;
+    /** qemu-img binary. Default: next to `qemuBin`, else from PATH. */
+    qemuImg?: string;
+    /** Accelerator. Default `auto` (KVM on Linux, as run.sh). */
+    accel?: EmulatorAccel;
+    /** QEMU's stdout/stderr. Default `<instance dir>/qemu.log`. */
+    logFile?: string;
+    /** How long QEMU must stay up after launch before it counts as started, ms. Default 2000. */
+    earlyExitWindowMs?: number;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Launch pool instance `n` (n >= 1): its own QEMU, detached, on copy-on-write
+ * overlays of the bundled images, with hdc forwarded from 127.0.0.1:55555+n, VNC
+ * on display n and the serial console on telnet 4444+n. The default emulator
+ * (run.sh, instance 0) opens the same images read-write, so the two cannot run at
+ * once; that is checked up front. If the instance is already running, nothing is
+ * launched. Connects hdc with `hdc tconn` only; the hdc server is never restarted.
+ */
+declare function startPoolInstance(opts: StartPoolInstanceOptions): Promise<EmulatorInstanceStatus>;
+interface WaitPoolInstanceReadyOptions {
+    config: ConfigProvider;
+    instance: number;
+    timeoutSeconds: number;
+    /** Default 5000. */
+    pollIntervalMs?: number;
+    logger?: Logger;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Poll pool instance `n` until it is `ready`. Throws when QEMU exits (with the log
+ * tail) or the timeout passes.
+ */
+declare function waitPoolInstanceReady(opts: WaitPoolInstanceReadyOptions): Promise<EmulatorInstanceStatus>;
+interface StopPoolInstanceOptions {
+    config: ConfigProvider;
+    instance: number;
+    /** Also delete the instance's directory: overlays, log and state. */
+    discard?: boolean;
+    logger?: Logger;
+    /** How long to wait for QEMU to exit after SIGTERM before SIGKILL, ms. Default 15000. */
+    killTimeoutMs?: number;
+}
+/**
+ * Stop pool instance `n`: signal only its own QEMU (by the PID it recorded, checked
+ * against the instance directory on Linux), drop its target from the hdc server with
+ * `hdc tconn <address> -remove`, and with `discard` delete its overlays. Other
+ * instances, the default emulator and every other QEMU are left alone. Resolves to
+ * whether a running QEMU was stopped.
+ */
+declare function stopPoolInstance(opts: StopPoolInstanceOptions): Promise<boolean>;
+
 /**
  * Try to connect hdc to the emulator. Resolves true on success, false otherwise.
  */
@@ -798,6 +1305,12 @@ interface StartEmulatorOptions {
     waitForHdcSeconds?: number;
     /** Poll interval for the hdc wait, ms. Default 5000. */
     hdcPollIntervalMs?: number;
+    /**
+     * If > 0, block until the guest reports `bootevent.boot.completed=true` over hdc, up
+     * to this many seconds. Connects with `hdc tconn` only: unlike `waitForHdcSeconds`,
+     * it never restarts the hdc server, so other connected devices are not disturbed.
+     */
+    waitReadySeconds?: number;
     abortSignal?: AbortSignal;
 }
 /**
@@ -813,12 +1326,17 @@ interface EmulatorStatus {
     installed: boolean;
     /** The configured emulator directory. */
     dir: string;
-    /** Whether an emulator QEMU process is alive. */
+    /** Whether the default emulator's QEMU is alive (pool instances do not count). */
     running: boolean;
     /** The hdc address checked for `connected`. */
     address: string;
     /** hdc lists `address` as a Connected target. */
     connected: boolean;
+    /**
+     * Every instance: the default emulator (instance 0, `address`) first, then each pool
+     * instance that has a state directory, with its health code.
+     */
+    instances: EmulatorInstanceStatus[];
 }
 /**
  * Report on the Oniro emulator without starting it: installed, running, and whether
@@ -830,6 +1348,66 @@ declare function getEmulatorStatus(config: ConfigProvider, opts?: {
     logger?: Logger;
 }): Promise<EmulatorStatus>;
 
+/**
+ * PID file of the default emulator (instance 0), the one `startEmulator` launches
+ * through the bundled run.sh/run.bat.
+ */
+declare const DEFAULT_EMULATOR_PID_FILE: string;
+/** Highest pool instance number `--instance` accepts. */
+declare const MAX_POOL_INSTANCE = 99;
+/** Whether a process with this PID exists (signal 0 probes without signalling). */
+declare function isPidAlive(pid: number | undefined): boolean;
+/** The PID of the default emulator (instance 0) when its PID file names a live process. */
+declare function readDefaultEmulatorPid(pidFile?: string): number | undefined;
+/** Throw unless `n` is a pool instance number (1..{@link MAX_POOL_INSTANCE}). */
+declare function assertPoolInstance(n: number): void;
+/** Where pool instances keep their state: `<emulatorDir>/instances`. */
+declare function poolRootDir(config: ConfigProvider): string;
+/** State directory of pool instance `n`: overlays, `instance.json`, `qemu.log`. */
+declare function poolInstanceDir(config: ConfigProvider, n: number): string;
+/** Size and mtime of a base image when its overlay was created; a change means the overlay is stale. */
+interface BaseImageFingerprint {
+    size: number;
+    mtimeMs: number;
+}
+/** What `instance.json` records about a pool instance. */
+interface PoolInstanceState {
+    instance: number;
+    /** QEMU's PID while it runs. */
+    pid?: number;
+    hdcPort: number;
+    vncDisplay: number;
+    serialPort: number;
+    memory: string;
+    smp: number;
+    resolution: string;
+    headless: boolean;
+    /** Seconds after `startedAt` past which a boot that never reached `ready` is `stuck`. */
+    bootTimeoutSeconds: number;
+    /** ISO time QEMU was launched. */
+    startedAt?: string;
+    /** ISO time this boot was first seen ready (`bootevent.boot.completed=true`). */
+    readyAt?: string;
+    /** ISO time hdc was first seen unable to reach the instance after it had been ready. */
+    lostAt?: string;
+    logFile: string;
+    /** Base image name (e.g. `userdata.img`) → fingerprint at overlay creation. */
+    bases?: Record<string, BaseImageFingerprint>;
+}
+declare function stateFile(dir: string): string;
+declare function readPoolState(dir: string): PoolInstanceState | undefined;
+declare function writePoolState(dir: string, state: PoolInstanceState): void;
+/**
+ * Whether `pid` is the QEMU of the instance in `dir`. On Linux the command line must
+ * name the directory, so a PID the OS recycled for another process is not mistaken
+ * for the instance (and never signalled); elsewhere only liveness is checked.
+ */
+declare function isInstanceProcess(pid: number | undefined, dir: string): boolean;
+/** Instance numbers that have a state directory, ascending. */
+declare function listPoolInstanceNumbers(config: ConfigProvider): number[];
+/** PIDs of pool instances whose QEMU is alive. */
+declare function livePoolPids(config: ConfigProvider): Map<number, number>;
+
 /**
  * True when `command` must be routed through `cmd.exe` to run at all —
  * i.e. we are on Windows and the target is a batch wrapper.
@@ -1369,6 +1947,156 @@ declare function sendGesture(opts: SendGestureOptions): Promise<void>;
  */
 declare function sendRawTouch(opts: SendRawTouchOptions): Promise<void>;
 
+/** A `--selector` expression (attribute DSL or XPath) that does not parse. */
+declare class SelectorParseError extends OniroError {
+    /** Offset into `input` where parsing stopped. */
+    readonly position: number;
+    readonly input: string;
+    constructor(detail: string, 
+    /** Offset into `input` where parsing stopped. */
+    position: number, input: string);
+}
+/**
+ * The element attributes a `--selector` expression (DSL key or XPath `@name`)
+ * can test, read off the pruned tree `dump layout` prints. Strings compare as
+ * they appear there; the boolean ones are always present as "true" or "false".
+ */
+declare const SELECTOR_KEYS: readonly ["text", "desc", "hint", "id", "key", "type", "enabled", "focused", "checked", "selected", "visible", "clickable", "longClickable", "checkable", "scrollable"];
+type SelectorKey = (typeof SELECTOR_KEYS)[number];
+/** The canonical key for `name` (`description` is `desc`), or undefined when it is not one. */
+declare function resolveSelectorKey(name: string): SelectorKey | undefined;
+/**
+ * The value of a selector attribute on a node. `key` falls back to `id` (the
+ * pruned tree drops a key equal to the id); `enabled` is the inverse of
+ * `disabled`; `visible` means drawn and not covered by an overlay.
+ */
+declare function selectorAttribute(n: FlatLayoutNode, key: SelectorKey): string | undefined;
+/** A layout node's own fields, tagged with its enclosing window's bundle and id. */
+declare function flatLayoutNode(n: LayoutNode, window: string | undefined, windowId: number | undefined): FlatLayoutNode;
+/** The node carries fields of its own, not just children. */
+declare function hasOwnFields(n: LayoutNode): boolean;
+/** A pruned layout node with links to its parent and children, for selector and XPath evaluation. */
+interface IndexedLayoutNode {
+    flat: FlatLayoutNode;
+    parent: IndexedLayoutNode | null;
+    children: IndexedLayoutNode[];
+    /** Position in depth-first (paint) order. */
+    order: number;
+    /** A bare container: no fields of its own (it never matches a selector). */
+    empty: boolean;
+}
+/** Link up a pruned tree; returns its root. Depth-first order matches {@link flattenLayout}. */
+declare function indexLayout(tree: LayoutNode): IndexedLayoutNode;
+/** Every node of an indexed tree, depth-first. */
+declare function allIndexed(root: IndexedLayoutNode): IndexedLayoutNode[];
+
+type Expr = {
+    k: 'or' | 'and';
+    a: Expr;
+    b: Expr;
+} | {
+    k: 'cmp';
+    op: CmpOp;
+    a: Expr;
+    b: Expr;
+} | {
+    k: 'attr';
+    key: SelectorKey;
+} | {
+    k: 'str';
+    v: string;
+} | {
+    k: 'num';
+    v: number;
+} | {
+    k: 'fn';
+    name: FnName;
+    args: Expr[];
+};
+type CmpOp = '=' | '!=' | '<' | '<=' | '>' | '>=';
+type FnName = 'contains' | 'starts-with' | 'ends-with' | 'not' | 'position' | 'last';
+type Step = {
+    axis: 'child' | 'descendant';
+    name: string;
+    predicates: Expr[];
+} | {
+    axis: 'self' | 'descendant-or-self' | 'parent';
+};
+/** A parsed XPath expression (see {@link parseXPath}). */
+interface XPathExpression {
+    /** The source text. */
+    readonly source: string;
+    /** Where evaluation starts: the document, or a parenthesised path filtered by predicates. */
+    readonly start: {
+        group: XPathExpression;
+        predicates: Expr[];
+    } | 'root';
+    readonly steps: readonly Step[];
+}
+/** Parse an XPath expression in the supported subset; throws {@link SelectorParseError}. */
+declare function parseXPath(source: string): XPathExpression;
+/**
+ * Evaluate an XPath expression (source text or {@link parseXPath} result) over
+ * a pruned layout tree. Returns the matching nodes in paint order, tagged with
+ * their window; bare containers are never returned.
+ */
+declare function evaluateXPath(tree: LayoutNode, expr: XPathExpression | string): FlatLayoutNode[];
+
+/** `=` equals, `*=` contains, `^=` starts with, `$=` ends with, `/=` matches a regular expression. */
+type SelectorOperator = '=' | '*=' | '^=' | '$=' | '/=';
+interface SelectorClause {
+    key: SelectorKey;
+    op: SelectorOperator;
+    value: string;
+    /** Regular-expression flags, for `/=` (`text/=^sign/i`). */
+    flags?: string;
+}
+/** `type=Button,text*=Sign[1]`: every clause must hold; `index` picks one match. */
+interface DslSelector {
+    kind: 'dsl';
+    clauses: SelectorClause[];
+    /** 0-based index into the matches in paint order; negative counts from the end (`[last]` is -1). */
+    index?: number;
+    raw: string;
+}
+/** `xpath=//Button[@text="OK"]`. */
+interface XPathSelector {
+    kind: 'xpath';
+    xpath: XPathExpression;
+    raw: string;
+}
+/** A parsed `--selector` expression. */
+type ElementSelector = DslSelector | XPathSelector;
+/**
+ * Parse a `--selector` expression: `xpath=<expr>` (see ./xpath.ts for the
+ * subset), or the attribute DSL `key<op>value[,key<op>value…][n]` with keys
+ * from {@link SELECTOR_KEYS}. Throws {@link SelectorParseError}.
+ */
+declare function parseSelector(input: string): ElementSelector;
+/** Whether one clause holds on a node. String comparisons are case-sensitive. */
+declare function clauseMatches(n: FlatLayoutNode, clause: SelectorClause): boolean;
+/**
+ * Every node of a pruned layout tree matching `selector`, in paint order,
+ * tagged with its window. The DSL index suffix is not applied here (callers
+ * pick with it); bare containers never match.
+ */
+declare function matchSelector(tree: LayoutNode, selector: ElementSelector): FlatLayoutNode[];
+/** Render DSL clauses (and an index) back into `--selector` text that {@link parseSelector} reads back. */
+declare function formatSelector(clauses: readonly SelectorClause[], index?: number): string;
+/** The recorded attributes of an element, as `dump layout` / `wait --json` print them. */
+type RecordedElement = Partial<FlatLayoutNode>;
+/**
+ * The most specific stable `--selector` for a recorded element: the first of
+ * `type` plus one of id, key, text, desc or hint (in that order of
+ * stability), then type plus every stable attribute it has, that matches
+ * exactly this element in `tree`; failing that, the full clause set with the
+ * element's `[n]` index among its matches. Exact (`=`) clauses only, so the
+ * selector does not drift onto similar elements. The element is found in
+ * `tree` by its type, id, key and labels (nearest `c` breaks a tie); throws
+ * when it is not there. Pure — the replay side of `record` (O-9) builds on it.
+ */
+declare function selectorFor(tree: LayoutNode, element: RecordedElement): string;
+
 /** A raw `uitest dumpLayout` node (attributes are strings). */
 interface RawLayoutNode {
     attributes?: Record<string, string>;
@@ -1397,6 +2125,13 @@ interface LayoutNode {
     longClick?: boolean;
     /** The component is disabled (`enabled: false`). */
     disabled?: boolean;
+    /** The component is not drawn (`visible: false`). */
+    hidden?: boolean;
+    /**
+     * Set on the node where a window starts: its window id (uitest's
+     * `hostWindowId`, the `WinId` column of `hidumper -s WindowManagerService -a -a`).
+     */
+    windowId?: number;
     /** The node's center is painted over by a later filled node (an overlay, a
      *  dialog scrim, the soft keyboard), so a tap there would land on that instead. */
     covered?: boolean;
@@ -1436,14 +2171,36 @@ declare function findCoveredNodes(root: RawLayoutNode): Set<RawLayoutNode>;
  * from the proven MCP `pruneNode`; `covered` (from {@link findCoveredNodes})
  * marks nodes hidden under an overlay.
  */
-declare function pruneLayout(node: RawLayoutNode, display: DisplaySize | null, covered?: ReadonlySet<RawLayoutNode>): LayoutNode | LayoutNode[] | null;
+declare function pruneLayout(node: RawLayoutNode, display: DisplaySize | null, covered?: ReadonlySet<RawLayoutNode>, parentWindow?: string): LayoutNode | LayoutNode[] | null;
 /** A pruned layout node without children, tagged with the window it belongs to. */
 interface FlatLayoutNode extends Omit<LayoutNode, 'children'> {
     /** Bundle of the enclosing window (the nearest node carrying `bundle`). */
     window?: string;
+    /** Id of the enclosing window (the nearest node carrying `windowId`). */
+    windowId?: number;
 }
 /** Flatten a pruned layout tree into a depth-first (paint-order) list. */
 declare function flattenLayout(tree: LayoutNode): FlatLayoutNode[];
+/** A window found in a pruned layout tree. */
+interface LayoutWindow {
+    windowId: number;
+    /** Bundle owning the window, when uitest reports one. */
+    bundle?: string;
+    /** Bounds [x1,y1,x2,y2] normalized to 0–1 of the display. */
+    b?: [number, number, number, number];
+}
+/** The windows in a pruned layout tree, in paint order. Pure. */
+declare function listLayoutWindows(tree: LayoutNode): LayoutWindow[];
+/**
+ * The part of a pruned tree that belongs to window `windowId`, under an empty
+ * root like a full dump's, or null when the window is not in the tree. Windows
+ * nested inside it are left out. Pure.
+ */
+declare function windowSubtree(tree: LayoutNode, windowId: number): LayoutNode | null;
+/** The same as {@link windowSubtree}, on a raw (unpruned) `uitest dumpLayout` tree. */
+declare function rawWindowSubtree(tree: RawLayoutNode, windowId: number): RawLayoutNode | null;
+/** The error for a `--window` that is not in the layout, listing the windows that are. */
+declare function windowNotFoundError(windows: readonly LayoutWindow[], windowId: number): OniroError;
 /** Selects layout nodes by what an agent can read off the screen. */
 interface LayoutSelector {
     /** Matches `text`, `desc`, or `hint`: case-insensitive exact matches win; otherwise substring matches. */
@@ -1453,8 +2210,18 @@ interface LayoutSelector {
     /** Restricts to a component type (e.g. `Button`, `TextInput`); case-insensitive. */
     type?: string;
 }
-/** Throw unless `selector` constrains something: a non-blank text, an id, or a type. */
-declare function assertLayoutSelector(selector: LayoutSelector): void;
+/**
+ * What to look for: the plain `--target` fields ({@link LayoutSelector}) or a
+ * parsed `--selector` expression ({@link ElementSelector}: the attribute DSL or XPath).
+ */
+type ElementQuery = LayoutSelector | ElementSelector;
+/** The query is a parsed `--selector` expression rather than plain `--target` fields. */
+declare function isElementSelector(q: ElementQuery): q is ElementSelector;
+/**
+ * Throw unless `selector` constrains something: a non-blank text, an id, or a
+ * type. A parsed {@link ElementSelector} always does.
+ */
+declare function assertLayoutSelector(selector: ElementQuery): void;
 /**
  * The tree without the windows owned by `bundle` — e.g. the soft keyboard, whose
  * keys ("Done", "9") would otherwise match element selectors. Pure.
@@ -1464,9 +2231,11 @@ declare function withoutWindow(tree: LayoutNode, bundle: string): LayoutNode;
  * Find the nodes matching `selector` in a pruned layout tree, in paint order.
  * For `text`, exact (case-insensitive, trimmed) matches are returned when any
  * exist; otherwise substring matches. Covered nodes are included — callers
- * decide what to do with them (see {@link pickTarget}).
+ * decide what to do with them (see {@link pickTarget}). A parsed
+ * {@link ElementSelector} returns every match ({@link matchSelector}); its
+ * index suffix is applied by {@link pickTarget} and {@link findVisibleMatch}.
  */
-declare function findLayoutNodes(tree: LayoutNode, selector: LayoutSelector): FlatLayoutNode[];
+declare function findLayoutNodes(tree: LayoutNode, selector: ElementQuery): FlatLayoutNode[];
 /** One-line summary of a node, used in errors and logs. */
 declare function describeLayoutNode(n: FlatLayoutNode): string;
 /** Why {@link pickTarget} could not choose a node. */
@@ -1475,18 +2244,34 @@ declare class TargetNotFoundError extends OniroError {
     readonly reason: PickTargetFailure;
     constructor(message: string, reason: PickTargetFailure);
 }
+/**
+ * The first uncovered node matching `selector`, or null. When a DSL selector
+ * carries an index (`[n]`), only that match counts, and only while uncovered.
+ */
+declare function findVisibleMatch(tree: LayoutNode, selector: ElementQuery): FlatLayoutNode | null;
 /**
  * Choose the single node to act on for `selector`. Covered nodes are skipped;
  * clickable matches are preferred over plain ones (a "Sign in" Button over the
  * "Sign in" title); a match nested inside another clickable match collapses
  * into it. `index` picks among what remains, in paint order. Throws
  * {@link TargetNotFoundError} when nothing (or more than one node) qualifies.
+ *
+ * For a parsed selector with an index (the DSL's `[n]` suffix, or `index`),
+ * the index picks from every match in paint order, the list
+ * `dump layout --selector` prints, and that element must be on screen and
+ * uncovered; the preferences above do not apply.
  */
-declare function pickTarget(tree: LayoutNode, selector: LayoutSelector, index?: number): FlatLayoutNode;
+declare function pickTarget(tree: LayoutNode, selector: ElementQuery, index?: number): FlatLayoutNode;
 interface DumpLayoutOptions {
     config: ConfigProvider;
     /** Filter to a single window/bundle (`uitest dumpLayout -b '<bundle>'`). */
     bundleName?: string;
+    /**
+     * Keep only this window (an id from `dump windows`, or a `windowId` in the
+     * layout). The whole screen is still dumped, so overlays from other windows
+     * still mark nodes covered and the soft keyboard is still detected.
+     */
+    windowId?: number;
     /** When false, return the parsed-but-unpruned tree. Default true. */
     prune?: boolean;
     /**
@@ -1504,6 +2289,33 @@ interface DumpLayoutOptions {
  */
 declare function dumpLayout(opts: DumpLayoutOptions): Promise<DumpLayoutResult>;
 
+/** A row of the `hidumper -s WindowManagerService -a -a` window table. */
+interface WindowInfo {
+    /** `WinId`: what `--window` takes, and the `windowId` in `dump layout`. */
+    id: number;
+    /** `WindowName`, which hidumper cuts to 20 characters. */
+    name: string;
+    displayId: number;
+    pid: number;
+    /** Window type: 1 is an app's main window; 2000 and up are system windows. */
+    type: number;
+    /** Stacking order; -1 for a window that is not shown. */
+    zOrder: number;
+    /** [x, y, width, height] in device pixels. */
+    rect?: [number, number, number, number];
+    /** It is the `Focus window`. */
+    focused: boolean;
+}
+/** Parse the window table of `hidumper -s WindowManagerService -a -a`. Pure. */
+declare function parseWindowList(raw: string): WindowInfo[];
+interface ListWindowsOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    logger?: Logger;
+}
+/** List the device's windows (shown ones first, in the order hidumper prints them). */
+declare function listWindows(opts: ListWindowsOptions): Promise<WindowInfo[]>;
+
 /**
  * Extract input-method bundle names from `hidumper -s 3703 -a -a` output, whose
  * `imeList` entries look like `"ime": "com.example.kikakeyboard/ServiceExtAbility"`.
@@ -1527,6 +2339,12 @@ declare function findKeyboardWindow(tree: LayoutNode, imeBundles: readonly strin
 
 /** `uitest uiInput` actions plus the composite ones built on top of them. */
 type UiInputType = InputType | 'clearText' | 'hideKeyboard';
+/**
+ * What selectors search (input, wait, screenshot and `dump layout --selector`):
+ * the tree minus the soft-keyboard window, whose keys are not targets, unless
+ * the caller restricted the dump to one window, which is then the one asked for.
+ */
+declare function selectableTree(layout: DumpLayoutResult, windowId?: number): DumpLayoutResult['tree'];
 interface DeviceOptions {
     config: ConfigProvider;
     deviceSerial?: string;
@@ -1538,9 +2356,12 @@ interface DeviceOptions {
  */
 declare function hideKeyboard(opts: DeviceOptions): Promise<boolean>;
 interface LocateTargetOptions extends DeviceOptions {
-    selector: LayoutSelector;
+    /** `--target` fields, or a parsed `--selector` expression (see {@link parseSelector}). */
+    selector: ElementQuery;
     /** Picks among several matching elements (see {@link pickTarget}). */
     index?: number;
+    /** Only look in this window (see {@link DumpLayoutOptions.windowId}). */
+    windowId?: number;
     /**
      * When the soft keyboard is up and the target is missing, covered, or matches
      * only a non-clickable label (the button may be hidden below the keyboard),
@@ -1576,10 +2397,12 @@ interface PerformInputOptions extends DeviceOptions {
     /** End point as 0–1 fractions of the display. */
     fx2?: number;
     fy2?: number;
-    /** Start point: the center of the element matching this selector. */
-    target?: LayoutSelector;
+    /** Start point: the center of the element matching this selector (`--target` fields or a parsed `--selector`). */
+    target?: ElementQuery;
     /** Picks among several elements matching `target`. */
     targetIndex?: number;
+    /** Look for `target` only in this window. */
+    windowId?: number;
     /** Velocity for swipe/drag/fling. */
     speed?: number;
     /** Key for keyEvent (see `resolveKeyEvent`). */
@@ -1608,7 +2431,10 @@ interface PerformInputResult {
  */
 declare function performInput(opts: PerformInputOptions): Promise<PerformInputResult>;
 interface WaitForTargetOptions extends DeviceOptions {
-    selector: LayoutSelector;
+    /** `--target` fields, or a parsed `--selector` expression. */
+    selector: ElementQuery;
+    /** Only look in this window; while it is not on screen nothing matches. */
+    windowId?: number;
     /** Wait until no uncovered element matches, instead of until one does. */
     gone?: boolean;
     timeoutMs: number;
@@ -1619,7 +2445,8 @@ interface WaitForTargetOptions extends DeviceOptions {
 /**
  * Poll the layout until an uncovered element matches `selector` (resolving with
  * it), or with `gone`, until none does (resolving null). Keys on the soft
- * keyboard are ignored. Throws on timeout.
+ * keyboard are ignored. A DSL selector's `[n]` waits for that match. Throws on
+ * timeout.
  */
 declare function waitForTarget(opts: WaitForTargetOptions): Promise<FlatLayoutNode | null>;
 
@@ -1928,6 +2755,300 @@ interface DumpLogOptions {
  */
 declare function dumpLog(opts: DumpLogOptions): Promise<HilogEntry[]>;
 
+/** The power manager's state, as `hidumper -s 3301` prints it: AWAKE, DIM, INACTIVE, SLEEP, … */
+declare function parsePowerState(hidumperOutput: string): string | null;
+/** The SceneBoard lock screen is on top: its root component is in the layout. */
+declare function isLockScreenShown(tree: LayoutNode): boolean;
+interface WakeScreenOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    logger?: Logger;
+}
+interface WakeScreenResult {
+    /** The device was not AWAKE and `power-shell wakeup` was sent. */
+    woke: boolean;
+    /** The lock screen was swiped away. */
+    unlocked: boolean;
+    /** The lock screen is still shown after the swipe: it needs a PIN, password or pattern. */
+    locked: boolean;
+}
+/**
+ * Turn the screen on and swipe away a lock screen that has no credential, so UI
+ * tests and input reach the app. A lock screen that asks for a credential stays
+ * (`locked: true`). Best effort: a check that fails is treated as "nothing to do".
+ */
+declare function wakeAndUnlock(opts: WakeScreenOptions): Promise<WakeScreenResult>;
+/**
+ * Keep the screen on for `ms` (`power-shell timeout -o`), so a long run does not
+ * let it turn off; returns a function that restores the configured timeout.
+ */
+declare function holdScreenOn(opts: WakeScreenOptions & {
+    ms: number;
+}): Promise<() => Promise<void>>;
+
+type Box = [number, number, number, number];
+/** Window name used for nodes outside any bundle window. */
+declare const NO_WINDOW = "(none)";
+/** Counts for one window of a layout. */
+interface LayoutWindowSummary {
+    /** Bundle owning the window, or `(none)` for nodes outside any bundle window. */
+    window: string;
+    /** Pruned elements in the window. */
+    elements: number;
+    /** Elements that carry something to read: text, description, placeholder, or an image. */
+    content: number;
+    /** Clickable elements. */
+    clickable: number;
+    /** Elements with non-empty text. */
+    text: number;
+}
+interface LayoutSummary {
+    display: DumpLayoutResult['display'];
+    windows: LayoutWindowSummary[];
+    /** The same counts over the whole layout. */
+    total: Omit<LayoutWindowSummary, 'window'>;
+    /** Present when the dump detected the soft keyboard. */
+    keyboard?: DumpLayoutResult['keyboard'];
+}
+/** Per-window element, content, clickable and text counts of a pruned layout. Pure. */
+declare function summarizeLayout(layout: DumpLayoutResult): LayoutSummary;
+/** How a baseline element was paired with a current one. */
+type LayoutMatchKind = 'id' | 'key' | 'text' | 'type';
+/** The identifying fields of an element, as reported in a diff. */
+interface LayoutDiffNode {
+    window?: string;
+    type?: string;
+    id?: string;
+    key?: string;
+    text?: string;
+    desc?: string;
+    hint?: string;
+    /** Bounds as 0-1 fractions of the display. */
+    b?: Box;
+}
+interface LayoutMatch {
+    by: LayoutMatchKind;
+    baseline: LayoutDiffNode;
+    current: LayoutDiffNode;
+    /** Intersection over union of the two boxes (1 = same place and size). */
+    iou: number;
+    /** Fields whose value differs (`text`, `type`, `click`, `disabled`, `checked`, …). */
+    changed: string[];
+}
+interface LayoutDiff {
+    /**
+     * 0-1: the sum, over matched pairs, of their IoU (halved when a field
+     * changed), divided by matched + missing + extra. 1 = the same layout.
+     */
+    similarity: number;
+    matched: LayoutMatch[];
+    /** Baseline elements with no counterpart now. */
+    missing: LayoutDiffNode[];
+    /** Current elements with no counterpart in the baseline. */
+    extra: LayoutDiffNode[];
+    /** Matched pairs that moved (IoU under 0.9) or changed a field. */
+    moved: number;
+    changed: number;
+    counts: {
+        baseline: number;
+        current: number;
+    };
+}
+/** Matched pairs with an IoU under this are reported as moved. */
+declare const LAYOUT_MOVED_IOU = 0.9;
+/** Intersection over union of two 0-1 boxes; 1 when neither has a box, 0 when only one has. */
+declare function boxIoU(a: Box | undefined, b: Box | undefined): number;
+/** Accept a `dump layout` result, or a bare pruned tree. Throws on a `--raw` dump. */
+declare function parseLayoutBaseline(json: unknown): DumpLayoutResult;
+/**
+ * Compare two pruned layouts. Elements are paired within the same window by
+ * id, then key, then label (text, description or placeholder) and type, then
+ * type with overlapping boxes; each rule pairs greedily by highest IoU. Boxes
+ * are the dump's 0-1 fractions of the display, so layouts from screens of
+ * different resolution compare. Pure.
+ */
+declare function diffLayouts(baseline: DumpLayoutResult, current: DumpLayoutResult): LayoutDiff;
+
+/** A decoded 8-bit greyscale image, row-major, one byte per pixel. */
+interface GreyImage {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/** Bits in a {@link pHash} / {@link dHash}. */
+declare const HASH_BITS = 64;
+/** A frame whose pHash is this close to a flat frame's is blank (deveco-cli's threshold)… */
+declare const BLANK_PHASH_DISTANCE = 10;
+/**
+ * …provided its grey levels barely vary. A pattern that varies in one
+ * direction only (full-width bands) also has a sparse DCT and hashes close to
+ * flat, so the hash alone is not enough.
+ */
+declare const BLANK_MAX_STDDEV = 10;
+/**
+ * A frame where at least this share of the app area is the background colour
+ * is blank, whatever its hash says. A "Hello World" page leaves about 1 % of
+ * the area as ink, so the bar sits well above it.
+ */
+declare const BLANK_BACKGROUND_SHARE = 0.998;
+/**
+ * Resample to `width`x`height` by area averaging (each output pixel is the
+ * mean of the source pixels it covers), which keeps thin features such as text
+ * as a faint mark instead of dropping them.
+ */
+declare function resizeGrey(img: GreyImage, width: number, height: number): GreyImage;
+/** The rows from `top` to `bottom` (fractions 0-1 of the height). */
+declare function cropRows(img: GreyImage, top: number, bottom: number): GreyImage;
+/** Hamming distance between two equal-length hex hashes (0 = identical, 64 = every bit differs). */
+declare function hammingDistance(a: string, b: string): number;
+/**
+ * 64-bit DCT perceptual hash as 16 hex digits: the image reduced to 32x32, its
+ * orthonormal DCT, the 8x8 lowest frequencies compared with their median (the
+ * DC term left out of the median). Coefficients under one grey level count as
+ * zero, so a flat frame with compression noise still hashes as flat.
+ */
+declare function pHash(img: GreyImage): string;
+/**
+ * 64-bit difference hash as 16 hex digits: the image reduced to 9x8, one bit
+ * per horizontally adjacent pair (left brighter than right). Cheaper than the
+ * pHash and more sensitive to small shifts.
+ */
+declare function dHash(img: GreyImage): string;
+/** pHash of a flat (single-colour) frame; every flat frame hashes the same. */
+declare function flatFrameHash(): string;
+/**
+ * Share (0-1) of pixels whose grey level moved by more than `threshold`
+ * (default 24 of 255), with both images reduced to a common thumbnail.
+ */
+declare function pixelChangeRatio(a: GreyImage, b: GreyImage, threshold?: number): number;
+interface ImageComparison {
+    /** pHash Hamming distance, 0-64 (0 = perceptually identical). */
+    phashDistance: number;
+    /** dHash Hamming distance, 0-64. */
+    dhashDistance: number;
+    /** Share (0-1) of pixels that changed by more than 24 grey levels. */
+    pixelChangeRatio: number;
+    /** The two images have different dimensions (compared after scaling to a common size). */
+    sizeMismatch: boolean;
+    /** Both hashes within 4 bits and under 1 % of pixels changed. */
+    same: boolean;
+}
+/** Thresholds behind {@link ImageComparison.same}. */
+declare const SAME_MAX_HASH_DISTANCE = 4;
+declare const SAME_MAX_CHANGE_RATIO = 0.01;
+/** Compare two screenshots: perceptual-hash distances plus the share of pixels that changed. */
+declare function compareImages(baseline: GreyImage, current: GreyImage): ImageComparison;
+interface BlankAnalysis {
+    /** The app area shows nothing: flat by pHash with little variance, or almost all one colour. */
+    blank: boolean;
+    /** Share (0-1) of the app area within 24 grey levels of its dominant colour; 1 = a flat frame. */
+    blankScore: number;
+    /** pHash Hamming distance from a flat frame (0-64); at most 10 is blank. */
+    phashDistance: number;
+    /** Standard deviation of the app area's grey levels (0 = flat). */
+    stdDev: number;
+    /** The dominant grey level (0-255) of the app area. */
+    background: number;
+}
+/**
+ * Whether a screenshot shows a blank app: the status and navigation bars are
+ * cropped off (top 6 %, bottom 4 %), then the frame is blank when its pHash is
+ * within {@link BLANK_PHASH_DISTANCE} bits of a flat frame's and its standard
+ * deviation is at most {@link BLANK_MAX_STDDEV}, or when at least
+ * {@link BLANK_BACKGROUND_SHARE} of it is the dominant colour.
+ */
+declare function analyzeBlank(img: GreyImage): BlankAnalysis;
+
+/** Default wait between the process appearing and the screenshot. */
+declare const DEFAULT_SMOKE_DELAY_MS = 2000;
+/** Default deadline for the process to appear after launch. */
+declare const DEFAULT_SMOKE_PID_TIMEOUT_MS = 10000;
+/** Decodes a JPEG screenshot to greyscale. Core decodes no images; the CLI passes a sharp-based one. */
+type GreyscaleDecoder = (jpeg: Buffer) => Promise<GreyImage>;
+/** What a {@link SmokeCrashProbe} is asked: was there a crash of `bundle` since `since`? */
+interface SmokeCrashProbeArgs {
+    config: ConfigProvider;
+    bundle: string;
+    /** When the launch started; only crashes at or after it count. */
+    since: Date;
+    /**
+     * Whether the launched process is still the one that started. A probe can
+     * wait for a faultlog when it is not (hiview writes it seconds after the
+     * death) and look only once when it is.
+     */
+    alive: boolean;
+    deviceSerial?: string;
+    logger?: Logger;
+}
+/**
+ * Crash-detection hook. Resolve a description of the newest crash (cpp_crash,
+ * js_crash, app_freeze, …) of the bundle since the launch, or null when there
+ * was none. The CLI passes the faultlog reader (`latestCrash`). A probe that
+ * throws is logged and counts as no crash.
+ */
+type SmokeCrashProbe<C = unknown> = (args: SmokeCrashProbeArgs) => Promise<C | null>;
+interface SmokeCheckOptions<C = unknown> {
+    config: ConfigProvider;
+    bundle: string;
+    /** When the launch was issued (crash window start). Default: when the check starts. */
+    since?: Date;
+    /** Wait between the process appearing and the screenshot. Default {@link DEFAULT_SMOKE_DELAY_MS}. */
+    delayMs?: number;
+    /** Deadline for the process to appear. Default {@link DEFAULT_SMOKE_PID_TIMEOUT_MS}. */
+    pidTimeoutMs?: number;
+    /** Where to write the screenshot JPEG. When omitted it is analysed but not kept. */
+    screenshotPath?: string;
+    /** Turns the JPEG into greyscale for the blank check; without it `blankScreen` is null. */
+    decodeGreyscale?: GreyscaleDecoder;
+    /** Crash-detection hook; see {@link SmokeCrashProbe}. Without it `crash` is null. */
+    crashProbe?: SmokeCrashProbe<C>;
+    deviceSerial?: string;
+    logger?: Logger;
+}
+interface SmokeResult<C = unknown> {
+    /** All checks passed: the process came up and stayed up, the screen is not blank, no crash. */
+    passed: boolean;
+    /** Why it failed, one line per failed check; empty when it passed. */
+    failures: string[];
+    /** Pid seen after launch, or null when the process never appeared. */
+    pid: number | null;
+    /** The process seen after launch was still running (same pid) after the delay. */
+    alive: boolean;
+    /** Pid after the delay when it differs from `pid` (the app died and was restarted), else absent. */
+    pidAfter?: number | null;
+    /** The app area is a flat frame; null when no decoder was given or the screenshot failed. */
+    blankScreen: boolean | null;
+    /** Share (0-1) of the app area in its dominant colour; 1 = flat. Null with `blankScreen`. */
+    blankScore: number | null;
+    /** The blank-check measurements (pHash distance from a flat frame, standard deviation, background). */
+    blank?: BlankAnalysis;
+    /** Path of the saved screenshot, or null when none was kept. */
+    screenshot: string | null;
+    /** The crash probe's finding, or null (no crash, or no probe). */
+    crash: C | null;
+    /** Whether a crash probe ran; `crash: null` without one means "not checked". */
+    crashChecked: boolean;
+    delayMs: number;
+}
+/** Combine the observations into a verdict. Pure. */
+declare function smokeVerdict(o: {
+    pid: number | null;
+    alive: boolean;
+    blankScreen: boolean | null;
+    crash: unknown;
+}): {
+    passed: boolean;
+    failures: string[];
+};
+/**
+ * Smoke-check a just-launched app: wait for its process, let it settle for
+ * `delayMs`, capture a screenshot and judge it against a flat frame, check the
+ * process is still the same one, and ask the crash probe (when given) for a
+ * crash since launch. Never throws for a failed check — the verdict is in the
+ * result; it throws only when the device cannot be reached.
+ */
+declare function smokeCheck<C = unknown>(opts: SmokeCheckOptions<C>): Promise<SmokeResult<C>>;
+
 interface RunHvigorwOptions {
     config: ConfigProvider;
     projectDir: string;
@@ -1985,9 +3106,17 @@ interface DiscoverHapsOptions {
     /** Max directory recursion depth. Default 8. */
     maxDepth?: number;
 }
+/**
+ * A module's test HAP (`<module>-ohosTest-{signed,unsigned}.hap`, built from
+ * `src/ohosTest`). Its filename starts with the module name, so without this it
+ * would be grouped with the module's own HAPs, and, being built last by
+ * `oniro-app test`, picked over them for install.
+ */
+declare function isTestHap(hapFileName: string): boolean;
 /**
  * Walk a project's build outputs and group `*-signed.hap` / `*-unsigned.hap`
- * by build module name (parsed from the HAP filename). Skips `node_modules` /
+ * by build module name (parsed from the HAP filename). Test HAPs
+ * (`*-ohosTest-*.hap`, see {@link isTestHap}) are left out. Skips `node_modules` /
  * `oh_modules` / `.git`, and, when `projectDir` is an app project root, any
  * other app project nested inside it, whose HAPs belong to another app.
  * Ported from the proven MCP `findHaps`, extended with per-module grouping so
@@ -2112,55 +3241,266 @@ interface RunCodelinterOptions {
 declare function runCodelinter(opts: RunCodelinterOptions): Promise<CodelinterResult>;
 
 /**
- * A hint for build output whose cause the compiler errors do not name, or
- * undefined. Pure/testable.
- */
-declare function diagnoseBuildFailure(output: string): string | undefined;
-interface BuildHapOptions {
-    config: ConfigProvider;
-    projectDir: string;
-    product?: string;
-    module?: string;
-    /** Forwarded as hvigor `buildMode` (e.g. release, debug). */
-    mode?: string;
-    /** hvigor task. Default `assembleHap`. */
+ * Where a diagnostic comes from: the ArkTS compiler, hvigor itself (configuration
+ * and task errors), the native toolchain (clang, lld), ohpm, the SDK the project
+ * compiles against, the signing material (a signingConfig for the other runtime),
+ * or `check arkts`.
+ */
+type DiagnosticSource = 'arkts' | 'hvigor' | 'native' | 'ohpm' | 'sdk' | 'signing' | 'arkts-check';
+/** One error or warning, in a shape shared by `build --json` and `check arkts --json`. */
+interface BuildDiagnostic {
+    severity: 'error' | 'warning';
+    source: DiagnosticSource;
+    /** The tool's code: eight digits for hvigor, ArkTS and ohpm (e.g. `10605008`). */
+    code?: string;
+    /** The ArkTS linter rule, e.g. `arkts-no-any-unknown`. */
+    rule?: string;
+    message: string;
+    /** Relative to the project root when the file lies inside it, else absolute. */
+    file?: string;
+    line?: number;
+    column?: number;
+    /** The hvigor task that reported it, e.g. `:entry:default@CompileArkTS`. */
     task?: string;
-    /** Run `ohpm install --all` first when `oh_modules/` is missing. Default true. */
-    autoInstallDeps?: boolean;
-    /** Build modules in parallel. Default true (see runHvigorw). */
-    parallel?: boolean;
-    abortSignal?: AbortSignal;
-    onOutput?: (chunk: string, stream: 'stdout' | 'stderr') => void;
-    logger?: Logger;
-}
-interface BuildHapResult {
-    exitCode: number;
-    durationMs: number;
-    /** Built HAPs grouped by module folder. */
-    discoveredHaps: Record<string, ModuleHaps>;
-    warnings: string[];
+    /** For `sdk` diagnostics: the API level the build needs. */
+    api?: string;
+}
+interface ParsedBuildOutput {
+    /** The first hvigor task reported as failed. */
+    failedTask?: string;
+    diagnostics: BuildDiagnostic[];
+    /** hvigor's own `COMPILE RESULT` counts. They can exceed the distinct diagnostics, so are a cross-check only. */
+    reportedErrors?: number;
+    reportedWarnings?: number;
+}
+/** Build output as plain lines: colour codes stripped and, of a line redrawn with `\r`, its last state. */
+declare function cleanBuildOutput(output: string): string[];
+/** The last `n` lines of build output, cleaned. */
+declare function buildOutputTail(output: string, n?: number): string;
+/**
+ * Parse hvigor build output (stdout and stderr together, ANSI codes and all) into
+ * diagnostics. Pure/testable. Understands the ArkTS compiler's coded and located
+ * blocks, hvigor's coded configuration and task errors, clang and lld output from
+ * a native build, and ohpm's coded errors. hvigor prints the ArkTS block twice, so
+ * diagnostics are de-duplicated; `projectDir` makes paths inside it relative.
+ */
+declare function parseBuildOutput(output: string, opts?: {
+    projectDir?: string;
+}): ParsedBuildOutput;
+/** A symbol the compiler says a kit or `@ohos.*` module does not export. */
+interface MissingSdkSymbol {
+    symbol: string;
+    module: string;
 }
+/** The kit/`@ohos` symbols that diagnostics report missing, de-duplicated. Pure. */
+declare function missingSdkSymbols(diagnostics: readonly BuildDiagnostic[]): MissingSdkSymbol[];
 /**
- * High-level build orchestration: ensure deps → run hvigorw → discover the
- * produced HAPs. The single call the CLI and MCP want; `runHvigorw` stays a raw
- * single-spawn primitive.
+ * When the build failed on kit or `@ohos` symbols that a newer installed SDK
+ * declares, one `sdk` diagnostic naming the API level that has them all (#22);
+ * otherwise null. `sdkHome` holds one folder per API level; `projectApi` is the
+ * project's compileSdkVersion. Best effort: it reads declaration files and does
+ * not know about SDKs that are not installed.
  */
-declare function buildHap(opts: BuildHapOptions): Promise<BuildHapResult>;
-
+declare function sdkTooOldDiagnostic(diagnostics: readonly BuildDiagnostic[], sdkHome: string, projectApi: number | undefined): BuildDiagnostic | null;
 /**
- * Conservative project-folder-name validator (no path separators, conservative charset).
+ * The package an `oh_modules/` path belongs to, e.g. `@ohos/flutter_ohos` for
+ * `oh_modules/.ohpm/@ohos+flutter_ohos@1.0.0/oh_modules/@ohos/flutter_ohos/src/…`.
  */
-declare function isValidProjectName(name: string): boolean;
+declare function ohModulesPackage(file: string): string | undefined;
 /**
- * Bundle-name validator. Allows reverse-DNS style identifiers like `com.example.myapp`.
+ * A hint when the ArkTS errors are missing properties or names inside
+ * `oh_modules/`: a dependency calling an API newer than the SDK the build used
+ * (#22). Message-level only; it does not read the dependencies. `sdkLabel` names
+ * that SDK (`HarmonyOS 5.1.0 (API 18) at …`) and `remedy` how to get a newer one.
+ * Null when no such error is there.
  */
-declare function isValidBundleName(bundleName: string): boolean;
+declare function dependencyApiDiagnostic(diagnostics: readonly BuildDiagnostic[], sdkLabel: string | undefined, remedy: string): BuildDiagnostic | null;
 
-interface TemplateOption {
-    id: string;
-    label: string;
-    description: string;
-    defaultModuleName: string;
+/**
+ * Which runtime a project targets. OpenHarmony projects build against the public
+ * OpenHarmony SDK; HarmonyOS projects build against Huawei's HarmonyOS SDK and
+ * need an AGC-issued certificate to sign (see `harmonyos/signing`).
+ */
+type RuntimeOs = 'OpenHarmony' | 'HarmonyOS';
+/**
+ * Detect the runtime a project targets from `build-profile.json5`.
+ *
+ * HarmonyOS only when the product declares `runtimeOS: "HarmonyOS"`, which DevEco
+ * Studio writes for every HarmonyOS project. Anything else — no such field, or a
+ * missing or unreadable profile — is OpenHarmony, so existing projects behave
+ * exactly as they did before HarmonyOS support. Reads the named product, else the
+ * first one.
+ */
+declare function detectRuntimeOs(projectDir: string, productName?: string): RuntimeOs;
+/**
+ * HarmonyOS SDK releases, mapping API level to the release version DevEco writes
+ * into `compileSdkVersion`, for when the installed SDK does not name the requested
+ * level itself. Only releases read from a real `sdk/default/sdk-pkg.json` are listed.
+ */
+declare const HARMONYOS_SDK_VERSIONS: ReadonlyMap<number, string>;
+/**
+ * The `"<version>(<api>)"` label a HarmonyOS product declares for an API level, or
+ * undefined when no HarmonyOS release is known for it.
+ */
+declare function harmonyOsSdkLabelForApi(api: number): string | undefined;
+
+/** The SDK a build compiles against, as `build --json` reports it (#22). */
+interface BuildSdk {
+    runtimeOS: RuntimeOs;
+    /** e.g. `HarmonyOS 6.1.1`, `OpenHarmony 5.1.0`. */
+    displayName?: string;
+    /** The release as the SDK names it: `6.1.1(24)` for HarmonyOS, the build (`5.1.0.107`) for OpenHarmony. */
+    version?: string;
+    /** e.g. `24`. */
+    api?: string;
+    /** The SDK directory: `DEVECO_SDK_HOME` for HarmonyOS, `<sdk home>/<api>` for OpenHarmony. */
+    path: string;
+}
+/**
+ * The SDK a build of `projectDir` uses, found the way the build finds it: the
+ * HarmonyOS SDK for a HarmonyOS product, else the OpenHarmony API folder for the
+ * project's compileSdkVersion. Undefined when it cannot be told.
+ */
+declare function resolveBuildSdk(opts: {
+    config: ConfigProvider;
+    projectDir: string;
+    runtimeOS: RuntimeOs;
+    logger?: Logger;
+}): BuildSdk | undefined;
+/** `HarmonyOS 5.1.0 (API 18) at <path>`. */
+declare function describeBuildSdk(sdk: BuildSdk): string;
+
+/**
+ * A hint for build output whose cause the compiler errors do not name, or
+ * undefined. Pure/testable. A symbol missing from a kit reads as a system API
+ * unless `newerSdkHasIt`, when a newer installed SDK declares it (see
+ * {@link sdkTooOldDiagnostic}).
+ */
+declare function diagnoseBuildFailure(output: string, newerSdkHasIt?: boolean): string | undefined;
+interface BuildHapOptions {
+    config: ConfigProvider;
+    projectDir: string;
+    product?: string;
+    module?: string;
+    /** Forwarded as hvigor `buildMode` (e.g. release, debug). */
+    mode?: string;
+    /** hvigor task. Default `assembleHap`. */
+    task?: string;
+    /** Run `ohpm install --all` first when `oh_modules/` is missing. Default true. */
+    autoInstallDeps?: boolean;
+    /** Build modules in parallel. Default true (see runHvigorw). */
+    parallel?: boolean;
+    abortSignal?: AbortSignal;
+    onOutput?: (chunk: string, stream: 'stdout' | 'stderr') => void;
+    logger?: Logger;
+}
+interface BuildSummary {
+    /** Distinct error diagnostics. */
+    errors: number;
+    /** Distinct warning diagnostics. */
+    warnings: number;
+    /** hvigor's `COMPILE RESULT` error count, which can exceed `errors`. */
+    reportedErrors?: number;
+    reportedWarnings?: number;
+}
+interface BuildHapResult {
+    exitCode: number;
+    durationMs: number;
+    /** Built HAPs grouped by module folder. */
+    discoveredHaps: Record<string, ModuleHaps>;
+    warnings: string[];
+    /** Compiler warnings (and errors, for a failed build) parsed from the output. */
+    diagnostics: BuildDiagnostic[];
+    summary: BuildSummary;
+    /** The SDK the build compiled against, when it could be told. */
+    sdk?: BuildSdk;
+}
+/**
+ * The build ran and failed: hvigor (or the `ohpm install` before it) exited
+ * non-zero. Carries what {@link parseBuildOutput} found, so callers need not
+ * scrape the output.
+ */
+declare class BuildFailedError extends OniroError {
+    readonly exitCode: number;
+    readonly diagnostics: BuildDiagnostic[];
+    readonly summary: BuildSummary;
+    readonly rawTail: string;
+    readonly failedTask?: string | undefined;
+    readonly hint?: string | undefined;
+    /** The SDK hvigor compiled against, when it could be told (not for an ohpm failure). */
+    sdk?: BuildSdk;
+    constructor(message: string, exitCode: number, diagnostics: BuildDiagnostic[], summary: BuildSummary, rawTail: string, failedTask?: string | undefined, hint?: string | undefined, cause?: unknown);
+}
+/**
+ * High-level build orchestration: ensure deps → run hvigorw → discover the
+ * produced HAPs. The single call the CLI and MCP want; `runHvigorw` stays a raw
+ * single-spawn primitive.
+ */
+declare function buildHap(opts: BuildHapOptions): Promise<BuildHapResult>;
+/** What {@link buildWithDiagnostics} returns: one shape for a build that passed and one that failed. */
+interface BuildReport {
+    ok: boolean;
+    exitCode: number;
+    durationMs: number;
+    /** The first task hvigor reported failed, or `ohpm install --all`. */
+    failedTask?: string;
+    diagnostics: BuildDiagnostic[];
+    summary: BuildSummary;
+    /** Built HAPs grouped by module folder; empty when the build failed. */
+    discoveredHaps: Record<string, ModuleHaps>;
+    warnings: string[];
+    /** The error message the build failed with (what `oniro-app build` prints). */
+    error?: string;
+    /** The SDK the project compiles against is not installed: install it and build again. */
+    missingSdk?: {
+        api: string;
+        version?: string;
+        expectedPath: string;
+    };
+    /**
+     * The SDK hvigor compiled against (`runtimeOS`, `displayName`, `version`, `api`,
+     * `path`), when it could be told. Absent for an ohpm failure or a missing SDK.
+     */
+    sdk?: BuildSdk;
+    /** The last 200 lines of build output, colour codes removed. Empty for a successful build. */
+    rawTail: string;
+}
+/**
+ * {@link buildHap}, but a build that fails returns `ok: false` with the parsed
+ * diagnostics instead of throwing, as does a project whose SDK is not installed
+ * (one `sdk` diagnostic, plus `missingSdk`). Errors that mean the build could not
+ * run at all (no command-line tools, not a project, cancelled) still throw.
+ */
+declare function buildWithDiagnostics(opts: BuildHapOptions): Promise<BuildReport>;
+
+/**
+ * Why the signingConfig a product names cannot sign for the runtime it targets,
+ * or undefined when it can (or names none, or the profile cannot be read).
+ *
+ * A HarmonyOS device accepts only AppGallery Connect material, which
+ * `sign --harmonyos` writes with `type: "HarmonyOS"`, the field hvigor keys on.
+ * Material without it is the OpenHarmony development certificate a plain `sign`
+ * writes, and hvigor's SignHap still signs with it, producing a
+ * `-signed.hap` that only fails at install time (#19). The mirror case, HarmonyOS
+ * material on an OpenHarmony product, is reported too. Reads the named product,
+ * else the first one, like {@link detectRuntimeOs}.
+ */
+declare function signingMismatch(projectDir: string, runtimeOS: RuntimeOs, productName?: string): string | undefined;
+
+/**
+ * Conservative project-folder-name validator (no path separators, conservative charset).
+ */
+declare function isValidProjectName(name: string): boolean;
+/**
+ * Bundle-name validator. Allows reverse-DNS style identifiers like `com.example.myapp`.
+ */
+declare function isValidBundleName(bundleName: string): boolean;
+
+interface TemplateOption {
+    id: string;
+    label: string;
+    description: string;
+    defaultModuleName: string;
 }
 /**
  * Enumerate templates inside `templateRoot`. Each direct subfolder is a template;
@@ -2397,69 +3737,6 @@ declare function bundleNameFromHapConfig(text: string): string | null;
 /** The bundle a HAP installs as, read from its `module.json` or `config.json`; null when neither names one. */
 declare function readHapBundleName(hapPath: string): Promise<string | null>;
 
-/**
- * Which runtime a project targets. OpenHarmony projects build against the public
- * OpenHarmony SDK; HarmonyOS projects build against Huawei's HarmonyOS SDK and
- * need an AGC-issued certificate to sign (see `harmonyos/signing`).
- */
-type RuntimeOs = 'OpenHarmony' | 'HarmonyOS';
-/**
- * Detect the runtime a project targets from `build-profile.json5`.
- *
- * HarmonyOS only when the product declares `runtimeOS: "HarmonyOS"`, which DevEco
- * Studio writes for every HarmonyOS project. Anything else — no such field, or a
- * missing or unreadable profile — is OpenHarmony, so existing projects behave
- * exactly as they did before HarmonyOS support. Reads the named product, else the
- * first one.
- */
-declare function detectRuntimeOs(projectDir: string, productName?: string): RuntimeOs;
-/**
- * HarmonyOS SDK releases, mapping API level to the release version DevEco writes
- * into `compileSdkVersion`, for when the installed SDK does not name the requested
- * level itself. Only releases read from a real `sdk/default/sdk-pkg.json` are listed.
- */
-declare const HARMONYOS_SDK_VERSIONS: ReadonlyMap<number, string>;
-/**
- * The `"<version>(<api>)"` label a HarmonyOS product declares for an API level, or
- * undefined when no HarmonyOS release is known for it.
- */
-declare function harmonyOsSdkLabelForApi(api: number): string | undefined;
-
-/**
- * A HarmonyOS SDK install. Unlike the OpenHarmony SDK, which `oniro-app sdk install`
- * downloads, the HarmonyOS SDK only ships inside DevEco Studio or the login-gated
- * HarmonyOS command-line tools, so oniro-app locates an existing install.
- */
-interface HarmonyOsSdk {
-    /** The directory containing `default/`; hvigor receives it as `DEVECO_SDK_HOME`. */
-    sdkPath: string;
-    /** The DevEco Studio or command-line-tools install holding the SDK, its tools and JBR. */
-    installRoot: string;
-    /** From `default/sdk-pkg.json`, e.g. `HarmonyOS 6.1.1`. */
-    displayName?: string;
-    /**
-     * The release as `compileSdkVersion` names it, e.g. `6.1.1(24)`, from
-     * `default/sdk-pkg.json`. hvigor builds only projects that name this release.
-     */
-    version?: string;
-}
-/**
- * Locate a HarmonyOS SDK, or return null when none is installed.
- *
- * Order: `harmonyosSdkPath` (`ONIRO_HARMONYOS_SDK_PATH`, an install root or its
- * `sdk` directory), then DevEco Studio in its default location, then the
- * command-line tools at `cmdToolsPath` when they are the HarmonyOS edition.
- */
-declare function findHarmonyOsSdk(opts: {
-    config: ConfigProvider;
-    logger?: Logger;
-}): HarmonyOsSdk | null;
-/** Like `findHarmonyOsSdk`, but throws an actionable error when none is installed. */
-declare function requireHarmonyOsSdk(opts: {
-    config: ConfigProvider;
-    logger?: Logger;
-}): HarmonyOsSdk;
-
 type HuaweiSiteCode = 'CN' | 'EU' | 'SG' | 'RU';
 interface HuaweiSite {
     code: HuaweiSiteCode;
@@ -2586,13 +3863,37 @@ interface HarmonyOsSessionOptions {
     logger?: Logger;
     http?: HarmonyOsHttpClient;
     tokenStore?: TokenStore;
-    /** Called with the sign-in URL before the browser opens, so a CLI can print it. */
-    onLoginUrl?: (url: string) => void;
+    /**
+     * Called with the sign-in URL before the browser opens, so a CLI can print it,
+     * and the loopback port the sign-in page will redirect to.
+     */
+    onLoginUrl?: (url: string, info: {
+        port: number;
+    }) => void;
+}
+interface HarmonyOsLoginOptions {
+    /** How long to wait for the sign-in. Default {@link LOGIN_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /**
+     * Loopback port the sign-in page redirects to. Default: one the OS assigns. Fix
+     * it to forward the port from the machine with the browser beforehand, with
+     * `ssh -L <port>:127.0.0.1:<port>`.
+     */
+    port?: number;
+    /** Default true. False leaves opening the URL (from `onLoginUrl`) to the user. */
+    openBrowser?: boolean;
+    /**
+     * Callback addresses the user pastes, one per item — say, a `readline`
+     * interface over stdin. For a browser on another machine, whose redirect to
+     * this machine's loopback port cannot load: the address it was sent to,
+     * copied from its address bar, completes the sign-in instead. The loopback
+     * listener keeps running alongside, and whichever arrives first wins; a pasted
+     * line that is not this sign-in's callback is reported and the next one read.
+     */
+    pastedCallbacks?: AsyncIterable<string>;
 }
 interface HarmonyOsSession {
-    login(opts?: {
-        timeoutMs?: number;
-    }): Promise<HuaweiUserInfo>;
+    login(opts?: HarmonyOsLoginOptions): Promise<HuaweiUserInfo>;
     /** Resolves false when there was no session to end. */
     logout(): Promise<boolean>;
     /** The signed-in account, or null. `refresh` mints a fresh AGC access token. */
@@ -2646,20 +3947,39 @@ interface SigningMaterialPaths {
     profilePath: string;
 }
 
-/** The fields of a provisioning profile that decide whether it can be reused. */
+/** The fields of a provisioning profile that decide whether it can be reused, and what it allows. */
 interface ProvisionProfileInfo {
+    /** `debug` or `release`. */
+    type?: string;
+    /** Who signed the profile: `app_gallery` for AGC, `pki_internal` for the OpenHarmony SDK's. */
+    issuer?: string;
     bundleName?: string;
-    /** The AGC team the profile was issued to. */
+    /** The AGC team the profile was issued to; `OpenHarmony` for the SDK's. */
     developerId?: string;
+    apl?: string;
+    appFeature?: string;
+    notBefore?: Date;
     notAfter?: Date;
     /** Uppercased UDIDs the debug profile is valid for. */
     deviceIds: string[];
     aclPermissions: string[];
-    /** PEM of the certificate the profile was issued for. */
+    /** PEM of the certificate a debug profile was issued for. */
     developmentCertificate?: string;
+    /** PEM of the certificate a release profile was issued for. */
+    distributionCertificate?: string;
 }
 /** Read a `.p7b` profile; null when it is missing or unreadable, which means "regenerate". */
 declare function readProvisionProfile(profilePath: string): ProvisionProfileInfo | null;
+/** {@link readProvisionProfile} on the bytes of a `.p7b`; null when they hold no profile. */
+declare function parseProvisionProfile(buffer: Buffer): ProvisionProfileInfo | null;
+/** `2026-10-01 11:50 UTC`. */
+declare function formatUtc(date: Date): string;
+/**
+ * The profile's type and expiry, for a one-line summary: `debug, valid until
+ * 2026-10-01 11:50 UTC`, or `debug, expired 2026-10-01 11:50 UTC`. Omits what
+ * the profile does not say.
+ */
+declare function describeProfileValidity(profile: Pick<ProvisionProfileInfo, 'type' | 'notAfter'>, now?: Date): string;
 
 interface HarmonyOsAutoSignOptions {
     config: ConfigProvider;
@@ -2682,6 +4002,10 @@ interface HarmonyOsSigningResult {
     regenerated: boolean;
     /** UDIDs the profile is valid for. */
     deviceIds: string[];
+    /** The profile's type: `debug` for the material AGC issues here. */
+    profileType?: string;
+    /** When the profile expires. AGC debug profiles last 14 days. */
+    notAfter?: Date;
 }
 /**
  * Sign a HarmonyOS project with the signed-in Huawei developer account, the way
@@ -2716,6 +4040,2123 @@ interface HarmonyOsSignHapResult extends HarmonyOsSigningResult {
  */
 declare function harmonyOsSignHap(opts: HarmonyOsSignHapOptions): Promise<HarmonyOsSignHapResult>;
 
+/**
+ * Parser for the output of `aa test … -s unittest OpenHarmonyTestRunner` (the
+ * Hypium runner). Each case prints a block when it starts (`STATUS_CODE: 1`) and
+ * one when it ends, carrying `class=`, `test=`, `stream=` (the failure message),
+ * `stack=` (several lines) and `consuming=` (ms). The run ends with
+ * `OHOS_REPORT_RESULT: stream=Tests run: N, Failure: F, Error: E, Pass: P, Ignore: I`,
+ * `OHOS_REPORT_CODE` and `TestFinished-ResultCode` / `-ResultMsg`.
+ */
+type TestStatus = 'pass' | 'fail' | 'error' | 'ignore' | 'unknown';
+interface TestCaseResult {
+    /** The `describe` name. */
+    suite: string;
+    /** The `it` name. */
+    name: string;
+    status: TestStatus;
+    /** The runner's raw `OHOS_REPORT_STATUS_CODE` for the finished case. */
+    statusCode: number;
+    durationMs?: number;
+    /** The assertion or error message (`stream=`), e.g. `expect 0 equals 3`. */
+    message?: string;
+    /** The JS stack the runner printed, project frames and Hypium frames alike. */
+    stack?: string;
+}
+interface TestSummary {
+    run: number;
+    pass: number;
+    fail: number;
+    error: number;
+    ignore: number;
+}
+interface ParsedTestOutput {
+    tests: TestCaseResult[];
+    /** From `OHOS_REPORT_RESULT`, or counted from `tests` when the runner never printed it. */
+    summary: TestSummary;
+    /** True when `OHOS_REPORT_RESULT` was printed. */
+    summaryReported: boolean;
+    /** `OHOS_REPORT_CODE`: 0 when every case passed, -1 otherwise. */
+    reportCode?: number;
+    /** `TestFinished-ResultCode`: 0 when the run itself completed, whatever the cases did. */
+    resultCode?: number;
+    /** `TestFinished-ResultMsg`, e.g. `The specified module name is not found.` */
+    resultMessage?: string;
+    /** `taskconsuming=`: the whole run, in ms. */
+    durationMs?: number;
+    /** For a dry run (`-s dryRun true`): the suites and their cases, without running them. */
+    dryRun?: Array<{
+        suite: string;
+        name: string;
+    }>;
+}
+/**
+ * The runner's status codes, as observed with Hypium 1.0.24 on OpenHarmony 7.0:
+ * 1 starts a case, 0 passed, -2 an assertion failed, -1 the case threw. -3 is
+ * assumed to mean ignored (the code was not observed); anything else is
+ * reported as `unknown`, with the raw code kept.
+ */
+declare function statusFromCode(code: number): TestStatus;
+/** Parse `aa test` output. Pure. Lines that are not runner markers are ignored. */
+declare function parseTestOutput(output: string): ParsedTestOutput;
+
+interface RunTestsOptions {
+    config: ConfigProvider;
+    projectDir: string;
+    /** The module whose `src/ohosTest` suite runs. Default `entry`. */
+    module?: string;
+    /** hvigor product. Default `default`. */
+    product?: string;
+    /** Run only these: `Suite`, `Suite#case`, or several joined by commas (the runner's `-s class`). */
+    testClass?: string;
+    /** Per-case timeout passed to the runner (`-s timeout`), ms. Default 15000. */
+    caseTimeoutMs?: number;
+    /** Wall-clock limit for the whole `aa test` run, ms; `aa test` can hang when the runner dies. Default 600000. */
+    runTimeoutMs?: number;
+    /** Build the main and test HAPs first. Default true. */
+    build?: boolean;
+    /**
+     * Turn the screen on, swipe away a lock screen without a credential, and keep
+     * the screen on during the run, so UI tests reach the app. Default true.
+     */
+    wakeScreen?: boolean;
+    /** hvigor build mode (e.g. debug). */
+    mode?: string;
+    /** Run `ohpm install --all` first when `oh_modules/` is missing. Default true. */
+    autoInstallDeps?: boolean;
+    deviceSerial?: string;
+    abortSignal?: AbortSignal;
+    /** Build and runner output as it arrives. */
+    onOutput?: OutputSink;
+    logger?: Logger;
+}
+/** How the run ended: every case passed, some case failed or threw, or the run itself did not complete. */
+type TestOutcome = 'passed' | 'failed' | 'runner-error';
+interface TestRunReport {
+    ok: boolean;
+    outcome: TestOutcome;
+    module: string;
+    bundle?: string;
+    /** The test module's name, from `src/ohosTest/module.json5` (`entry_test` in the templates). Left installed. */
+    testModule?: string;
+    tests: TestCaseResult[];
+    summary: TestSummary;
+    /** `TestFinished-ResultCode`: 0 when the run completed, whatever the cases did. */
+    resultCode?: number;
+    resultMessage?: string;
+    /** `OHOS_REPORT_CODE`: 0 when every case passed. */
+    reportCode?: number;
+    haps: {
+        main?: string;
+        test?: string;
+    };
+    /** Why the run did not complete (outcome `runner-error`). */
+    error?: string;
+    /** For a build that failed: its diagnostics and task (see `build --json`). */
+    failedTask?: string;
+    diagnostics?: BuildDiagnostic[];
+    /** hilog lines of the app's processes during the run (last 300): assertion logs, JS crash stacks. */
+    log: string[];
+    /** Things that may explain a failure without being one, e.g. a lock screen that needs a credential. */
+    warnings: string[];
+    durationMs: number;
+    /** The last 200 lines of `aa test` output (or of the build output, when the build failed). */
+    rawTail: string;
+}
+/** Where hvigor writes a module's test HAP for a product. */
+declare function testHapPath(moduleDir: string, module: string, product?: string, signed?: boolean): string;
+/**
+ * The `aa test` command line. Pure. `testClass` is a `Suite`, `Suite#case`, or
+ * a comma-separated list of them; it is quoted for the device shell.
+ */
+declare function aaTestCommand(opts: {
+    bundle: string;
+    testModule: string;
+    caseTimeoutMs?: number;
+    testClass?: string;
+}): string;
+/** The test module name declared in `<moduleDir>/src/ohosTest/module.json5`. */
+declare function readTestModuleName(moduleDir: string): string;
+/** The outcome of a parsed run. Pure. */
+declare function decideOutcome(run: {
+    resultCode?: number;
+    summary: TestSummary;
+    completed: boolean;
+}): {
+    outcome: TestOutcome;
+    error?: string;
+};
+/**
+ * Build a module's main and `ohosTest` HAPs, install both, run the suite with
+ * `aa test` (Hypium's OpenHarmonyTestRunner) and parse the result. Never throws
+ * for a failed test, a failed build or a run that did not complete: those come
+ * back as `outcome` `failed` or `runner-error`. Throws only when it cannot start
+ * (no such module, cancelled).
+ */
+declare function runTests(opts: RunTestsOptions): Promise<TestRunReport>;
+
+/**
+ * `check arkts`: the SDK's own ArkTS checker (ets-loader's `etsStandaloneChecker`,
+ * the type and linter pass `CompileArkTS` runs) plus the ArkUI component-model and
+ * project-config rules hvigor enforces later in a build, without a build. It runs
+ * deveco-cli's `arkts-check.cjs` (MIT, vendored under `vendor/deveco-cli/`, adapted
+ * to take the SDK directory) in a child node process, against the SDK the project
+ * compiles with.
+ */
+/** Where the SDK the checker loads came from. */
+interface ArktsCheckSdk {
+    /** The directory holding `ets/`, `previewer/` and `toolchains/`. */
+    dir: string;
+    runtimeOS: RuntimeOs;
+    /** The project's `compileSdkVersion` API level, for an OpenHarmony project. */
+    api?: number;
+    /** HarmonyOS's `hms/ets`, added to the checker's API paths. */
+    hmsEtsDir?: string;
+}
+interface ArktsCheckSummary {
+    errors: number;
+    warnings: number;
+    fixed: number;
+    /** Source files the checker was given. */
+    files: number;
+    /**
+     * Diagnostics that came from the SDK's ArkTS checker rather than the project rules.
+     * Zero alongside project-rule findings can mean the checker produced nothing, so it
+     * is reported rather than inferred.
+     */
+    checkerDiagnostics: number;
+}
+interface ArktsCheckReport {
+    /** True when the check ran and found no error. */
+    ok: boolean;
+    /** False when the checker could not run or crashed: then nothing is known about the code. */
+    completed: boolean;
+    diagnostics: BuildDiagnostic[];
+    /** Diagnostics `--fix` rewrote away, verified by a re-check. */
+    fixed: BuildDiagnostic[];
+    /** Files `--fix` edited that were not in `files` (an `export` added in the declaring module). */
+    alsoModified: string[];
+    summary: ArktsCheckSummary;
+    sdk?: ArktsCheckSdk;
+    durationMs: number;
+    /** Why the check did not complete. */
+    error?: string;
+}
+interface ArktsCheckOptions {
+    config: ConfigProvider;
+    projectDir: string;
+    /** Check only these `.ets` files (relative to the project or absolute); project-wide rules are skipped. */
+    files?: string[];
+    /** Apply the checker's verified fixes (compiler suggestions, import paths, missing `export`, ...). */
+    fix?: boolean;
+    /** Override the SDK directory (holding `ets/`); by default the one the project compiles with. */
+    sdkDir?: string;
+    /** With `sdkDir`: HarmonyOS's `hms/ets` API directory to add. */
+    hmsEtsDir?: string;
+    /** Kill the checker after this long. Default 300 000 ms. */
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+    logger?: Logger;
+    /** The checker script; tests substitute a stand-in. */
+    scriptPath?: string;
+    /** The node binary that runs it. Default: the one running this process. */
+    nodePath?: string;
+}
+/**
+ * The vendored `arkts-check.cjs`: beside `dist/` once published, two levels up
+ * from `src/check/` in the repo.
+ */
+declare function arktsCheckerScript(): string;
+/**
+ * The SDK `check arkts` loads for a project: for HarmonyOS, the located HarmonyOS
+ * SDK's `default/openharmony` plus `default/hms/ets`; for OpenHarmony, the API
+ * directory named by `compileSdkVersion` under the SDK home (or the project's
+ * `local.properties` `sdk.dir`). Throws `SdkNotInstalledError` when that API is not
+ * installed, so a caller can offer to install it.
+ */
+declare function resolveArktsCheckSdk(config: ConfigProvider, projectDir: string, logger?: Logger): ArktsCheckSdk;
+/**
+ * Turn the checker's stdout into a report. A run that printed no JSON (the checker
+ * threw, which it does on purpose rather than report a crash as a clean result) or
+ * printed `error` is `completed: false`.
+ */
+declare function parseArktsCheckOutput(stdout: string, stderr: string, exitCode: number): Omit<ArktsCheckReport, 'sdk' | 'durationMs'>;
+/**
+ * Run `check arkts` on a project. Resolves with `completed: false` and `error` when
+ * the checker could not run or crashed; throws only when the SDK cannot be resolved
+ * (`SdkNotInstalledError` when the project's API is not installed).
+ */
+declare function checkArkts(opts: ArktsCheckOptions): Promise<ArktsCheckReport>;
+
+/**
+ * `oniro-app doctor`: one verdict on whether this machine can build, check, sign,
+ * install and test a project, with the tool versions in use so drift between two
+ * runs is visible. Each check is `ok`, `warn`, `fail` or `skip`, with a one-line fix.
+ */
+type DoctorStatus = 'ok' | 'warn' | 'fail' | 'skip';
+interface DoctorCheck {
+    /** Stable key: `node`, `java`, `sdk`, `cmdtools`, `cmdtools-flavour`, `arkts-check`, `hdc`, `device`, `signing`, `disk`. */
+    id: string;
+    status: DoctorStatus;
+    /** What was found, one line. */
+    detail: string;
+    /** What to run or change, when the status is not ok. */
+    fix?: string;
+    /** True when `fix` was applied by `doctor --fix` (the status is then the re-checked one). */
+    fixed?: boolean;
+}
+interface DoctorProject {
+    dir: string;
+    runtimeOS: RuntimeOs;
+    /** As written in build-profile.json5: an API level, or `6.0.0(20)` for HarmonyOS. */
+    compileSdkVersion?: string | number;
+    compatibleSdkVersion?: string | number;
+    /** The API level a device must run at least: compatibleSdkVersion, else compileSdkVersion. */
+    minApi?: number;
+}
+/** Versions in use, recorded so a change between two runs shows (#25). */
+interface DoctorVersions {
+    node: string;
+    java?: string;
+    cmdTools?: string;
+    cmdToolsFlavour?: string;
+    /** The SDK directory a build or `check arkts` of the project uses. */
+    sdk?: string;
+    hdc?: string;
+    deviceApi?: string;
+}
+interface DoctorReport {
+    /** True when no check failed. */
+    ok: boolean;
+    checks: DoctorCheck[];
+    project?: DoctorProject;
+    versions: DoctorVersions;
+}
+interface DoctorOptions {
+    config: ConfigProvider;
+    /** A project to check the SDK, flavour, device API and signing for. */
+    projectDir?: string;
+    /** Install the project's missing OpenHarmony SDK. */
+    fix?: boolean;
+    /** Check a device is reachable (default true). False skips `device`. */
+    device?: boolean;
+    deviceSerial?: string;
+    /** Run `check arkts` on a generated one-file project (default true). */
+    arktsSelfTest?: boolean;
+    logger?: Logger;
+    progress?: ProgressReporter;
+    env?: NodeJS.ProcessEnv;
+    /** Seams for tests. */
+    installSdk?: (opts: InstallSdkOptions) => Promise<void>;
+    arktsCheckerScript?: string;
+}
+/**
+ * What a complete command-line tools install holds. `cmdtools install` extracting
+ * only part of the archive leaves `bin/ohpm` in place, so "installed" alone does
+ * not catch it (#16).
+ */
+declare const CMD_TOOLS_REQUIRED: readonly ["bin/ohpm", "bin/hvigorw", "bin/codelinter", "hvigor", "ohpm", "codelinter", "tool/node", "sdk/default/openharmony/toolchains", "version.txt"];
+/** Parse `20` or `"6.0.0(20)"` to its API level. */
+declare function apiLevelOf(value: unknown): number | undefined;
+declare function describeProject(projectDir: string): DoctorProject;
+declare function checkNode(version?: string): DoctorCheck;
+/** The command-line tools are installed, complete, and of a recorded version. */
+declare function checkCmdTools(config: ConfigProvider, versions: DoctorVersions): DoctorCheck;
+/** codelinter only fully checks projects of its own flavour (#21). */
+declare function checkCmdToolsFlavour(versions: DoctorVersions, project: DoctorProject | undefined, toolsOk?: boolean): DoctorCheck;
+/** The signing material the project's signingConfigs name exists. */
+declare function checkSigning(project: DoctorProject): DoctorCheck;
+/** Free space where SDKs install and where the project builds. */
+declare function checkDisk(dirs: string[], statfs?: (dir: string) => {
+    bavail: number;
+    bsize: number;
+}): DoctorCheck;
+/** Run every check. Never throws for a failed check; `ok` is false when any check failed. */
+declare function runDoctor(opts: DoctorOptions): Promise<DoctorReport>;
+
+interface ScreenPage {
+    /**
+     * The name a route uses to reach the page: the `main_pages.json` entry (`pages/Index`) for an `@Entry` page
+     * (its `routeName` for a named route), the route name for a `NavDestination` (`Detail`), the struct name for a
+     * `NavDestination` struct no route registers.
+     */
+    name: string;
+    module: string;
+    /** Project-relative path of the file declaring the page's component (or route-map builder). */
+    file: string;
+    line: number;
+    /** The struct rendered as the page, when there is one. */
+    component: string | null;
+    /** The component is decorated `@Entry`. */
+    entry: boolean;
+    kind: 'entry' | 'navDestination';
+    /** Listed in `main_pages.json`, a route map, a `.navDestination()` builder, or an `@Entry({ routeName })`. */
+    registered: boolean;
+    /**
+     * Component calls the page renders, through its custom components and `@Builder`s, excluding layout
+     * containers (`Column`, `Row`, `Stack`, `List`, `Navigation`, `NavDestination`, ...) and `Blank`/`Divider`.
+     * Each `ForEach`/`LazyForEach`/`Repeat` item template and each `if` branch counts once.
+     */
+    contentNodes: number;
+    /** Distinct literal route targets pushed from the page's component or the custom components it renders. */
+    routesOut: string[];
+}
+interface ScreenRoute {
+    /** The page whose component holds the call site, else the enclosing struct, class or function. */
+    from: string;
+    /** The target: a `pages/...` url, a NavDestination route name, or the source of a non-literal argument. */
+    to: string;
+    file: string;
+    line: number;
+    /** The call: `pushUrl`, `replaceUrl`, `pushNamedRoute`, `replaceNamedRoute`, `pushPath`, `pushPathByName`, `replacePath`, `replacePathByName`, `pushDestination`, `pushDestinationByName` or `loadContent`. */
+    via: string;
+    /** The target is not a string literal or a constant resolvable in the project (`to` is then its source text). */
+    dynamic?: true;
+}
+interface ScreenPlaceholder {
+    file: string;
+    line: number;
+    text: string;
+    /** `comment` (TODO/FIXME), `text` (a placeholder-like string literal), `resource` (such a string in string.json), `empty-build`, `no-content` (a page that renders only containers). */
+    kind: 'comment' | 'text' | 'resource' | 'empty-build' | 'no-content';
+}
+interface ScreensInventory {
+    projectDir: string;
+    modules: string[];
+    pages: ScreenPage[];
+    routes: ScreenRoute[];
+    placeholders: ScreenPlaceholder[];
+    /** Things the inventory could not resolve: a listed page whose file is missing, a route-map builder not found, ... */
+    warnings: string[];
+}
+interface ScreensOptions {
+    projectDir: string;
+}
+/** Layout-only components: they arrange content but are not content. */
+declare const LAYOUT_COMPONENTS: ReadonlySet<string>;
+/**
+ * Build the static screen inventory of an OpenHarmony/HarmonyOS project: its pages (`@Entry` pages from
+ * `main_pages.json`, `NavDestination`s from route maps and `.navDestination()` builders), the route call sites
+ * between them, and placeholder markers. Reads every module in `build-profile.json5`; needs no SDK and no build.
+ * Throws `OniroError` when the project cannot be read.
+ */
+declare function inventoryScreens(opts: ScreensOptions): ScreensInventory;
+
+interface ScreensSpec {
+    /** Screens the spec asks for: a name, or a name with its own minimum. */
+    screens?: Array<string | {
+        name: string;
+        minContentNodes?: number;
+    }>;
+    /** Routes the spec asks for. Without `from`, a push call site anywhere in the app satisfies it. */
+    routes?: Array<{
+        from?: string;
+        to: string;
+    }>;
+    /** Content nodes every screen needs (default 1). */
+    minContentNodes?: number;
+}
+interface ScreenSpecResult {
+    name: string;
+    ok: boolean;
+    required: number;
+    /** The best matching page (the one with the most content nodes). */
+    page?: string;
+    file?: string;
+    contentNodes?: number;
+    reason?: string;
+}
+interface RouteSpecResult {
+    from?: string;
+    to: string;
+    ok: boolean;
+    /** The first call site that satisfies the route. */
+    site?: Pick<ScreenRoute, 'from' | 'to' | 'file' | 'line' | 'via'>;
+    reason?: string;
+}
+interface ScreensSpecReport {
+    ok: boolean;
+    screens: ScreenSpecResult[];
+    routes: RouteSpecResult[];
+    /** One line per failed screen or route. */
+    failures: string[];
+}
+/** Pages a spec name refers to, by route name, last path segment (`pages/Detail` -> `Detail`) or component, ignoring case. */
+declare function pagesMatching(inventory: Pick<ScreensInventory, 'pages'>, name: string): ScreenPage[];
+/**
+ * The G2 gate as a pure function of a `screens` inventory: every spec screen has a page with at least
+ * `minContentNodes` content nodes, and every spec route has a push or replace call site (`router.pushUrl`,
+ * `NavPathStack.pushPathByName`, ...; `loadContent` and non-literal targets do not count). A route's `from`
+ * matches the page holding the call site, or a page whose `routesOut` (which includes the custom components it
+ * renders) has the target. Names match a page's route name, its last path segment or its component, ignoring case.
+ */
+declare function checkScreensAgainstSpec(inventory: Pick<ScreensInventory, 'pages' | 'routes'>, spec: ScreensSpec): ScreensSpecReport;
+
+/**
+ * A small token scanner and declaration finder for ArkTS (`.ets`) sources.
+ *
+ * Plain TypeScript cannot parse ArkTS: `struct`, the UI trailing-closure syntax
+ * (`Column() { Text('a') }`) and `$r`/`$$` are not TypeScript. The screen
+ * inventory only needs tokens with line numbers, matched brackets, and the
+ * struct, class, function and method declarations with their decorators, so a
+ * scanner that gets comments, strings, template literals and regex literals
+ * right is enough, needs no dependency, and does not depend on an SDK being
+ * installed.
+ */
+type TokenKind = 'ident' | 'string' | 'template' | 'number' | 'punct' | 'regex' | 'eof';
+interface Token {
+    kind: TokenKind;
+    /** Source text of the token (for strings and templates, including the quotes). */
+    value: string;
+    /** For `string` and `template` tokens: the unquoted text (a template's static parts only). */
+    text: string;
+    /** 1-based line of the token's first character. */
+    line: number;
+    start: number;
+    end: number;
+}
+interface SourceComment {
+    text: string;
+    line: number;
+}
+interface Decorator {
+    name: string;
+    /** Index of the `(` of the decorator's arguments, when it has any. */
+    argsOpen?: number;
+}
+interface Declaration {
+    kind: 'struct' | 'class' | 'function' | 'enum' | 'namespace' | 'object';
+    name: string;
+    decorators: Decorator[];
+    /** Index of the name token. */
+    nameIndex: number;
+    line: number;
+    /** Indices of the body's `{` and `}`. */
+    bodyOpen: number;
+    bodyClose: number;
+}
+interface ScannedSource {
+    src: string;
+    tokens: Token[];
+    comments: SourceComment[];
+    /** For each bracket token, the index of its partner; -1 for other tokens or an unbalanced bracket. */
+    match: Int32Array;
+    declarations: Declaration[];
+}
+/** Tokenize an ArkTS/TypeScript source, keeping comments aside. */
+declare function scanEts(src: string): ScannedSource;
+
+/**
+ * Types of the SDK declaration index behind `oniro-app api search` and `api show`:
+ * every class, interface, function, member, enum, ArkUI component and decorator the
+ * ArkTS declaration files of one SDK API level declare, and the Node-API C functions,
+ * types and macros its native sysroot headers declare.
+ */
+type ApiSymbolKind = 'namespace' | 'class' | 'interface' | 'enum' | 'enumMember' | 'type' | 'function' | 'method' | 'constructor' | 'property' | 'variable'
+/** An ArkUI built-in component (`declare const Column: ColumnInterface`) or a declared `struct`. */
+ | 'component'
+/** An ArkUI decorator (`declare const Local: PropertyDecorator`). */
+ | 'decorator'
+/** C: a `#define`. */
+ | 'macro'
+/** C: a `typedef`. */
+ | 'typedef'
+/** C: a `typedef struct { ... }`. */
+ | 'struct';
+type ApiLanguage = 'arkts' | 'c';
+interface ApiEntry {
+    /** The declared name: `pushPathByName`. */
+    name: string;
+    /** The name with its enclosing namespaces, classes and interfaces: `NavPathStack.pushPathByName`. */
+    qualifiedName: string;
+    kind: ApiSymbolKind;
+    language: ApiLanguage;
+    /**
+     * The module that declares it: `@ohos.router`, `@arkts.collections`, a path under
+     * `ets/api` for files that are not modules (`application/UIAbilityContext`), `component/navigation`
+     * for the global ArkUI declarations, or the header (`napi/native_api.h`).
+     */
+    module: string;
+    /** The kit that exports it (`@kit.ArkUI`): from the `ets/kits` re-exports, else the file's `@kit` tag. */
+    kit?: string;
+    /** How an app imports it, when a kit or module exports it: `import { router } from '@kit.ArkUI'`. */
+    import?: string;
+    /** Declared globally (the ArkUI component files): usable without an import. */
+    global?: boolean;
+    /** The API level that introduced it: the lowest `@since` of its doc comments (or its parent's). */
+    since?: number;
+    /** The `@since` values as written, when one carries more than a number (`12 dynamic`, `23 static`). */
+    sinceText?: string;
+    /** `@deprecated` as written (`since 9`); an empty string when the tag has no text. */
+    deprecated?: string;
+    /** The API level of `@deprecated since N`. */
+    deprecatedSince?: number;
+    /** `@useinstead`: what to use instead. */
+    useInstead?: string;
+    /** `@syscap`. */
+    syscap?: string;
+    /** `@systemapi`: only system apps may call it. */
+    systemApi?: boolean;
+    /** The file that declares it, relative to the SDK directory (`ets/component/navigation.d.ts`). */
+    file: string;
+    /** 1-based line of the declaration (not of its doc comment). */
+    line: number;
+    /** The declaration text, whitespace collapsed (the header only for classes, interfaces, namespaces and enums). */
+    signature: string;
+    /** The first line of its doc comment. */
+    doc?: string;
+}
+/** The index of one SDK directory. */
+interface ApiIndex {
+    /** Bumped whenever the shape or the extraction changes, so old caches are rebuilt. */
+    format: number;
+    /** The SDK API directory indexed (holding `ets/` and `native/`). */
+    sdkDir: string;
+    /** The API level from `ets/oh-uni-package.json`. */
+    api?: number;
+    /** The SDK version from `ets/oh-uni-package.json` (`6.0.0.47`). */
+    sdkVersion?: string;
+    /** What the cache is keyed by: the SDK directory and the mtimes of its `oh-uni-package.json` files. */
+    key: string;
+    builtAt: string;
+    /** Declaration files read. */
+    files: number;
+    buildMs: number;
+    entries: ApiEntry[];
+}
+
+/**
+ * Build, cache and load the declaration index of one SDK API directory.
+ *
+ * Sources, relative to the SDK directory:
+ * - `ets/api/**` and `ets/arkts/**` (`.d.ts`, `.d.ets`): the `@ohos.*` and `@arkts.*` modules;
+ * - `ets/component/**`: the global ArkUI component and decorator declarations;
+ * - `ets/kits/@kit.*.d.ts`: which kit re-exports each module symbol (no entries of their own);
+ * - `native/sysroot/usr/include/{napi/*.h,node_api*.h,js_native_api*.h}`: Node-API.
+ *
+ * The index is JSON, cached per SDK directory and rebuilt when the mtime of its
+ * `oh-uni-package.json` files (rewritten by an SDK install) or the index format changes.
+ */
+declare const API_INDEX_FORMAT = 1;
+interface BuildApiIndexOptions {
+    /**
+     * The TypeScript module to parse with. By default the SDK's bundled one
+     * (`ets/build-tools/ets-loader/node_modules/typescript`), else one resolvable from here.
+     */
+    typescript?: unknown;
+    logger?: Logger;
+}
+/** What a cached index of `sdkDir` must match to be reused. */
+declare function apiIndexKey(sdkDir: string): string;
+/** Build the index of one SDK API directory (holding `ets/`, and `native/` for Node-API). */
+declare function buildApiIndex(sdkDir: string, opts?: BuildApiIndexOptions): ApiIndex;
+/** The cache file of `sdkDir`'s index under `cacheDir`. */
+declare function apiIndexCachePath(cacheDir: string, sdkDir: string): string;
+declare function serializeApiIndex(index: ApiIndex): string;
+declare function deserializeApiIndex(json: string): ApiIndex;
+interface LoadApiIndexOptions extends BuildApiIndexOptions {
+    /** Where indexes are cached (an `api-index/` folder is created in it). Omit to not cache. */
+    cacheDir?: string;
+    /** Rebuild even when the cache is current. */
+    rebuild?: boolean;
+}
+interface LoadedApiIndex {
+    index: ApiIndex;
+    /** True when it came from the cache. */
+    cached: boolean;
+    cachePath?: string;
+    /** Wall time to load or build it. */
+    loadMs: number;
+}
+/** The index of `sdkDir`: the cached one when it is current, else a new build (then cached). */
+declare function loadApiIndex(sdkDir: string, opts?: LoadApiIndexOptions): LoadedApiIndex;
+
+/**
+ * Ranked token search and exact lookup over an `ApiIndex`, in process.
+ *
+ * Each whitespace-separated query token must match an entry, in its name or
+ * qualified name, or in its doc line; the scores add up. Per token, best first:
+ * the exact name, the exact qualified name or a dotted suffix of it
+ * (`router.pushUrl`), a name prefix, a camelCase or snake_case part of the name
+ * (`Path` in `pushPathByName`), a substring of the name, then a word in the doc
+ * line. Ties go to types over members, then current over deprecated, public over
+ * system APIs, and shorter names.
+ */
+interface ApiSearchOptions {
+    /** Only entries a kit exports: `ArkUI`, `@kit.ArkUI` (case-insensitive). */
+    kit?: string;
+    /** Only these kinds. */
+    kinds?: readonly ApiSymbolKind[];
+    /** Only `arkts` (ArkTS declarations) or `c` (Node-API headers). */
+    language?: 'arkts' | 'c';
+    /** Leave out `@deprecated` entries. */
+    noDeprecated?: boolean;
+    /** Leave out `@systemapi` entries. */
+    noSystemApi?: boolean;
+    /** At most this many hits. Default 20. */
+    limit?: number;
+}
+interface ApiSearchHit extends ApiEntry {
+    score: number;
+    /** Other declarations of the same symbol in the same file (overloads), not listed separately. */
+    overloads?: number;
+}
+interface ApiSearchResult {
+    query: string;
+    /** Distinct symbols that matched, before the limit. */
+    total: number;
+    hits: ApiSearchHit[];
+}
+/** `ArkUI`, `arkui`, `@kit.ArkUI` -> `@kit.arkui`. */
+declare function normalizeKit(kit: string): string;
+/** `pushPathByName` -> push, path, by, name; `napi_create_object` -> napi, create, object. */
+declare function nameParts(name: string): string[];
+/** Ranked search of `index` for `query`. */
+declare function searchApi(index: ApiIndex, query: string, opts?: ApiSearchOptions): ApiSearchResult;
+interface ApiShowResult {
+    symbol: string;
+    found: boolean;
+    /** Every declaration of it (overloads included), exact qualified-name matches first. */
+    entries: ApiEntry[];
+}
+/**
+ * Exact lookup: the declarations whose qualified name is `symbol` (`NavPathStack.pushPathByName`,
+ * `router.pushUrl`, `Column`, `@Local`), or, when none is, whose qualified name ends with
+ * `.symbol` (`Preferences.get` finds `preferences.Preferences.get`). Case-sensitive.
+ */
+declare function showApi(index: ApiIndex, symbol: string, opts?: Pick<ApiSearchOptions, 'kit' | 'kinds' | 'language'>): ApiShowResult;
+
+/** Which SDK API directory `api search` and `api show` read, and why. */
+interface ApiSdkSelection {
+    sdkDir: string;
+    api?: number;
+    source: 'sdk-option' | 'api-option' | 'project' | 'newest-installed';
+    /** Why the SDK is not the one the project asks for, when it is not. */
+    note?: string;
+}
+interface ResolveApiSdkOptions {
+    /** An SDK API directory (holding `ets/`), used as is. */
+    sdkDir?: string;
+    /** An API level: `<sdk home>/<api>`. */
+    api?: number;
+    /** A project directory; its `compileSdkVersion` picks the SDK. Searched upwards for `build-profile.json5`. */
+    projectDir?: string;
+}
+/** The installed OpenHarmony SDK API levels under the SDK home, newest first. */
+declare function installedApiLevels(config: ConfigProvider): number[];
+/**
+ * Pick the SDK: `sdkDir`, else `<sdk home>/<api>`, else the one the enclosing
+ * project's `compileSdkVersion` names (as hvigor finds it), else the newest installed.
+ */
+declare function resolveApiSdk(config: ConfigProvider, opts?: ResolveApiSdkOptions): ApiSdkSelection;
+/** Where API indexes are cached: `<cacheDir>/api-index/` (`cacheDir` defaults to `~/.oniro/cache`). */
+declare function getApiIndexCacheDir(config: ConfigProvider): string;
+
+/**
+ * The doc-comment tags the index records, read from the `/** ... *\/` blocks before a
+ * declaration. OpenHarmony stacks one block per API level that changed a symbol's
+ * documentation (the `@since 10` block, then the `@since 11` block that adds
+ * `@atomicservice`, ...), so a symbol's facts come from all of its blocks.
+ */
+interface DocTags {
+    /** The lowest numeric `@since`. */
+    since?: number;
+    /** The `@since` values with a qualifier (`12 dynamic`), joined with `, `. */
+    sinceText?: string;
+    deprecated?: string;
+    deprecatedSince?: number;
+    useInstead?: string;
+    syscap?: string;
+    systemApi?: boolean;
+    /** `@kit` (on a file's `@file` block): `ArkUI`. */
+    kit?: string;
+    /** The block is a file header (`@file`, `@addtogroup`), not a declaration's doc. */
+    fileHeader?: boolean;
+    doc?: string;
+}
+/** The tags of one block. */
+declare function parseDocBlock(block: string): DocTags;
+/**
+ * The tags of a declaration from all its doc blocks, oldest first: the lowest
+ * `@since` (of the public blocks, when the newest block is public), a deprecation
+ * from any block, and the syscap, system-API flag and doc line of the newest block.
+ * File-header blocks are skipped.
+ */
+declare function mergeDocBlocks(blocks: readonly string[]): DocTags;
+
+/**
+ * `api show` beyond the exact lookup: on a miss, which other installed SDKs declare
+ * the symbol, and the close names this SDK does declare. This is the answer to "does
+ * this member exist at this API level": a hallucinated member gets the real ones.
+ */
+interface ApiElsewhere {
+    api: number;
+    /** The lowest `@since` of its declarations there. */
+    since?: number;
+}
+/**
+ * Close names for a symbol `index` does not declare: for `Parent.member`, the
+ * members of `Parent` sharing a camelCase part with `member` (most shared first), then
+ * the search hits for `member` itself, else the first functions and methods of `Parent`.
+ */
+declare function suggestApiSymbols(index: ApiIndex, symbol: string, limit?: number): string[];
+interface FindInOtherSdksOptions {
+    cacheDir?: string;
+    kit?: string;
+    logger?: Logger;
+}
+/** The installed SDKs other than `exceptSdkDir` that declare `symbol`, newest first. Builds their indexes if needed. */
+declare function findApiInOtherSdks(config: ConfigProvider, symbol: string, exceptSdkDir: string, opts?: FindInOtherSdksOptions): ApiElsewhere[];
+
+/**
+ * What a faultlog is. `sample_stack` is the periodic stack sampling hiview adds
+ * to a freeze (`freeze-cpuinfo-ext-*`), not a fault of its own.
+ */
+type FaultLogKind = 'cpp_crash' | 'js_crash' | 'app_freeze' | 'sample_stack' | 'unknown';
+/** The three kinds that are a fault of the process. */
+type FaultLogFamily = 'cpp_crash' | 'js_crash' | 'app_freeze';
+declare const FAULT_LOG_FAMILIES: readonly FaultLogFamily[];
+type FaultConfidence = 'high' | 'medium' | 'low';
+/** `full`: the faultlog's header region is present; `fragment`: a pasted excerpt. */
+type FaultCompleteness = 'full' | 'fragment';
+interface FaultLogClassification {
+    kind: FaultLogKind;
+    /** For `app_freeze`, the event (`THREAD_BLOCK_6S`, `APP_INPUT_BLOCK`, `LIFECYCLE_TIMEOUT`). */
+    subtype?: string;
+    confidence: FaultConfidence;
+    completeness: FaultCompleteness;
+    /** Why the kind was chosen. */
+    evidence: string[];
+    /** Why each other kind was ruled out. */
+    excluded: Array<{
+        kind: FaultLogFamily;
+        reason: string;
+    }>;
+    /** Set when several kinds matched and no rule picks one (`kind: 'unknown'`), or the runner-up of a mixed fragment. */
+    candidates: Array<{
+        kind: FaultLogFamily;
+        confidence: FaultConfidence;
+        evidence: string[];
+        arbitrable: boolean;
+    }>;
+    /** Set when the input is not a faultlog at all. */
+    outOfScope?: {
+        reason: 'empty' | 'hilog_stream' | 'other_platform';
+        detail: string;
+    };
+}
+/** A faultlog above this is refused rather than silently truncated. */
+declare const MAX_FAULTLOG_BYTES: number;
+/**
+ * Classify faultlog text by its structure alone (never by file name), so the
+ * same input always gets the same answer. Order: a whole faultlog's header,
+ * then sample-stack markers, then the patterns of an excerpt.
+ */
+declare function classifyFaultLog(input: string): FaultLogClassification;
+
+/** `Tid:20020, Name:com.example.app` (leading space tolerated, as in cppcrash). */
+declare const THREAD_HEADER_RE: RegExp;
+/** Where a frame's code lives: the OS, the app, or something else (an anonymous mapping). */
+type FrameArea = 'system' | 'app' | 'other';
+interface NativeFrame {
+    index: number;
+    pc: string;
+    /** Library or executable path, e.g. `/system/lib64/libace_compatible.z.so` or `[shmm]`. */
+    library: string;
+    /** `do_dlsym+492`, when the log has one. */
+    symbol: string | null;
+    buildId: string | null;
+    area: FrameArea;
+    /** The line as printed, trimmed. */
+    raw: string;
+}
+interface JsFrame {
+    /** Function name (`anonymous` for lambdas), when the line has one. */
+    function: string | null;
+    /** Module after the function name (`entry`), when the line has one. */
+    module: string | null;
+    file: string;
+    line: number;
+    column: number;
+    /** In the project's own sources (`<module>/src/main/…`), not the SDK or a dependency. */
+    project: boolean;
+    raw: string;
+}
+type StackFrame = ({
+    kind: 'native';
+} & NativeFrame) | ({
+    kind: 'js';
+} & JsFrame);
+interface ThreadStack {
+    tid: string;
+    name: string;
+    frames: StackFrame[];
+}
+/** Parse one native frame line, or `null` if it is not one. */
+declare function parseNativeFrame(line: string): NativeFrame | null;
+/** Parse one ArkTS/JS frame line, or `null` if it is not one. */
+declare function parseJsFrame(line: string): JsFrame | null;
+/** Parse a native or JS frame line. */
+declare function parseFrame(line: string): StackFrame | null;
+/** Split stack text at `Tid:…, Name:…` headers. A repeated tid replaces the earlier one. */
+declare function parseThreadStacks(lines: readonly string[]): Map<string, ThreadStack>;
+/** The stack-capture error lines in a section, each with what it means (deduplicated). */
+declare function extractStackErrors(lines: readonly string[]): string[];
+
+interface BinderNode {
+    pid: string;
+    tid: string;
+}
+/** One binder transaction from the freeze log's BinderCatcher section. */
+interface BinderTransaction {
+    srcPid: string;
+    srcTid: string;
+    dstPid: string;
+    dstTid: string;
+    code: string;
+    waitSeconds: number;
+    frzState: string;
+    async: boolean;
+    raw: string;
+}
+interface BinderInfo {
+    transactions: BinderTransaction[];
+    /** pid → process name, from the peers' stacks. */
+    peers: Map<string, string>;
+}
+/** One synchronous wait in the chain the faulting thread belongs to. */
+interface BinderEdge {
+    /** `pid:tid(process/thread)`; a tid of 0 means every binder thread of the process is busy (IPC full). */
+    from: string;
+    to: string;
+    waitSeconds: number;
+    code: string;
+    frzState?: string;
+}
+interface BinderPropagation {
+    /** Longest wait first. */
+    edges: BinderTransaction[];
+    /** Deadlock cycles, one representative per strongly connected group. */
+    cycles: BinderNode[][];
+    notes: string[];
+}
+/** `pid:tid(process/thread)`; the main thread's name usually equals the process name, so it is shown once. */
+declare function nodeLabel(node: BinderNode, processNames: Map<string, string>, threadNames?: Map<string, string>): string;
+/** Parse the BinderCatcher section: transactions, then the peers' stacks. */
+declare function parseBinder(lines: readonly string[]): BinderInfo;
+/**
+ * The synchronous binder chain the faulting thread is part of: what it waits on
+ * (downstream) and who waits on it (upstream), anchored on every thread of the
+ * faulting process that appears in a transaction, plus any deadlock cycles.
+ */
+declare function buildPropagation(binder: BinderInfo, faultPid: string, faultTid: string): BinderPropagation;
+
+declare const CPP_HEADER: {
+    readonly module: RegExp;
+    readonly version: RegExp;
+    readonly pid: RegExp;
+    readonly uid: RegExp;
+    readonly process: RegExp;
+    readonly lifetime: RegExp;
+    readonly timestamp: RegExp;
+    readonly reason: RegExp;
+    readonly lastFatalMessage: RegExp;
+};
+interface CppCrashLog {
+    header: Partial<Record<keyof typeof CPP_HEADER, string>>;
+    /** The first thread of `Fault thread info:`. */
+    faultThread: ThreadStack | null;
+    /** The GWP-ASan report, from its banner to its end marker. */
+    gwpAsan: string;
+}
+declare function parseCppCrash(lines: readonly string[]): CppCrashLog;
+declare const JS_HEADER: {
+    readonly module: RegExp;
+    readonly process: RegExp;
+    readonly package: RegExp;
+    readonly version: RegExp;
+    readonly pid: RegExp;
+    readonly uid: RegExp;
+    readonly faultTime: RegExp;
+    readonly timestamp: RegExp;
+    readonly reason: RegExp;
+    readonly errorName: RegExp;
+    readonly errorMessage: RegExp;
+    readonly errorCode: RegExp;
+};
+interface JsCrashLog {
+    header: Partial<Record<keyof typeof JS_HEADER, string>>;
+    faultTid: string;
+    faultThreadName: string;
+    /** The `Stacktrace:` section, one frame per line as printed. */
+    stack: string[];
+    /** The same frames, parsed. */
+    frames: StackFrame[];
+    /** The `HybridStack:` section (native and JS frames interleaved), when present. */
+    hybrid: StackFrame[];
+}
+declare function parseJsCrash(lines: readonly string[]): JsCrashLog;
+declare const FREEZE_HEADER: {
+    readonly module: RegExp;
+    readonly reason: RegExp;
+    readonly process: RegExp;
+    readonly pid: RegExp;
+};
+declare const FREEZE_MSG: {
+    readonly eventName: RegExp;
+    readonly timestamp: RegExp;
+    readonly pid: RegExp;
+    readonly tid: RegExp;
+    readonly process: RegExp;
+    readonly msg: RegExp;
+    readonly faultTime: RegExp;
+};
+interface FreezeReport {
+    msg: Partial<Record<keyof typeof FREEZE_MSG, string>>;
+    stacks: Map<string, ThreadStack>;
+    stackErrors: string[];
+}
+interface FreezeLog {
+    header: Partial<Record<keyof typeof FREEZE_HEADER, string>>;
+    /** The header's Reason, else the event name. */
+    reason: string;
+    /** The first report (warning). */
+    warning: FreezeReport;
+    /** The second report (block), taken a few seconds later, when present. */
+    block: FreezeReport | null;
+    binder: BinderInfo;
+    /** tid of the FFRT worker running the blocked queue task, when there is one. */
+    ffrtTid: string;
+    /** pid → process name, for labelling binder nodes. */
+    processNames: Map<string, string>;
+    pid: string;
+    process: string;
+    /** The blocked thread: the FFRT worker when the queue is blocked, else the reported TID, else the main thread. */
+    faultTid: string;
+}
+declare function parseFreeze(lines: readonly string[]): FreezeLog;
+
+/**
+ * The native crash record faultloggerd writes to `/data/log/faultlog/temp/`
+ * (`cppcrash-<pid>-<epoch ms>.json`) before hiview turns it into a cppcrash
+ * faultlog. When hiview refuses the record (on some builds it does not
+ * recognise processdump at `/root/system/bin/processdump` and logs
+ * `Fail to add fault log … is not processdump`), this file is the only record
+ * of an app's native crash. Written for this package; not part of the deveco-cli port.
+ */
+interface JsonFrame {
+    pc?: string;
+    symbol?: string;
+    offset?: number;
+    file?: string;
+    buildId?: string;
+    /** JS frames carry these instead of `pc`. */
+    packageName?: string;
+    line?: number;
+    column?: number;
+}
+interface JsonThread {
+    thread_name?: string;
+    tid?: number;
+    frames?: JsonFrame[];
+}
+interface CrashJson {
+    JSON_VERSION?: string;
+    BUILD_INFO?: string;
+    TIMESTAMP?: string;
+    PID?: number;
+    UID?: number;
+    PNAME?: string;
+    PROCESS_LIFETIME?: string;
+    LOG_SOURCE?: string;
+    REASON?: string;
+    LAST_FATAL_MESSAGE?: string;
+    KEY_THREAD_INFO?: JsonThread;
+    OTHER_THREAD_INFO?: JsonThread[];
+    KEY_THREAD_REGISTERS?: string;
+}
+/** Whether text is a faultloggerd crash record rather than a faultlog. */
+declare function isCrashJson(text: string): boolean;
+/**
+ * Render a crash record as the cppcrash faultlog hiview would have written, so
+ * one parser reads both. Throws on invalid JSON.
+ */
+declare function renderCrashJson(text: string): string;
+
+/** The trailing `HiLog:` section of a faultlog (from that line on), or `''`. */
+declare function hilogSection(lines: readonly string[]): string;
+
+/** One fault, read from a faultlog: what kind, where it happened, and why. */
+interface CrashVerdict {
+    /** A process fault (`cpp_crash`, `js_crash` or `app_freeze`); false for a sample stack or an unrecognised log. */
+    crashed: boolean;
+    kind: FaultLogKind;
+    /** For `app_freeze`, the event (`THREAD_BLOCK_6S`, `APP_INPUT_BLOCK`, `LIFECYCLE_TIMEOUT`). */
+    subtype: string | null;
+    confidence: FaultConfidence;
+    completeness: FaultCompleteness;
+    /** The app's bundle name (`Module name:` of an app's faultlog; for a native service, its module). */
+    bundle: string | null;
+    process: string | null;
+    pid: number | null;
+    uid: number | null;
+    /** The faulting (or blocked) thread. */
+    tid: number | null;
+    threadName: string | null;
+    /** When the fault happened, as the log prints it (device local time, `YYYY-MM-DD HH:MM:SS.mmm`). */
+    time: string | null;
+    /** `Reason:` — the signal (`Signal:SIGSEGV(SEGV_MAPERR)@0x0 …`), the JS error class, or the freeze event. */
+    reason: string | null;
+    /** The top frame of the faulting thread, as printed. */
+    topFrame: string | null;
+    /** The first frame in the app's own code: an ArkTS frame under `<module>/src/main/`, else a native frame in the app's libraries. */
+    projectFrame: string | null;
+    /** Source position of the first project ArkTS frame, as the log prints it (`entry/src/main/ets/pages/Index.ets`). */
+    file: string | null;
+    line: number | null;
+    column: number | null;
+    /** For a JS crash: the error and its stack. */
+    jsError: {
+        name: string;
+        message: string;
+        stack: string[];
+    } | null;
+    /** Every frame of the faulting thread as printed, native and ArkTS interleaved, top first (for a freeze, from the first report). */
+    stack: string[];
+    /** Native frames of the faulting thread (for a freeze, from the first report). */
+    nativeFrames: NativeFrame[];
+    /** ArkTS frames of the faulting thread. */
+    jsFrames: JsFrame[];
+    /** For a freeze: the synchronous binder calls the blocked thread is part of, longest wait first. */
+    binderChain: BinderEdge[];
+    /** For a freeze: binder deadlock cycles, `a -> b -> a`. */
+    deadlocks: string[];
+    /** Notes on the binder chain, the stack capture, or the classification. */
+    notes: string[];
+    /** cppcrash `LastFatalMessage:` (an abort message), when present. */
+    lastFatalMessage: string | null;
+    /** cppcrash GWP-ASan report, when present. */
+    gwpAsan: string | null;
+    /** Why the kind was chosen. */
+    evidence: string[];
+    /** The faultlog's file name, e.g. `jscrash-com.example.app-20010043-20261105123257298.log`. */
+    name: string | null;
+    /** Where the faultlog is: its path on the device, or the local file it was read from. */
+    path: string | null;
+    /** A local copy of the whole faultlog, when one was saved. */
+    rawPath: string | null;
+}
+interface AnalyzeFaultLogOptions {
+    name?: string;
+    path?: string;
+    rawPath?: string;
+}
+/** Freeze logs print `2026/11/05-12:42:29[:053]`; give every kind `2026-11-05 12:42:29[.053]`. */
+declare function normalizeFaultTime(value: string | undefined): string | null;
+/**
+ * Classify a faultlog and read its fault: kind and confidence, the process, the
+ * reason, the top and first project frames (with `file:line:column` for ArkTS),
+ * the JS error, the native frames and, for a freeze, the binder chain.
+ */
+declare function analyzeFaultLog(input: string, opts?: AnalyzeFaultLogOptions): CrashVerdict;
+
+/** Where hiview keeps faultlogs. */
+declare const FAULTLOG_DIR = "/data/log/faultlog/faultlogger";
+/** Where faultloggerd leaves native crash records (`cppcrash-<pid>-<epoch ms>.json`). */
+declare const FAULTLOG_TEMP_DIR = "/data/log/faultlog/temp";
+/** `hidumper -s 1201` is hiview; `-p Faultlogger` its faultlog plugin. */
+declare const faultloggerCommand: (args: string) => string;
+interface FaultLogEntry {
+    /** File name, e.g. `jscrash-com.example.app-20010043-20261105123257298.log`. */
+    name: string;
+    /** Path on the device. */
+    path: string;
+    /** `faultlogger`: a hiview faultlog; `temp`: a faultloggerd crash record hiview has not (or will not) turn into one. */
+    source: 'faultlogger' | 'temp';
+    /** The file-name prefix: `cppcrash`, `jscrash`, `appfreeze`, `sysfreeze`, `syswarning`, … */
+    type: string;
+    /** Bundle or process name. */
+    module: string | null;
+    pid: number | null;
+    uid: number | null;
+    /** Device-local time of the fault, `YYYY-MM-DD HH:MM:SS.mmm`. */
+    time: string | null;
+    /** The fault's instant, when known: always for a crash record, for a faultlog when the device's UTC offset was read. */
+    epochMs: number | null;
+}
+interface FaultLogDeviceOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    timeoutMs?: number;
+    logger?: Logger;
+}
+interface ListFaultLogsOptions extends FaultLogDeviceOptions {
+    /** Only entries of this bundle (exact module/process name). */
+    bundle?: string;
+    /** Only entries since this instant, or since this many seconds before the device's clock now. */
+    since?: Date | number;
+    /** Also list faultloggerd's native crash records that have no faultlog. Default true. */
+    includeCrashRecords?: boolean;
+}
+/** The file names between the `******` lines of `hidumper … -p Faultlogger -l`, or null if the output is not a list. */
+declare function parseFaultLogList(stdout: string): string[] | null;
+/**
+ * Read `<type>-<module>-<uid>-<yyyyMMddHHmmss[SSS]>.log`. `utcOffsetMinutes`
+ * (the device's) turns the local time into `epochMs`.
+ */
+declare function parseFaultLogName(name: string, utcOffsetMinutes?: number): FaultLogEntry | null;
+/** `+0100` → 60. */
+declare function parseUtcOffset(value: string): number | null;
+/** Parse the `== <path>` / head-of-file blocks the crash-record listing prints. */
+declare function parseCrashRecordHeads(stdout: string): FaultLogEntry[];
+/**
+ * List faultlogs on the device, newest first: hiview's (`hidumper -s 1201 -a
+ * '-p Faultlogger -LogSuffixWithMs'`, else `ls` of {@link FAULTLOG_DIR}) and,
+ * unless turned off, faultloggerd's native crash records that hiview never
+ * turned into a faultlog.
+ */
+declare function listFaultLogs(opts: ListFaultLogsOptions): Promise<FaultLogEntry[]>;
+/** Drop the `[ability]` / `HiviewService` banner hidumper prints before the file. */
+declare function stripHidumperBanner(stdout: string): string;
+interface ReadFaultLogOptions extends FaultLogDeviceOptions {
+    entry: FaultLogEntry;
+}
+/** The whole faultlog (or crash record) as text: `hidumper … -f <name>`, else `cat`. */
+declare function readFaultLog(opts: ReadFaultLogOptions): Promise<string>;
+interface LatestCrashOptions extends FaultLogDeviceOptions {
+    /** Bundle to look for; any process when unset. */
+    bundle?: string;
+    /** Only faults since this instant, or since this many seconds before the device's clock now. */
+    since?: Date | number;
+    /**
+     * Keep looking this long (ms) when nothing is found yet: hiview writes a
+     * faultlog a moment after the process dies. Default 0 (look once).
+     */
+    waitMs?: number;
+    /** Poll interval while waiting. Default 1000. */
+    pollMs?: number;
+    /** Save the whole faultlog in this directory and report it as `rawPath`. */
+    saveDir?: string;
+}
+/**
+ * The newest fault of `bundle` (since `since`) on the device, classified and
+ * parsed, or null when there is none. Considers faultlogs of every kind and
+ * native crash records hiview did not turn into one.
+ */
+declare function latestCrash(opts: LatestCrashOptions): Promise<CrashVerdict | null>;
+
+/** The flow file format version this code reads and writes. */
+declare const FLOW_VERSION = 1;
+/** What a step does. `wait` only waits for its selector (or, with `gone`, for it to disappear). */
+declare const FLOW_ACTIONS: readonly ["click", "longClick", "doubleClick", "swipe", "inputText", "keyEvent", "wait"];
+type FlowAction = (typeof FLOW_ACTIONS)[number];
+/** A point as 0–1 fractions of the display, as `dump layout` prints centers. */
+interface FlowPoint {
+    fx: number;
+    fy: number;
+}
+/** One step of a flow. See packages/cli/README.md (`replay`) for the format. */
+interface FlowStep {
+    action: FlowAction;
+    /**
+     * The element to wait for and act on, as `--selector` text (`type=Button,id=continueBtn`,
+     * `xpath=//Button[@text="OK"]`). Optional for keyEvent (waited for, not tapped) and
+     * inputText (types into the focused field); click-like actions and swipe need it or `fallback`.
+     */
+    selector?: string;
+    /** Where to act when there is no selector (or, with `replay --fallback`, when it is not found). */
+    fallback?: FlowPoint;
+    /** inputText: the text to type. */
+    text?: string;
+    /** inputText: clear the field first. */
+    clear?: boolean;
+    /** keyEvent: a key name (Back, Home, Enter, Delete, …), a KeyCode id, or a combo like `Ctrl+A`. */
+    key?: string | number;
+    /** swipe: where the finger ends. */
+    to?: FlowPoint;
+    /** swipe: velocity, px/s (uitest default 600). */
+    speed?: number;
+    /** wait: wait until no element matches the selector, instead of until one does. */
+    gone?: boolean;
+    /** A selector for an element that must be on screen after the step. */
+    expect?: string;
+    /** Pause after the action, before `expect` and the next step, ms. */
+    waitMs?: number;
+    /** This step's timeout for its selector and `expect`, ms (default: `replay --step-timeout`). */
+    timeoutMs?: number;
+    /** Free text for people reading the flow; ignored. */
+    note?: string;
+}
+/** The device a flow was recorded or written for (informational). */
+interface FlowDevice {
+    api?: number;
+    display?: {
+        width: number;
+        height: number;
+    };
+}
+/** A flow file: versioned JSON, written by `record` or by hand, run by `replay`. */
+interface Flow {
+    version: typeof FLOW_VERSION;
+    /** The app the flow drives; replay reports a divergence as `wrong-screen` when it is not on screen. */
+    bundle?: string;
+    /** The ability `replay --launch` starts (default: the bundle's main ability). */
+    ability?: string;
+    device?: FlowDevice;
+    steps: FlowStep[];
+}
+/** A flow file that is not valid JSON or does not follow the format; lists every problem. */
+declare class FlowFormatError extends OniroError {
+    readonly problems: string[];
+    readonly file?: string | undefined;
+    constructor(problems: string[], file?: string | undefined);
+}
+/**
+ * Validate a parsed flow document, reporting every problem at once (field paths
+ * such as `steps[2].selector`), and return it typed. Selectors are parsed, so a
+ * flow that loads replays without a selector syntax error. Pure.
+ */
+declare function parseFlow(doc: unknown, file?: string): Flow;
+/** Read and validate a flow file. Throws {@link FlowFormatError}. */
+declare function readFlowFile(file: string): Flow;
+/** A flow as the JSON text `record` writes (two-space indent, trailing newline). */
+declare function formatFlow(flow: Flow): string;
+
+/**
+ * One finger of a pointer event, as `uitest uiRecord record` writes it: `W1_*`
+ * and `W2_*` are widgets hit-tested at the down and up points, `X_POSI`, `Y_POSI`
+ * and `X2_POSI`, `Y2_POSI` the down and up points in pixels. The points are
+ * exact; the widgets are not reliable (see {@link flowFromRecording}).
+ */
+interface UiRecordFinger {
+    W1_BOUNDS?: string;
+    W1_HIER?: string;
+    W1_ID?: string;
+    W1_Text?: string;
+    W1_Type?: string;
+    X_POSI?: string;
+    Y_POSI?: string;
+    X2_POSI?: string;
+    Y2_POSI?: string;
+    [field: string]: unknown;
+}
+/**
+ * One line of uitest's `record.csv`, which is JSON Lines despite its name. Pointer
+ * events carry `OP_TYPE` click, longClick, doubleClick, swipe, fling, drag, back,
+ * home or recent, the foreground `BUNDLE` and `ABILITY`, and `fingerList`; key
+ * events carry `OP_TYPE` key and `KeyCode1`..`KeyCode3` (each keystroke is two
+ * lines, the second carrying the layout path). With `-l`, `FILEPAHT` (sic) is the
+ * layout uitest dumped when it wrote the event.
+ */
+interface UiRecordEvent {
+    OP_TYPE: string;
+    EVENT_TYPE?: string;
+    BUNDLE?: string;
+    ABILITY?: string;
+    FILEPAHT?: string;
+    fingerNumber?: string;
+    fingerList?: UiRecordFinger[];
+    KeyCode1?: string;
+    KeyCode2?: string;
+    KeyCode3?: string;
+    [field: string]: unknown;
+}
+/** Parse the lines of uitest's `record.csv` (JSON Lines); other lines are skipped. Pure. */
+declare function parseUiRecordLines(text: string): UiRecordEvent[];
+/** The character a keystroke types (KeyCode ids, modifiers included), or undefined for other keys. Pure. */
+declare function keystrokeChar(codes: readonly number[]): string | undefined;
+/** A keystroke as a `keyEvent` key: a name `input --key` knows, a KeyCode id, or a `+` combo. Pure. */
+declare function keystrokeName(codes: readonly number[]): string;
+/**
+ * The element a touch at `p` lands on in a pruned layout: the last element in
+ * paint order whose bounds contain the point and that is not covered, skipping
+ * window roots and bare containers. Pure.
+ */
+declare function elementAt(tree: LayoutNode, p: FlowPoint): FlatLayoutNode | undefined;
+/**
+ * A selector for a text field that does not depend on its content (which typing
+ * changes): its type with its id, key or placeholder, else every one of them
+ * plus the field's `[n]` index. Pure.
+ */
+declare function fieldSelector(tree: LayoutNode, field: FlatLayoutNode): string | undefined;
+/**
+ * A selector for an element that appeared with the step: unique and uncovered in
+ * `after`, absent from `before`, inside the app's window. Ids and keys are tried
+ * before texts. Undefined when nothing new is identifiable (the step did not
+ * visibly change the app). Pure.
+ */
+declare function expectFor(before: LayoutNode, after: LayoutNode, opts?: {
+    bundle?: string;
+    keyboardIds?: ReadonlySet<number>;
+}): string | undefined;
+/** When things happened during the recording, read off the device (epoch ms). */
+interface RecordingTimes {
+    /** When the `initial` layout was dumped. */
+    initial: number;
+    /** Every touch-down during the recording, in order (hilog `ServerMsgHandler: [P:D:…]`). */
+    touchDowns: readonly number[];
+    /** When uitest wrote each layout file (its mtime), by device path. */
+    layouts: ReadonlyMap<string, number>;
+}
+/**
+ * The touch-down time of each pointer event, by event index, when the events
+ * account for exactly the touch-downs seen: one per finger (two for a
+ * doubleClick), and none or one for back/home/recent (which uitest also reports
+ * for keys). Undefined when neither count matches. Pure.
+ */
+declare function alignTouches(events: readonly UiRecordEvent[], touchDowns: readonly number[]): Map<number, number> | undefined;
+interface FlowFromRecordingInput {
+    events: readonly UiRecordEvent[];
+    /** The pruned layouts the recorder saved, by the device path in each event's `FILEPAHT`. */
+    layouts: ReadonlyMap<string, LayoutNode>;
+    /** A pruned layout dumped just before recording started. */
+    initial: LayoutNode;
+    /** A pruned layout dumped just after recording stopped (the state after the last event). */
+    final?: LayoutNode;
+    /** When the touches and the layouts happened; without it the layouts are taken in event order. */
+    times?: RecordingTimes;
+    display: DisplaySize;
+    /** Input-method bundles (see `getImeBundles`), to tell taps on the soft keyboard apart. */
+    imeBundles?: readonly string[];
+    /** The app being recorded; default: the first bundle the pointer events name. */
+    bundle?: string;
+    ability?: string;
+    api?: number;
+}
+interface FlowFromRecordingResult {
+    flow: Flow;
+    /** Events that could not be turned into steps, steps left without a selector, timing problems. */
+    warnings: string[];
+}
+/**
+ * Turn the events of a `uitest uiRecord record -l` session into a flow. Each
+ * pointer event becomes a step on the element under its touch point in the
+ * layout on screen at that moment (uitest's own widget when that layout has it
+ * there, since uitest hit-tests late), with {@link selectorFor}'s selector, the
+ * touch point as `fallback`, and as `expect` an element that appeared after it
+ * ({@link expectFor}). Taps on the soft keyboard and typed keystrokes collapse
+ * into one inputText step on the focused field ({@link fieldSelector}), with the
+ * text read off that field afterwards; other keys, and back and home, become
+ * keyEvent steps. A tap on a field next to the inputText step for that field is
+ * dropped (inputText taps it). Pure.
+ */
+declare function flowFromRecording(input: FlowFromRecordingInput): FlowFromRecordingResult;
+
+/** Where `uitest uiRecord record` writes its events on the device (fixed by uitest). */
+declare const UI_RECORD_CSV = "/data/local/tmp/record.csv";
+interface RecordFlowOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    logger?: Logger;
+    /** Stop after this long, ms. */
+    durationMs?: number;
+    /** Stop when this aborts (Ctrl+C). Recording runs until one of the two. */
+    abortSignal?: AbortSignal;
+    /** The app being recorded; default: the foreground app when recording starts. */
+    bundle?: string;
+    /**
+     * Turn the screen on, swipe away a lock screen without a credential, and keep
+     * the screen on while recording (restored afterwards). Default true.
+     */
+    wake?: boolean;
+    /** Called when the recorder has written more events (raw lines, two per keystroke). */
+    onEvents?: (count: number) => void;
+    /** How often to poll the recorder, ms. Default 1000. */
+    pollMs?: number;
+    /**
+     * Keep uitest's raw recording here: `record.csv`, the layout files, the
+     * recorder's console, and `recording.json` (display, IME bundles, touch and
+     * layout times, the layouts dumped before and after). For bug reports.
+     */
+    rawDir?: string;
+}
+interface RecordFlowResult extends FlowFromRecordingResult {
+    /** The raw event lines uitest wrote. */
+    events: number;
+}
+/**
+ * A device timestamp as `date '+%Y-%m-%d %H:%M:%S.%N %z'` and `stat -c %y` print it
+ * (`2026-11-05 14:37:23.885001099 +0100`), in epoch ms; undefined when it does not parse. Pure.
+ */
+declare function parseDeviceTime(text: string): number | undefined;
+/**
+ * The touch-down times in `hilog -x` output: the multimodal input service logs
+ * `ServerMsgHandler: [P:D:<id>|…]` for each finger going down. hilog prints local
+ * time without a year or zone, so `reference` (a {@link parseDeviceTime} string
+ * from the device) supplies them. Only touches at or after `since` (epoch ms) count. Pure.
+ */
+declare function parseTouchDowns(hilog: string, reference: string, since?: number): number[];
+/** `Current ForAbility :com.example.app, EntryAbility` from the recorder's console. Pure. */
+declare function parseRecorderForeground(consoleText: string): {
+    bundle: string;
+    ability: string;
+} | undefined;
+/**
+ * Record a flow with uitest's own recorder: run `uitest uiRecord record -l` in
+ * the background on the device (it logs every touch and key, with the widget
+ * under the finger, and dumps the layout for each), stop it with SIGINT after
+ * `durationMs` or when `abortSignal` aborts, then pull its event file and
+ * layouts and turn them into a flow ({@link flowFromRecording}). uitest writes
+ * an event only once the next touch has started, so the multimodal input
+ * service's hilog domain is followed meanwhile for the touch-down times, and the
+ * layouts' modification times place them on the same clock. A layout dumped
+ * just before starting and one just after stopping bracket the session. Events
+ * made by `input` (uitest uiInput) are recorded too. While the recorder runs,
+ * `uitest dumpLayout` blocks for everyone using the device.
+ */
+declare function recordFlow(opts: RecordFlowOptions): Promise<RecordFlowResult>;
+
+/** Why a replay stopped at a step. */
+type DivergenceReason = 
+/** The step's element did not appear within the timeout. */
+'not-found'
+/** The step ran, but its `expect` element did not appear. */
+ | 'expect-not-found'
+/** The flow's app is not on screen (it crashed, another app or the lock screen is in front). */
+ | 'wrong-screen'
+/** Several elements match the step's selector (append `[n]` or make it more specific). */
+ | 'ambiguous'
+/** The element is there but covered by an overlay. */
+ | 'covered'
+/** The input could not be sent. */
+ | 'action-failed';
+interface ReplayStepResult {
+    index: number;
+    action: FlowStep['action'];
+    selector?: string;
+    ok: boolean;
+    durationMs: number;
+    /** The element the step acted on. */
+    target?: string;
+    /** The step acted on its fallback point (no selector, or `fallback: true` and the selector was not found). */
+    usedFallback?: boolean;
+    /** This step's screenshot (`screenshotsDir`). */
+    screenshot?: string;
+}
+/** What was on screen when the flow diverged. */
+interface DivergenceLayout {
+    /** Windows on screen, in paint order. */
+    windows: Array<{
+        windowId: number;
+        bundle?: string;
+    }>;
+    /** The flow's app has a window on screen. */
+    appOnScreen?: boolean;
+    lockScreen: boolean;
+    keyboard: boolean;
+    /** The app's elements (or, when it is not on screen, every element), one line each, capped. */
+    elements: string[];
+    /** How many elements there were before the cap. */
+    elementCount: number;
+}
+/** An element that matches all but one clause of the step's selector. */
+interface NearMatch {
+    element: string;
+    /** The clause it fails, e.g. `text=Continue`. */
+    differs: string;
+}
+interface ReplayReport {
+    ok: boolean;
+    /** passed: every step ran; diverged: a step failed (exit 1); error: the replay could not run (exit 2). */
+    outcome: 'passed' | 'diverged' | 'error';
+    bundle?: string;
+    /** Steps run (first index, last index), 0-based and inclusive. */
+    range: [number, number];
+    steps: ReplayStepResult[];
+    failedStep?: number;
+    reason?: DivergenceReason;
+    message?: string;
+    /** The selector that was not satisfied (the step's, or its expect). */
+    selector?: string;
+    /** Screenshot taken when the flow diverged. */
+    screenshot?: string;
+    layout?: DivergenceLayout;
+    nearMatches?: NearMatch[];
+    /** Why the replay could not run (outcome error). */
+    error?: string;
+    warnings: string[];
+}
+interface ReplayFlowOptions {
+    config: ConfigProvider;
+    flow: Flow;
+    deviceSerial?: string;
+    logger?: Logger;
+    /** First step to run, 0-based. Default 0. */
+    from?: number;
+    /** Last step to run, 0-based and inclusive. Default: the last step. */
+    to?: number;
+    /** How long to wait for a step's selector and its expect, ms. Default 10000. A step's `timeoutMs` overrides it. */
+    stepTimeoutMs?: number;
+    /** Poll interval of those waits, ms. Default 500. */
+    pollMs?: number;
+    /** Save a screenshot after every step here (`step-<i>.jpeg`); the divergence screenshot goes here too. */
+    screenshotsDir?: string;
+    /** Act on a step's fallback point when its selector is not found, instead of diverging. */
+    fallback?: boolean;
+    /** Force-stop and start the flow's app before the first step. */
+    launch?: boolean;
+    /** Turn the screen on, swipe away a lock screen without a credential, keep it on during the run. Default true. */
+    wake?: boolean;
+    /** Take a screenshot when the flow diverges. Default true. */
+    divergenceScreenshot?: boolean;
+    onStep?: (result: ReplayStepResult) => void;
+    abortSignal?: AbortSignal;
+}
+/** Elements matching every clause of a DSL selector but one, for the divergence report. Pure. */
+declare function nearMatches(tree: DumpLayoutResult['tree'], selector: ElementSelector, limit?: number): NearMatch[];
+/** What is on screen, focused on the flow's app. Pure. */
+declare function summarizeDivergenceLayout(layout: DumpLayoutResult, bundle?: string): DivergenceLayout;
+/**
+ * Replay a flow on the device through the same path as `input --selector` and
+ * `wait --selector`: for each step, wait for its selector, act on the element
+ * (or on its fallback point), pause `waitMs`, then wait for its `expect`. Stops
+ * at the first step that fails and reports why (see {@link DivergenceReason}),
+ * with a screenshot, a summary of what was on screen, and the elements that
+ * nearly match the selector. Never throws for a divergence or a missing device:
+ * the report's outcome says which.
+ */
+declare function replayFlow(opts: ReplayFlowOptions): Promise<ReplayReport>;
+
+/**
+ * Parsing of `hitrace` text output: ftrace text whose user-space markers are
+ * `tracing_mark_write` events.
+ *
+ * What an OpenHarmony API 26 device writes (seen on a real capture):
+ *
+ * ```
+ *  ample.perfprobe-17599   (  17599) [005] ..... 149437.321439: tracing_mark_write: B|17599|H:ReceiveVsync name:WM_17599 ... vsyncId:16026, fd:26|M0538
+ *  ample.perfprobe-17599   (  17599) [005] ..... 149437.337990: tracing_mark_write: E|17599|M0538
+ *  OS_IPC_13_4366-4366     (   2693) [006] ..... 149433.777705: tracing_mark_write: B|2693|H:[a92ab18be48d19e,27224d3,0]#virtual int ...StartAbility(...)|I31
+ *  RSUniRenderThre-3012    (   2695) [004] ..... 149433.818003: tracing_mark_write: C|2695|H:JANK_FRAME_1-5F|1|M0538
+ * ```
+ *
+ * - `B|<tgid>|H:<name>|<level><tag>` opens a slice on the writing thread,
+ *   `E|<tgid>|<level><tag>` closes the innermost one. The trailing level and tag
+ *   (`I39`, `M0538`) are new in recent releases; older ones end at the name.
+ * - `S|<tgid>|H:<name>|<cookie>|…` / `F|…` start and finish an async slice,
+ *   `C|<tgid>|H:<name>|<value>|…` sets a counter.
+ * - Names carry an `H:` prefix and, when a HiTraceChain is active, a
+ *   `[chainId,spanId,parentSpanId]#` prefix; both are stripped.
+ * - The task column is the thread's comm (15 characters at most: an app's
+ *   main thread shows the END of its bundle name, `ample.perfprobe`) and its
+ *   tid; the parenthesised column is the tgid (`-------` for idle). Traces
+ *   recorded without the tgid column parse too (the B/E payload has the tgid).
+ *
+ * `sched_switch` lines are used, when the `sched` category was on, for the CPU
+ * time of main threads (tid == tgid).
+ */
+/** A closed (or, at the end of the trace, still open) synchronous slice. */
+interface TraceSlice {
+    tid: number;
+    /** Process (tgid) from the marker. */
+    pid: number;
+    /** Name without the `H:` and HiTraceChain prefixes. */
+    name: string;
+    /** Start, ms on the trace clock (boot time by default). */
+    ts: number;
+    /** Duration, ms; undefined when the slice was still open at the end of the trace. */
+    dur?: number;
+    /** Nesting depth on its thread, 0 for outermost. */
+    depth: number;
+}
+/** An async slice (`S`/`F` pair). */
+interface TraceAsyncSlice {
+    pid: number;
+    name: string;
+    cookie: string;
+    ts: number;
+    dur?: number;
+}
+interface TraceCounterSample {
+    pid: number;
+    name: string;
+    ts: number;
+    value: number;
+}
+interface TraceModel {
+    slices: TraceSlice[];
+    asyncSlices: TraceAsyncSlice[];
+    counters: TraceCounterSample[];
+    /** tid → its comm (the last one seen), and tid → tgid. */
+    threads: Map<number, {
+        comm: string;
+        pid: number;
+    }>;
+    /** First and last event timestamps, ms. */
+    startMs: number;
+    endMs: number;
+    /** Lines that looked like trace events. */
+    eventCount: number;
+    /** `tracing_mark_write` events. */
+    markerCount: number;
+    /** `sched_switch` events seen (0: the sched category was off). */
+    schedSwitchCount: number;
+    /**
+     * CPU time per thread id, ms, from sched_switch (empty without sched data). A
+     * process's main thread has tid == pid, so its entry is `get(pid)`; this needs no
+     * tgid column.
+     */
+    mainThreadCpuMs: Map<number, number>;
+    /**
+     * RenderService surface name → the pid that owns it, from
+     * `RSUniRender::QuickPrepare:[<surface>] nodeId[…] pid[<pid>]` (graphic category).
+     * An app's main window surface is named after the last part of its bundle
+     * name and an index (`perfprobe0`), which identifies the app's process when
+     * its thread names did not make it into the trace (`<...>`).
+     */
+    surfacePids: Map<string, number>;
+    /** From the `entries-in-buffer/entries-written: a/b` header, when present. */
+    entriesInBuffer?: number;
+    entriesWritten?: number;
+}
+interface ParseTraceOptions {
+    /** Keep only the slices this returns true for (called when a slice closes, and for open ones at the end). Default: all. */
+    keepSlice?: (slice: TraceSlice, threadComm: string | undefined) => boolean;
+}
+/** `H:[chain]#name` → `name`. Pure. */
+declare function cleanMarkerName(raw: string): string;
+/** Incremental parser; feed lines, then `finish()`. */
+declare class TraceParser {
+    private readonly opts;
+    private readonly model;
+    private readonly stacks;
+    private readonly openAsync;
+    private readonly switchedIn;
+    private headerDone;
+    constructor(opts?: ParseTraceOptions);
+    line(raw: string): void;
+    private bound;
+    private schedSwitch;
+    private marker;
+    private close;
+    finish(): TraceModel;
+}
+/** Parse hitrace text held in memory. Pure. */
+declare function parseTraceText(text: string, opts?: ParseTraceOptions): TraceModel;
+/** Parse a hitrace text file, streaming it line by line (traces run to hundreds of MB). */
+declare function parseTraceFile(file: string, opts?: ParseTraceOptions): Promise<TraceModel>;
+
+/**
+ * Turn a parsed hitrace capture into the numbers a performance gate needs:
+ * the app's frames (janky ones against the display's refresh interval), its
+ * cold-start time, main-thread load, and RenderService's own per-scene jank
+ * reports. Pure.
+ *
+ * Markers this relies on, as an OpenHarmony API 26 device (ArkUI, RenderService,
+ * ability runtime) emits them with the `ace graphic app ability window`
+ * categories:
+ *
+ * - Frames: on the app's main thread (tid == pid) each UI frame is one
+ *   `ReceiveVsync name:WM_<pid> … now:<vsync ns> expectedEnd:<ns> vsyncId:<n>`
+ *   slice enclosing `OnVsyncEvent` → `UIVsyncTask` → `FlushLayoutTask` /
+ *   `FlushRenderTask`. ArkUI only asks for a vsync when something is dirty, so
+ *   an idle app writes no frames. A frame's time is from its vsync (`now:`) to
+ *   the end of the slice, so a frame whose callback was held up by other work on
+ *   the main thread counts the wait too; it is janky when that exceeds one
+ *   refresh interval (the UI missed the next vsync).
+ * - Refresh interval: `VSyncReceiver:period:<ns>` inside those frames, else
+ *   `refreshPeriod is: <ns>`, else the caller's rate (hidumper), else 60 Hz.
+ * - Cold start: from `AbilityManagerClient::StartAbility` on the `aa` tool's
+ *   thread (else `AbilityManagerService::StartAbility` in foundation) before the
+ *   app's process appears, to `RSJankStats::ReportEventFirstFrame app pid <pid>`
+ *   in render_service (the first frame composited), else to the end of the app's
+ *   first UI frame.
+ * - Scenes: `RSJankStats::ReportEventJankFrame maxFrameTime is …`,
+ *   `ReportEventHitchTimeRatio hitch time ratio is … ms/s` and
+ *   `ReportEventResponse responseLatency is …ms` name a scene (APP_LIST_FLING,
+ *   ABILITY_OR_PAGE_SWITCH, …) and the bundle.
+ */
+interface PerfFrameStats {
+    /** UI frames the app's main thread produced. */
+    total: number;
+    /** Frames that took longer than one refresh interval (vsync to done). */
+    janky: number;
+    /** janky / total (0 without frames). */
+    jankRate: number;
+    p50Ms: number;
+    p95Ms: number;
+    maxMs: number;
+    /** Refresh intervals missed in all: Σ floor(frame / interval). */
+    missedVsyncs: number;
+    /** The longest frames, longest first: offset from the trace start and duration, ms. */
+    longest: Array<{
+        atMs: number;
+        ms: number;
+    }>;
+}
+interface PerfStartup {
+    /** Launch request to the app's first frame on screen, ms. */
+    coldMs: number;
+    /** The app's first UI frame on its main thread (initial build, measure, layout), ms. */
+    firstFrameMs: number | null;
+    /** Launch request to the app's process being forked, ms. */
+    processMs: number | null;
+    /** Where coldMs starts and ends. */
+    from: string;
+    to: string;
+}
+interface PerfScene {
+    /** RenderService's scene id, e.g. APP_LIST_FLING, ABILITY_OR_PAGE_SWITCH. */
+    scene: string;
+    page?: string;
+    maxFrameMs?: number;
+    maxHitchMs?: number;
+    hitchMsPerS?: number;
+    responseMs?: number;
+}
+interface TraceSummary {
+    /** The app's process (main thread id). */
+    pid: number | null;
+    /** Length of the capture, ms. */
+    durationMs: number;
+    refreshRateHz: number;
+    frames: PerfFrameStats;
+    startup: PerfStartup | null;
+    mainThread: {
+        /** Time in top-level traced slices on the main thread, ms. */
+        busyMs: number;
+        /** CPU time of the main thread, ms (only with the `sched` category). */
+        cpuMs: number | null;
+    };
+    scenes: PerfScene[];
+    notes: string[];
+}
+interface SummarizeTraceOptions {
+    bundle: string;
+    /** The app's pid when known (e.g. `pidof` after the capture); otherwise found from the trace. */
+    pid?: number;
+    /** Refresh rate to use when the trace has no vsync period. */
+    refreshRateHz?: number;
+    /** The capture cold-launched the app: report startup, and leave its first frame out of the frame stats. */
+    launched?: boolean;
+}
+/** Slices the summary needs; pass as `keepSlice` to keep memory flat on long captures. */
+declare function perfSliceFilter(slice: TraceSlice): boolean;
+/** The thread name an app's main thread gets: the bundle name, cut to its last (or first) 15 characters. */
+declare function commMatchesBundle(comm: string, bundle: string): boolean;
+/** The q-quantile (0..1) of sorted values, nearest-rank. */
+declare function quantile(sorted: number[], q: number): number;
+/** Candidate app pids: main threads named after the bundle, and pids whose markers name it (`…##<bundle>`). */
+declare function findAppPids(model: TraceModel, bundle: string): number[];
+/** Pids owning a RenderService surface named `<last part of the bundle><index>`, the app's main window. */
+declare function findAppPidsBySurface(model: TraceModel, bundle: string): number[];
+/** Summarise a capture for one bundle. Pure. */
+declare function summarizeTrace(model: TraceModel, opts: SummarizeTraceOptions): TraceSummary;
+
+/** One row of `hiperf report --sort dso,func`. */
+interface HiperfFunction {
+    /** Share of the samples' event count, %. */
+    percent: number;
+    dso: string;
+    func: string;
+}
+interface HiperfReport {
+    /** The sampled event, e.g. `hw-cpu-cycles`. */
+    event?: string;
+    samples: number;
+    top: HiperfFunction[];
+}
+/**
+ * Parse `hiperf report -i <data> --sort dso,func` text:
+ *
+ * ```
+ * Event: hw-cpu-cycles (type 0 id 0)
+ * Samples Count: 25
+ * Event Count: 20091
+ * Heating count dso                              func
+ * 39.16%   7868 [kernel.kallsyms]                _raw_spin_unlock_irqrestore
+ * 32.58%   6546 /system/lib/ld-musl-aarch64.so.1 /system/lib/ld-musl-aarch64.so.1+0x13fd6c
+ * ```
+ *
+ * Several events (several `Event:` sections) add up their samples; rows keep
+ * the first section's order. Pure.
+ */
+declare function parseHiperfReport(text: string, limit?: number): HiperfReport;
+
+/**
+ * Categories captured by default: ArkUI (frames), graphic (vsync period,
+ * RenderService first-frame and jank reports), app and ability (launch),
+ * window. `sched` adds the main thread's CPU time, at a large cost in buffer.
+ */
+declare const DEFAULT_TRACE_CATEGORIES: readonly ["ace", "app", "graphic", "ability", "window"];
+/** hitrace buffer, KB (its own default is 18432). */
+declare const DEFAULT_TRACE_BUFFER_KB = 65536;
+/** How long a `--launch` capture keeps running after the launch, and a plain capture lasts, ms. */
+declare const DEFAULT_PERF_FOR_MS = 5000;
+/** How long a `--flow` capture keeps running after the flow, ms. */
+declare const DEFAULT_PERF_FLOW_TAIL_MS = 1000;
+interface PerfTraceOptions {
+    config: ConfigProvider;
+    deviceSerial?: string;
+    logger?: Logger;
+    /** The app to measure. Defaults to the flow's bundle. */
+    bundle?: string;
+    /** Ability `launch` starts (default: the bundle's main ability, or the flow's). */
+    ability?: string;
+    /** Force-stop and cold-launch the bundle once tracing runs; reports startup. */
+    launch?: boolean;
+    /** Replay this flow while tracing (after the launch, with `launch`). */
+    flow?: Flow;
+    /** Replay options passed through (step timeout, fallback, screenshots). */
+    replay?: Pick<ReplayFlowOptions, 'stepTimeoutMs' | 'fallback' | 'screenshotsDir' | 'from' | 'to' | 'onStep'>;
+    /**
+     * Without a flow: how long to capture (after the launch with `launch`), ms;
+     * default {@link DEFAULT_PERF_FOR_MS}. With a flow: how long to keep capturing
+     * after it, default {@link DEFAULT_PERF_FLOW_TAIL_MS}.
+     */
+    forMs?: number;
+    /** Local path for the trace (default: a new file in the system temp dir). */
+    out?: string;
+    /** hitrace categories (default {@link DEFAULT_TRACE_CATEGORIES}). */
+    categories?: string[];
+    /** hitrace buffer size, KB (default {@link DEFAULT_TRACE_BUFFER_KB}). */
+    bufferKb?: number;
+    /** Turn the screen on and swipe away a credential-less lock screen, and keep it on. Default true. */
+    wake?: boolean;
+    /** Also sample the app's process with hiperf and report its top functions. */
+    hiperf?: boolean;
+    abortSignal?: AbortSignal;
+}
+interface PerfTraceReport {
+    /** The capture completed and was summarised. */
+    ok: boolean;
+    bundle: string;
+    durationMs: number;
+    /** The trace, pulled to the host. */
+    trace: string | null;
+    refreshRateHz: number | null;
+    frames: PerfFrameStats | null;
+    startup: PerfStartup | null;
+    flow: ReplayReport | null;
+    pid: number | null;
+    mainThread: TraceSummary['mainThread'] | null;
+    scenes: PerfScene[];
+    hiperf?: (HiperfReport & {
+        data: string | null;
+    }) | {
+        error: string;
+    };
+    categories: string[];
+    notes: string[];
+    /** Why the capture could not complete. */
+    error?: string;
+}
+interface PerfThresholds {
+    /** Fail when frames.jankRate is above this (0..1). */
+    maxJankRate?: number;
+    /** Fail when startup.coldMs is above this. */
+    maxStartupMs?: number;
+}
+interface PerfGateResult {
+    passed: boolean;
+    failures: string[];
+}
+/** Check a report against thresholds; a metric that was not measured fails a threshold set on it. Pure. */
+declare function evaluatePerfGate(report: Pick<PerfTraceReport, 'frames' | 'startup' | 'flow'>, t: PerfThresholds): PerfGateResult;
+/** `activeMode: 1080x2400, refreshRate=59` in `hidumper -s RenderService -a screen`. Pure. */
+declare function parseActiveRefreshRate(hidumper: string): number | null;
+/**
+ * Capture a hitrace trace on the device while the app cold-launches, a flow is
+ * replayed, or for a fixed time; pull it and summarise it for the bundle (see
+ * {@link summarizeTrace}). Never throws for a failed capture or a missing
+ * device: `ok` is false and `error` says why. Tracing is always stopped.
+ */
+declare function perfTrace(opts: PerfTraceOptions): Promise<PerfTraceReport>;
+
+/**
+ * Search over the OpenHarmony application-development documentation (`docs sync`
+ * clones `en/application-dev` of gitcode.com/openharmony/docs). The SDK typings
+ * behind `api search` / `api show` say whether a symbol exists and with what
+ * signature; the docs say how an API is used, which business error codes a kit
+ * throws and how the platform behaves. The index is deterministic, built in memory
+ * in a few seconds from titles, headings and an inverted word index, and answers a
+ * query in milliseconds; bodies are read on demand.
+ */
+interface DocEntry {
+    /** Path relative to the `en/application-dev` tree, e.g. `ui/arkts-navigation-jump.md`. */
+    path: string;
+    title: string;
+    /** Every `##`–`####` heading with its 1-based line. */
+    headings: DocHeading[];
+    bytes: number;
+}
+interface DocHeading {
+    line: number;
+    level: number;
+    text: string;
+}
+interface DocSearchHit {
+    path: string;
+    title: string;
+    score: number;
+    /** Headings that contain a query word (at most 6), to pass to `show`. */
+    headings: {
+        line: number;
+        text: string;
+    }[];
+    /** First paragraph after the title, trimmed. */
+    snippet: string;
+}
+interface DocSearchOptions {
+    /** At most n hits (default 8, at most 30). */
+    limit?: number;
+    /** Only documents under this subtree, e.g. `ui`, `reference/errorcodes`. */
+    section?: string;
+}
+interface DocSearchResult {
+    query: string;
+    /** The words the query was read as. */
+    terms: string[];
+    total: number;
+    hits: DocSearchHit[];
+}
+interface DocShowOptions {
+    /** A heading (or a distinctive part of it, case-insensitive): only that section. */
+    heading?: string;
+    /** Line cap (default 250, at most 1200). */
+    maxLines?: number;
+}
+type DocShowResult = {
+    found: true;
+    path: string;
+    /** The text (images and inline HTML dropped), cut at `maxLines` with a note. */
+    text: string;
+    truncated: boolean;
+    /** The headings inside what was shown. */
+    headings: {
+        line: number;
+        text: string;
+    }[];
+    /** Lines of the whole section before the cap. */
+    lines: number;
+} | {
+    found: false;
+    path: string;
+    error: string;
+    /** Similar document paths, or the document's headings when the heading did not match. */
+    suggestions: string[];
+};
+/** Every `.md` under `tree`, sorted, skipping figure directories. */
+declare function listMarkdown(tree: string): string[];
+/** Lower-cased words of a text: identifiers keep their dots, 2–40 chars, no long digit runs (hashes, ids). */
+declare function docTokens(text: string): string[];
+interface QueryTerm {
+    term: string;
+    /** 1 for a word of the query, 0.4 for a part of a camelCase or dotted identifier. */
+    weight: number;
+}
+/**
+ * The query's words plus the parts of camelCase and dotted identifiers
+ * (`NavPathStack` → nav, path, stack), so a guide that says "path stack" still matches;
+ * the parts weigh less and are not required.
+ */
+declare function docQueryTerms(query: string): QueryTerm[];
+/** Whether `term` occurs in `text` as a whole word (a trailing API-level suffix such as `insert10+` still counts). */
+declare function wordIn(text: string, term: string): boolean;
+/** Title and headings of one document. */
+declare function parseDoc(rel: string, text: string): DocEntry;
+/**
+ * Distinct index words of a document: its text plus the words of its path. A dotted
+ * identifier also contributes its parts (`this.pathstack.pushpathbyname` → pathstack,
+ * pushpathbyname) and a word with a trailing API-level suffix its stem
+ * (`pushpathbyname10` → pushpathbyname), so the words a reader types are the words
+ * the index holds.
+ */
+declare function docWords(rel: string, text: string): Set<string>;
+declare class DocsIndex {
+    readonly tree: string;
+    readonly docs: readonly DocEntry[];
+    /** Build time, ms. */
+    readonly buildMs: number;
+    /** word → ascending document ids (packed: 4 bytes per occurrence). */
+    private readonly postings;
+    private constructor();
+    /** The index of a tree, built on the first call of a process and kept. */
+    static load(tree: string): DocsIndex;
+    /** An index over in-memory documents (tests). `tree` is used by `show` for reading files. */
+    static fromDocs(tree: string, docs: {
+        path: string;
+        text: string;
+    }[]): DocsIndex;
+    /** Forget the cached index of a tree (after a sync). */
+    static forget(tree: string): void;
+    get size(): number;
+    private has;
+    /**
+     * Documents containing every word of the query (any of them when none does), scored by
+     * where the words occur: title, headings, path, body; a document whose title is exactly a
+     * query word, or that contains the whole query in a title or heading, ranks higher; the
+     * generated API reference ranks a little below the guides, system-API pages and tables of
+     * contents below everything.
+     */
+    search(query: string, o?: DocSearchOptions): DocSearchResult;
+    private snippet;
+    /**
+     * A document, or one of its sections: from the heading that matches `heading`
+     * (exactly, else by substring, case-insensitive) to the next heading of the same or a
+     * higher level. Image lines and inline HTML are dropped; the text is cut at `maxLines`
+     * with a note of what was left out.
+     */
+    show(rel: string, o?: DocShowOptions): DocShowResult;
+}
+
+/** The OpenHarmony documentation repository. */
+declare const DOCS_REPO = "https://gitcode.com/openharmony/docs";
+/** The part of the repository `docs search` reads; device, kernel and the Chinese tree stay out. */
+declare const DOCS_SPARSE_PATH = "en/application-dev";
+/** Sparse-checkout patterns (non-cone): the tree without its figures, which are about 90% of its bytes. */
+declare const DOCS_SPARSE_PATTERNS: readonly string[];
+/**
+ * The release branch of the docs repository for an SDK: from its version
+ * (`oh-uni-package.json`: `6.1.0.31` → `OpenHarmony-6.1-Release`, `5.1.0.107` →
+ * `OpenHarmony-5.1.0-Release`), else from the API level (18 → 5.1.0, 20 → 6.0,
+ * 23 → 6.1, 26 → 7.0), else `master`.
+ */
+declare function docsRefFor(sdk: {
+    api?: number;
+    version?: string;
+}): string;
+/** `{ api, version }` of an SDK API directory, from `ets/oh-uni-package.json`; empty when unreadable. */
+declare function readSdkRelease(sdkDir: string): {
+    api?: number;
+    version?: string;
+};
+/** Where the clones live: the `docsDir` config key, default `<sdkRootDir>/docs`. */
+declare function getDocsRootDir(config: ConfigProvider): string;
+/** The clone of one release: `<docs root>/<ref>`. */
+declare function docsDirFor(config: ConfigProvider, ref: string): string;
+/** The `en/application-dev` tree of a clone, or null when the release has not been synced. */
+declare function docsTree(docsDir: string): string | null;
+interface SyncDocsOptions {
+    /** The branch or tag to clone. */
+    ref: string;
+    /** Where to clone (normally `docsDirFor(config, ref)`). */
+    dir: string;
+    /** Repository URL (default {@link DOCS_REPO}). */
+    repo?: string;
+    logger?: Logger;
+    /** Per git step; the clone of a release takes a minute or two. Default 10 minutes. */
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+}
+interface SyncDocsResult {
+    dir: string;
+    ref: string;
+    /** Markdown files under `en/application-dev`. */
+    files: number;
+    /** False when the clone was created, true when an existing one was brought up to date. */
+    updated: boolean;
+    /** The commit the tree is at. */
+    commit?: string;
+}
+/**
+ * Clone or update the documentation of one release: a partial (`--filter=blob:none`),
+ * depth-1, sparse clone of `en/application-dev` without its figures, about 100 MB
+ * instead of the 2 GB a plain clone of the tree is. A second call on an existing
+ * clone fetches the branch head and resets to it. Needs `git` on the PATH.
+ */
+declare function syncDocs(opts: SyncDocsOptions): Promise<SyncDocsResult>;
+
 declare const VERSION: string;
 
-export { ALL_SDKS, APL_VALUES, APP_FEATURE_VALUES, type AbilityInfo, type AgcAuthInfo, AgcError, type Apl, type AppFeature, type ApplyChangesOptions, type ApplyChangesResult, type BuildHapOptions, type BuildHapResult, type BundleOptions, CancelledError, type CaptureBurstOptions, type CaptureLogOptions, type CaptureLogResult, ChecksumMismatchError, type CmdToolsFlavour, CmdToolsNotInstalledError, type CmdToolsStatus, type CmdWrapper, type CodelinterFinding, type CodelinterReport, type CodelinterResult, type CodelinterSummary, CommandFailedError, type ConfigKey, type ConfigProvider, type CreateScaffoldOptions, type CreateScaffoldResult, type DeveloperAgreementStatus, type DeviceFullInfo, type DeviceInfo, type DiscoverHapsOptions, type DisplaySize, type DisplaySizeOptions, type DownloadOptions, type DumpLayoutOptions, type DumpLayoutResult, type DumpLogOptions, type EmulatorStatus, type ExtractZipOptions, type FlatLayoutNode, type GenerateSigningConfigsOptions, type GestureUitestOptions, type GetDeviceInfoOptions, HARMONYOS_SDK_VERSIONS, HUAWEI_SITES, type HapAssetDiff, type HapSigningInfo, type HapZip, type HarmonyOsAutoSignOptions, type HarmonyOsSdk, type HarmonyOsSession, type HarmonyOsSessionOptions, type HarmonyOsSignHapOptions, type HarmonyOsSignHapResult, type HarmonyOsSigningResult, type HdcExecOptions, type HdcExecResult, type HdcShellOptions, type HidumperOptions, type HilogEntry, type HilogLevel, type HuaweiSite, type HuaweiSiteCode, type HuaweiTeam, type HuaweiUserInfo, INSTALL_TMP_DIRNAME, type InputType, type InstallAppOptions, type InstallAppResult, type InstallCandidate, type InstallCmdToolsOptions, type InstallEmulatorOptions, type InstallMethod, type InstallSdkFromArchiveOptions, type InstallSdkOptions, type InstallTempDir, type InstallTempDirOptions, type InstalledSdk, InsufficientSpaceError, type KeyboardState, type LaunchAppOptions, type LayoutNode, type LayoutSelector, type LocateTargetOptions, type LocatedTarget, type Logger, type ModuleHaps, OHOS_DAILY_BUILDS_URL, OHOS_URL_BASE, type OniroContext, OniroError, type OsFolder, type OutputSink, type ParamOptions, type PerformInputOptions, type PerformInputResult, type PickTargetFailure, type PickedHap, type PrepareSigningOptions, type PrepareSigningResult, type ProgressReporter, type ProgressUpdate, type ProjectModule, type Prompter, type ProvisionProfileInfo, type RawLayoutNode, type RawTouchEvent, type RebootDecision, type RebootOptions, type RecvFileOptions, type RunCodelinterOptions, type RunHvigorwOptions, type RunHvigorwResult, type RunOhpmOptions, type RunProcessOptions, type RunningProcess, type RuntimeOs, SIGNED_HAP_CHUNK_SIZE, SIGNING_ERRORS, type ScreenDump, type Screenshot, type ScreenshotOptions, type SdkArchiveInfo, type SdkInfo, SdkNotInstalledError, type SdkRelease, type SendFileOptions, type SendGestureOptions, type SendInputOptions, type SendRawTouchOptions, type SetHilogLevelOptions, type SignOpenHarmonyHapOptions, type SignOpenHarmonyHapResult, type SigningKind, type SigningMaterialPaths, type SigningPasswords, type StartEmulatorOptions, type StoredSession, type StreamHilogOptions, TMP_DIR_HINT, TargetNotFoundError, type TemplateOption, type TokenStore, type UiInputType, UnsupportedPlatformError, VERSION, type WaitForBootOptions, type WaitForBundleOptions, type WaitForConditionOptions, type WaitForLogOptions, type WaitForTargetOptions, type WatchLogOptions, type Waypoint, appSandboxDir, applyChanges, assertDevicePath, assertLayoutSelector, attemptHdcConnection, buildCmdWrapper, buildGestureCommands, buildGestureUitestCommand, buildHap, buildHvigorwArgs, buildInputCommand, buildRawTouchCommand, bundleNameFromHapConfig, captureBurst, captureLog, cleanCodelinterOutput, consoleLogger, createHarmonyOsSession, createInstallTempDir, createMaterial, createScaffold, createTempWorkDir, createTokenStore, decideInstallMethod, decideReboot, decryptPwd, dedupEntries, defaultContext, defaultPaths, defaultSignedHapPath, describeLayoutNode, detectAaStartFailure, detectCmdToolsFlavour, detectInstallFailure, detectProjectSdkVersion, detectRuntimeOs, detectSigningConfigNames, diagnoseBuildFailure, diffEntryNames, diffHapAssets, discoverHaps, downloadAndInstallSdk, downloadFile, dumpLayout, dumpLog, dumpRenderService, dumpScreen, dumpWindow, encryptPwd, ensureFreeSpace, ensureInstallOk, ensureOhModules, ensureOk, ensureRemoteOk, escapeCmdArgument, escapeCmdCommand, existingHapOrUnsigned, extractTarball, extractZipWithProgress, findAppProcessId, findCmdToolsSourceDir, findCoveredNodes, findHarmonyOsSdk, findKeyboardWindow, findLayoutNodes, findMissingProjectSdk, findRunningProcess, findSdkOsDir, flattenLayout, forceStop, formatBytes, generateSigningConfigs, getBundleName, getCmdToolsBin, getCmdToolsDownloadUrl, getCmdToolsPath, getCmdToolsStatus, getDeviceInfo, getDisplaySize, getEmulatorDir, getEmulatorStatus, getFreeSpaceBytes, getHdcPath, getHvigorwPath, getImeBundles, getInstalledSdks, getKey, getMainAbility, getOhosBaseSdkHome, getOhpmPath, getOsFolder, getSdkFilename, getSdkRootDir, getSupportedSdksForUi, harmonyOsAutoSign, harmonyOsSdkLabelForApi, harmonyOsSignHap, hdcClientFailure, hdcExec, hdcTargetArgs, hdcTargetArgsFor, hideKeyboard, hilogTimeMs, installApp, installCmdTools, installEmulator, installFailureReason, installSdkFromArchive, isBundleInstalled, isCmdToolsInstalled, isEmulatorInstalled, isOutOfSpaceError, isRamBackedPath, isUnsignedHap, isUsableDevice, isValidBundleName, isValidProjectName, killProcessTree, launchApp, listAbilities, listDevices, listModules, listRunningProcesses, listTemplates, locateTarget, missingProjectRootFiles, needsCmdWrapper, nonInteractivePrompter, noopLogger, noopProgress, normaliseLocalPath, paramGet, paramGetMany, paramSet, parseBounds, parseCodelinterFindings, parseCodelinterReport, parseDeviceList, parseHilogLine, parseImeBundles, parseMainAbilityFromBmDump, parseParamValues, parseRemoteExit, performInput, pickHap, pickSigningKind, pickTarget, prepareSigning, pruneLayout, readHapBundleName, readHapSigningInfo, readJson5File, readJsonFile, readProvisionProfile, readZipEntry, reboot, recvFile, removeCmdTools, removeEmulator, removeSdk, removeTempWorkDir, requireHarmonyOsSdk, resolveDeviceSerial, resolveKeyEvent, resolveTmpRoot, runCodelinter, runHvigorw, runOhpm, runProcess, scopedLogger, selectDevice, sendFile, sendGesture, sendInput, sendRawTouch, setHilogLevel, shell, shellChecked, signOpenHarmonyHap, spawnCompat, startEmulator, staticConfig, stopEmulator, streamHilog, takeScreenshot, toLongPath, toSpaceError, uninstallApp, unsignedHapRejection, validateTemplateLayout, verifySha256, waitForBoot, waitForBundle, waitForCondition, waitForLog, waitForTarget, watchLog, waypointsToRawEvents, withHapZip, withoutWindow, writeJson5File, writeJsonFile };
+export { ALL_SDKS, API_INDEX_FORMAT, APL_VALUES, APP_FEATURE_VALUES, type AbilityInfo, type AgcAuthInfo, AgcError, type AnalyzeFaultLogOptions, type ApiElsewhere, type ApiEntry, type ApiIndex, type ApiLanguage, type ApiSdkSelection, type ApiSearchHit, type ApiSearchOptions, type ApiSearchResult, type ApiShowResult, type ApiSymbolKind, type Apl, type AppFeature, type ApplyChangesOptions, type ApplyChangesResult, type ArktsCheckOptions, type ArktsCheckReport, type ArktsCheckSdk, type ArktsCheckSummary, BLANK_BACKGROUND_SHARE, BLANK_MAX_STDDEV, BLANK_PHASH_DISTANCE, type BaseImageFingerprint, type BinderEdge, type BinderInfo, type BinderNode, type BinderPropagation, type BinderTransaction, type BlankAnalysis, type BuildApiIndexOptions, type BuildDiagnostic, BuildFailedError, type BuildHapOptions, type BuildHapResult, type BuildReport, type BuildSdk, type BuildSummary, type BundleOptions, CMD_TOOLS_REQUIRED, CancelledError, type CaptureBurstOptions, type CaptureLogOptions, type CaptureLogResult, type CertificateInfo, ChecksumMismatchError, type CmdToolsFlavour, type CmdToolsFsOps, type CmdToolsInfo, CmdToolsNotInstalledError, type CmdToolsSdk, type CmdToolsStatus, type CmdWrapper, type CodelinterFinding, type CodelinterReport, type CodelinterResult, type CodelinterSummary, CommandFailedError, type ConfigKey, type ConfigProvider, type CppCrashLog, type CrashJson, type CrashVerdict, type CreateScaffoldOptions, type CreateScaffoldResult, DEFAULT_BOOT_TIMEOUT_SECONDS, DEFAULT_EMULATOR_PID_FILE, DEFAULT_PERF_FLOW_TAIL_MS, DEFAULT_PERF_FOR_MS, DEFAULT_SMOKE_DELAY_MS, DEFAULT_SMOKE_PID_TIMEOUT_MS, DEFAULT_TRACE_BUFFER_KB, DEFAULT_TRACE_CATEGORIES, DOCS_REPO, DOCS_SPARSE_PATH, DOCS_SPARSE_PATTERNS, type Declaration, type Decorator, type DeveloperAgreementStatus, type DeviceFullInfo, type DeviceInfo, type DiagnosticSource, type DiscoverHapsOptions, type DisplaySize, type DisplaySizeOptions, type DivergenceLayout, type DivergenceReason, type DocEntry, type DocHeading, type DocSearchHit, type DocSearchOptions, type DocSearchResult, type DocShowOptions, type DocShowResult, type DocTags, DocsIndex, type DoctorCheck, type DoctorOptions, type DoctorProject, type DoctorReport, type DoctorStatus, type DoctorVersions, type DownloadOptions, type DslSelector, type DumpLayoutOptions, type DumpLayoutResult, type DumpLogOptions, EMULATOR_KERNEL_APPEND, type ElementQuery, type ElementSelector, type EmulatorAccel, type EmulatorHealth, type EmulatorInstanceStatus, type EmulatorStatus, type ExtractZipOptions, FAULTLOG_DIR, FAULTLOG_TEMP_DIR, FAULT_LOG_FAMILIES, FLOW_ACTIONS, FLOW_VERSION, type FaultCompleteness, type FaultConfidence, type FaultLogClassification, type FaultLogDeviceOptions, type FaultLogEntry, type FaultLogFamily, type FaultLogKind, type FindInOtherSdksOptions, type FlatLayoutNode, type Flow, type FlowAction, type FlowDevice, FlowFormatError, type FlowFromRecordingInput, type FlowFromRecordingResult, type FlowPoint, type FlowStep, type FrameArea, type FreezeLog, type FreezeReport, type GenerateSigningConfigsOptions, type GenerateSigningConfigsResult, type GestureUitestOptions, type GetDeviceInfoOptions, type GreyImage, type GreyscaleDecoder, HARMONYOS_SDK_VERSIONS, HASH_BITS, HUAWEI_SITES, type HapAssetDiff, type HapProfileReport, type HapSigner, type HapSigningInfo, type HapVerifyStatus, type HapZip, type HarmonyOsAutoSignOptions, type HarmonyOsLoginOptions, type HarmonyOsSdk, type HarmonyOsSdkListing, type HarmonyOsSdkSource, type HarmonyOsSession, type HarmonyOsSessionOptions, type HarmonyOsSignHapOptions, type HarmonyOsSignHapResult, type HarmonyOsSigningResult, type HdcBootProbe, type HdcExecOptions, type HdcExecResult, type HdcShellOptions, type HealthInputs, type HidumperOptions, type HilogEntry, type HilogLevel, type HiperfFunction, type HiperfReport, type HuaweiSite, type HuaweiSiteCode, type HuaweiTeam, type HuaweiUserInfo, INSTALL_TMP_DIRNAME, type ImageComparison, type IndexedLayoutNode, type InputType, type InstallAppOptions, type InstallAppResult, type InstallCandidate, type InstallCmdToolsOptions, type InstallCmdToolsResult, type InstallEmulatorOptions, type InstallMethod, type InstallSdkFromArchiveOptions, type InstallSdkOptions, type InstallTempDir, type InstallTempDirOptions, type InstalledSdk, InsufficientSpaceError, type JsCrashLog, type JsFrame, type KeyboardState, LAYOUT_COMPONENTS, LAYOUT_MOVED_IOU, type LatestCrashOptions, type LaunchAppOptions, type LayoutDiff, type LayoutDiffNode, type LayoutMatch, type LayoutMatchKind, type LayoutNode, type LayoutSelector, type LayoutSummary, type LayoutWindow, type LayoutWindowSummary, type ListFaultLogsOptions, type ListWindowsOptions, type LoadApiIndexOptions, type LoadedApiIndex, type LocateTargetOptions, type LocatedTarget, type Logger, MAX_FAULTLOG_BYTES, MAX_POOL_INSTANCE, type MissingSdkSymbol, type ModuleHaps, NO_WINDOW, type NativeFrame, type NearMatch, OHOS_DAILY_BUILDS_URL, OHOS_URL_BASE, type OniroContext, OniroError, type OsFolder, type OutputSink, POOL_DEFAULT_MEMORY, POOL_DEFAULT_RESOLUTION, POOL_DEFAULT_SMP, POOL_DISKS, POOL_REQUIRED_IMAGES, type ParamOptions, type ParseTraceOptions, type ParsedBuildOutput, type ParsedTestOutput, type PerfFrameStats, type PerfGateResult, type PerfScene, type PerfStartup, type PerfThresholds, type PerfTraceOptions, type PerfTraceReport, type PerformInputOptions, type PerformInputResult, type PickTargetFailure, type PickedHap, type PoolInstancePorts, type PoolInstanceState, type PoolQemuSpec, type PrepareSigningOptions, type PrepareSigningResult, type ProgressReporter, type ProgressUpdate, type ProjectModule, type Prompter, type ProvisionProfileInfo, type QueryTerm, type RawLayoutNode, type RawTouchEvent, type ReadFaultLogOptions, type RebootDecision, type RebootOptions, type RecordFlowOptions, type RecordFlowResult, type RecordedElement, type RecordingTimes, type RecvFileOptions, type ReplayFlowOptions, type ReplayReport, type ReplayStepResult, type ResolveApiSdkOptions, type RouteSpecResult, type RunCodelinterOptions, type RunHvigorwOptions, type RunHvigorwResult, type RunOhpmOptions, type RunProcessOptions, type RunTestsOptions, type RunningProcess, type RuntimeOs, SAME_MAX_CHANGE_RATIO, SAME_MAX_HASH_DISTANCE, SELECTOR_KEYS, SIGNED_HAP_CHUNK_SIZE, SIGNING_ERRORS, type ScannedSource, type ScreenDump, type ScreenPage, type ScreenPlaceholder, type ScreenRoute, type ScreenSpecResult, type ScreensInventory, type ScreensOptions, type ScreensSpec, type ScreensSpecReport, type Screenshot, type ScreenshotOptions, type SdkArchiveInfo, type SdkInfo, SdkNotInstalledError, type SdkPkgInfo, type SdkRelease, type SelectorClause, type SelectorKey, type SelectorOperator, SelectorParseError, type SendFileOptions, type SendGestureOptions, type SendInputOptions, type SendRawTouchOptions, type SetHilogLevelOptions, type SignOpenHarmonyHapOptions, type SignOpenHarmonyHapResult, type SigningKind, type SigningMaterialPaths, type SigningMaterialSummary, type SigningPasswords, type SmokeCheckOptions, type SmokeCrashProbe, type SmokeCrashProbeArgs, type SmokeResult, type SourceComment, type StackFrame, type StartEmulatorOptions, type StartPoolInstanceOptions, type StopPoolInstanceOptions, type StoredSession, type StreamHilogOptions, type SummarizeTraceOptions, type SyncDocsOptions, type SyncDocsResult, THREAD_HEADER_RE, TMP_DIR_HINT, TargetNotFoundError, type TemplateOption, type TestCaseResult, type TestOutcome, type TestRunReport, type TestStatus, type TestSummary, type ThreadStack, type Token, type TokenKind, type TokenStore, type TraceAsyncSlice, type TraceCounterSample, type TraceModel, TraceParser, type TraceSlice, type TraceSummary, UI_RECORD_CSV, type UiInputType, type UiRecordEvent, type UiRecordFinger, UnsupportedPlatformError, VERSION, type VerifyHapOptions, type VerifyHapResult, type WaitForBootOptions, type WaitForBundleOptions, type WaitForConditionOptions, type WaitForLogOptions, type WaitForTargetOptions, type WaitPoolInstanceReadyOptions, type WakeScreenOptions, type WakeScreenResult, type WatchLogOptions, type Waypoint, type WindowInfo, type XPathExpression, type XPathSelector, aaTestCommand, alignTouches, allIndexed, analyzeBlank, analyzeFaultLog, apiIndexCachePath, apiIndexKey, apiLevelOf, appSandboxDir, applyChanges, arktsCheckerScript, assertDevicePath, assertLayoutSelector, assertPoolInstance, attemptHdcConnection, boxIoU, buildApiIndex, buildCmdWrapper, buildGestureCommands, buildGestureUitestCommand, buildHap, buildHvigorwArgs, buildInputCommand, buildOutputTail, buildPoolQemuArgs, buildPropagation, buildRawTouchCommand, buildWithDiagnostics, bundleNameFromHapConfig, captureBurst, captureLog, checkArkts, checkCmdTools, checkCmdToolsFlavour, checkDisk, checkNode, checkScreensAgainstSpec, checkSigning, classifyEmulatorHealth, classifyFaultLog, clauseMatches, cleanBuildOutput, cleanCodelinterOutput, cleanMarkerName, commMatchesBundle, compareImages, consoleLogger, createHarmonyOsSession, createInstallTempDir, createMaterial, createScaffold, createTempWorkDir, createTokenStore, cropRows, dHash, decideInstallMethod, decideOutcome, decideReboot, decryptPwd, dedupEntries, defaultContext, defaultPaths, defaultSignedHapPath, dependencyApiDiagnostic, describeBuildSdk, describeCmdTools, describeLayoutNode, describeProfileValidity, describeProject, describeReplacement, describeSigningMaterial, deserializeApiIndex, detectAaStartFailure, detectCmdToolsFlavour, detectInstallFailure, detectProjectSdkVersion, detectRuntimeOs, detectSigningConfigNames, diagnoseBuildFailure, diffEntryNames, diffHapAssets, diffLayouts, discoverHaps, docQueryTerms, docTokens, docWords, docsDirFor, docsRefFor, docsTree, downloadAndInstallSdk, downloadFile, dumpLayout, dumpLog, dumpRenderService, dumpScreen, dumpWindow, elementAt, emulatorAccelArgs, encryptPwd, ensureFreeSpace, ensureInstallOk, ensureOhModules, ensureOk, ensureRemoteOk, escapeCmdArgument, escapeCmdCommand, evaluatePerfGate, evaluateXPath, existingHapOrUnsigned, expectFor, extractStackErrors, extractTarball, extractZipWithProgress, faultloggerCommand, fieldSelector, findApiInOtherSdks, findAppPids, findAppPidsBySurface, findAppProcessId, findCmdToolsSourceDir, findCoveredNodes, findHapSignTool, findHarmonyOsSdk, findKeyboardWindow, findLayoutNodes, findMissingProjectSdk, findRunningProcess, findSdkOsDir, findVisibleMatch, flatFrameHash, flatLayoutNode, flattenLayout, flowFromRecording, forceStop, formatBytes, formatFlow, formatHapVerification, formatSelector, formatUtc, generateSigningConfigs, getApiIndexCacheDir, getBundleName, getCmdToolsBin, getCmdToolsDownloadUrl, getCmdToolsPath, getCmdToolsStatus, getDefaultInstanceStatus, getDeviceInfo, getDisplaySize, getDocsRootDir, getEmulatorDir, getEmulatorStatus, getFreeSpaceBytes, getHarmonyOsSdkListing, getHdcPath, getHvigorwPath, getImeBundles, getInstalledSdks, getKey, getMainAbility, getOhosBaseSdkHome, getOhpmPath, getOsFolder, getPoolInstanceStatus, getSdkFilename, getSdkRootDir, getSupportedSdksForUi, hammingDistance, harmonyOsAutoSign, harmonyOsSdkLabelForApi, harmonyOsSignHap, hasOwnFields, hdcClientFailure, hdcExec, hdcTargetArgs, hdcTargetArgsFor, hideKeyboard, hilogSection, hilogTimeMs, holdScreenOn, indexLayout, installApp, installCmdTools, installEmulator, installFailureReason, installSdkFromArchive, installedApiLevels, inventoryScreens, isBundleInstalled, isCmdToolsInstalled, isCrashJson, isElementSelector, isEmulatorInstalled, isInstanceProcess, isLockScreenShown, isOutOfSpaceError, isPidAlive, isRamBackedPath, isTcpPortFree, isTestHap, isUnsignedHap, isUsableDevice, isValidBundleName, isValidProjectName, keystrokeChar, keystrokeName, killProcessTree, latestCrash, launchApp, listAbilities, listDevices, listFaultLogs, listLayoutWindows, listMarkdown, listModules, listPoolInstanceNumbers, listPoolInstanceStatuses, listRunningProcesses, listTemplates, listWindows, livePoolPids, loadApiIndex, locateTarget, matchSelector, mergeDocBlocks, missingProjectRootFiles, missingSdkSymbols, nameParts, nearMatches, needsCmdWrapper, nodeLabel, nonInteractivePrompter, noopLogger, noopProgress, normaliseLocalPath, normalizeFaultTime, normalizeKit, ohModulesPackage, pHash, pagesMatching, paramGet, paramGetMany, paramSet, parseActiveRefreshRate, parseArktsCheckOutput, parseBinder, parseBounds, parseBuildOutput, parseCodelinterFindings, parseCodelinterReport, parseCppCrash, parseCrashRecordHeads, parseDeviceList, parseDeviceTime, parseDoc, parseDocBlock, parseFaultLogList, parseFaultLogName, parseFlow, parseFrame, parseFreeze, parseHilogLine, parseHiperfReport, parseImeBundles, parseJsCrash, parseJsFrame, parseLayoutBaseline, parseMainAbilityFromBmDump, parseNativeFrame, parseParamValues, parsePowerState, parseProvisionProfile, parseRecorderForeground, parseRemoteExit, parseSelector, parseTestOutput, parseThreadStacks, parseTouchDowns, parseTraceFile, parseTraceText, parseUiRecordLines, parseUtcOffset, parseWindowList, parseXPath, perfSliceFilter, perfTrace, performInput, pickHap, pickSigningKind, pickTarget, pixelChangeRatio, poolInstanceDir, poolInstancePorts, poolRootDir, prepareSigning, probeEmulatorBoot, pruneLayout, quantile, rawWindowSubtree, readCmdToolsInfo, readDefaultEmulatorPid, readFaultLog, readFlowFile, readHapBundleName, readHapSigningInfo, readJson5File, readJsonFile, readLogTail, readPoolState, readProvisionProfile, readSdkPkg, readSdkRelease, readTestModuleName, readZipEntry, reboot, recordFlow, recvFile, removeCmdTools, removeEmulator, removeSdk, removeTempWorkDir, renderCrashJson, replayFlow, requireHarmonyOsSdk, resizeGrey, resolveApiSdk, resolveArktsCheckSdk, resolveBuildSdk, resolveDeviceSerial, resolveKeyEvent, resolveProjectSdkDir, resolveSelectorKey, resolveTmpRoot, runCodelinter, runDoctor, runHvigorw, runOhpm, runProcess, runTests, scanEts, scopedLogger, sdkTooOldDiagnostic, searchApi, selectDevice, selectableTree, selectorAttribute, selectorFor, sendFile, sendGesture, sendInput, sendRawTouch, serializeApiIndex, setHilogLevel, shell, shellChecked, showApi, signOpenHarmonyHap, signingMismatch, smokeCheck, smokeVerdict, spawnCompat, startEmulator, startPoolInstance, stateFile, staticConfig, statusFromCode, stopEmulator, stopPoolInstance, streamHilog, stripHidumperBanner, suggestApiSymbols, summarizeDivergenceLayout, summarizeLayout, summarizeTrace, syncDocs, takeScreenshot, testHapPath, toLongPath, toSpaceError, uninstallApp, unsignedHapRejection, validateTemplateLayout, verifyHap, verifyHapExitCode, verifySha256, waitForBoot, waitForBundle, waitForCondition, waitForLog, waitForTarget, waitPoolInstanceReady, wakeAndUnlock, watchLog, waypointsToRawEvents, windowNotFoundError, windowSubtree, withHapZip, withoutWindow, wordIn, writeJson5File, writeJsonFile, writePoolState };