@ohos-perf/core 0.2.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -26,6 +26,27 @@ declare class StreamerNotFoundError extends OhosPerfError {
26
26
  code?: string;
27
27
  });
28
28
  }
29
+ declare class EmulatorCommandError extends OhosPerfError {
30
+ readonly output: string;
31
+ constructor(message: string, output: string, opts?: {
32
+ cause?: unknown;
33
+ code?: string;
34
+ });
35
+ }
36
+ declare class EmulatorImageMissingError extends OhosPerfError {
37
+ readonly installCommand: string;
38
+ constructor(message: string, installCommand: string, opts?: {
39
+ cause?: unknown;
40
+ code?: string;
41
+ });
42
+ }
43
+ declare class EmulatorNotFoundError extends OhosPerfError {
44
+ readonly searchedPaths: string[];
45
+ constructor(searchedPaths: string[], opts?: {
46
+ cause?: unknown;
47
+ code?: string;
48
+ });
49
+ }
29
50
  declare class IngestError extends OhosPerfError {
30
51
  readonly stderr: string;
31
52
  constructor(message: string, stderr: string, code?: string, opts?: {
@@ -149,6 +170,23 @@ declare class Hdc {
149
170
  * HDC_SHELL_FAILED.
150
171
  */
151
172
  shell(target: string, cmd: string): Promise<HdcResult>;
173
+ /**
174
+ * Run a long-lived shell command and collect its stdout for `durationMs`.
175
+ *
176
+ * `hilog` never exits on its own, so the host clock bounds the capture and
177
+ * the child is killed at the end. Killing is the normal path, not an error:
178
+ * the result carries whatever was printed before the kill and `code` is the
179
+ * exit code only when the child exited on its own (`null` when killed).
180
+ *
181
+ * A command that fails immediately (non-zero exit before the deadline) is
182
+ * still returned rather than thrown: the collector decides whether the
183
+ * output is usable, and an empty result is what it must see.
184
+ */
185
+ shellFor(target: string, cmd: string, durationMs: number): Promise<{
186
+ stdout: string;
187
+ stderr: string;
188
+ code: number | null;
189
+ }>;
152
190
  recv(target: string, devicePath: string, localPath: string): Promise<void>;
153
191
  send(target: string, localPath: string, devicePath: string): Promise<void>;
154
192
  fport(target: string, local: number, remote: number): Promise<void>;
@@ -180,7 +218,7 @@ declare class Hdc {
180
218
  * probe output that produced the verdict. Callers never have to infer "empty
181
219
  * result" from "unsupported device".
182
220
  */
183
- type CapabilityId = 'trace.frames' | 'trace.sched' | 'trace.binder' | 'trace.thread_state' | 'trace.ark' | 'perf.samples' | 'perf.pmu' | 'mem.procfs' | 'mem.native_hook' | 'mem.gpu' | 'render.fps_live' | 'render.hitch' | 'render.vsync' | 'ui.tree' | 'ui.gesture' | 'power.xpower' | 'net.io' | 'disk.io' | 'js.heap' | 'coverage' | 'startup.app_startup';
221
+ type CapabilityId = 'trace.frames' | 'trace.sched' | 'trace.binder' | 'trace.thread_state' | 'trace.ark' | 'perf.samples' | 'perf.pmu' | 'mem.procfs' | 'mem.native_hook' | 'mem.gpu' | 'render.fps_live' | 'render.hitch' | 'render.vsync' | 'ui.tree' | 'ui.gesture' | 'ui.capture' | 'power.xpower' | 'net.io' | 'disk.io' | 'js.heap' | 'coverage' | 'hilog.stream' | 'startup.app_startup' | 'static.hap';
184
222
  /**
185
223
  * How directly a capability measures the thing it claims to measure.
186
224
  *
@@ -322,12 +360,12 @@ declare class Streamer {
322
360
  * without a fresh file all fail. Every filesystem failure is surfaced as an
323
361
  * IngestError, never a raw fs error.
324
362
  */
325
- convert(inputPath: string, outputDbPath: string): Promise<void>;
363
+ convert(inputPath: string, outputDbPath: string, soDir?: string): Promise<void>;
326
364
  /**
327
365
  * `shell: false` is mandatory: the DevEco install path contains spaces, and
328
366
  * a shell would split `D:/Application/DevEco Studio/...` into pieces.
329
367
  */
330
- spawnSpec(inputPath: string, outputDbPath: string): SpawnSpec;
368
+ spawnSpec(inputPath: string, outputDbPath: string, soDir?: string): SpawnSpec;
331
369
  private spawnSpecFor;
332
370
  /** Spawn without a shell so spaces in the executable path stay intact. */
333
371
  protected spawnProcess(command: string, args: string[]): Promise<SpawnResult>;
@@ -350,6 +388,12 @@ interface SceneLayout {
350
388
  hidumperFile: string;
351
389
  /** `ui.json` from a `uitest dumpLayout` capture. */
352
390
  uiFile: string;
391
+ /** `screenshot.png` from a `uitest screenCap` capture. */
392
+ screenshotFile: string;
393
+ /** `hilog.log` from a `--hilog` capture: the raw device log stream. */
394
+ hilogFile: string;
395
+ /** `hilog.jsonl` from the same capture: one typed row per log line. */
396
+ hilogJsonlFile: string;
353
397
  metadataFile: string;
354
398
  }
355
399
  declare function createSceneLayout(root: string): SceneLayout;
@@ -635,6 +679,33 @@ declare class HidumperCollector implements Collector {
635
679
  }, layout: SceneLayout): Promise<HidumperCapture>;
636
680
  }
637
681
 
682
+ /** The command whose stdout is the log stream. */
683
+ declare const HILOG_COMMAND = "hilog";
684
+ /**
685
+ * Captures the device's hilog stream into the scene.
686
+ *
687
+ * The output is the raw log text, one line per record. Parsing happens
688
+ * offline (`parseHilogText`), so the artifact is exactly what the device
689
+ * printed and a parser change never requires a re-capture.
690
+ */
691
+ declare class HilogCollector implements Collector {
692
+ readonly id = "hilog";
693
+ readonly provides: CapabilityId[];
694
+ collect(hdc: Hdc, target: string, opts: {
695
+ durationMs: number;
696
+ }, layout: SceneLayout): Promise<{
697
+ lines: number;
698
+ }>;
699
+ }
700
+ /**
701
+ * Read the captured log back.
702
+ *
703
+ * Returns `undefined` when the scene has no `hilog.log`: an absent artifact
704
+ * is a scene that never captured logs, and the analyzer turns that into a
705
+ * degraded reason rather than an empty measurement.
706
+ */
707
+ declare function readHilogText(layout: SceneLayout): string | undefined;
708
+
638
709
  /**
639
710
  * hiperf collection driver.
640
711
  *
@@ -822,7 +893,32 @@ interface UiNode {
822
893
  readonly scrollable: boolean;
823
894
  /** Direct child count. */
824
895
  readonly children: number;
896
+ /**
897
+ * `bounds` parsed into a rect, or `undefined` when the string did not match
898
+ * the measured `"[l,t][r,b]"` form. The diff compares geometry edge by edge,
899
+ * so it needs numbers; a node whose bounds did not parse simply has none.
900
+ */
901
+ readonly boundsRect?: {
902
+ readonly left: number;
903
+ readonly top: number;
904
+ readonly right: number;
905
+ readonly bottom: number;
906
+ };
907
+ /**
908
+ * Every string attribute the dump carried, for the UI diff's attribute
909
+ * comparison. Optional so a caller that only lists nodes does not pay for a
910
+ * copy of every field; `flattenUiTree` always fills it.
911
+ */
912
+ readonly attributes?: Readonly<Record<string, string>>;
825
913
  }
914
+ /**
915
+ * Parse a `bounds` string into a rect.
916
+ *
917
+ * The dump writes `"[0,0][1080,2340]"`. Anything else — a different separator,
918
+ * a float, a single corner — is `undefined` rather than a guess: the UI diff
919
+ * treats geometry as numbers, and a guessed rect would mark the wrong region.
920
+ */
921
+ declare function parseBounds(bounds: string): UiNode['boundsRect'];
826
922
  /**
827
923
  * Flatten a `dumpLayout` document depth-first in document order.
828
924
  *
@@ -834,16 +930,27 @@ interface UiNode {
834
930
  * A document that is not a tree at all yields `[]` rather than throwing: the
835
931
  * caller asked "what is on screen", and "nothing parseable" is a valid answer
836
932
  * that the `ui.get` query can return as zero rows.
933
+ *
934
+ * `opts.full` adds `boundsRect` and the raw `attributes` map, which the UI diff
935
+ * needs and `ui.get` does not: a query row carries the documented subset, so an
936
+ * agent reading a screen does not get every renderer field with it.
837
937
  */
838
- declare function flattenUiTree(root: unknown): UiNode[];
938
+ declare function flattenUiTree(root: unknown, opts?: {
939
+ full?: boolean;
940
+ }): UiNode[];
839
941
  /**
840
942
  * Read a captured `ui.json` and flatten it.
841
943
  *
842
944
  * A missing file is not an error (the scene may have no uitest capture);
843
945
  * invalid JSON is likewise `undefined`, because a truncated dump is not a
844
946
  * screen with no nodes.
947
+ *
948
+ * `opts.full` is passed through to {@link flattenUiTree}: the UI diff reads a
949
+ * scene with it, the `ui.get` query does not.
845
950
  */
846
- declare function readUiTree(path: string): UiNode[] | undefined;
951
+ declare function readUiTree(path: string, opts?: {
952
+ full?: boolean;
953
+ }): UiNode[] | undefined;
847
954
 
848
955
  /** Fixed device-side path; removed before and after every dump. */
849
956
  declare const DEVICE_UI_PATH = "/data/local/tmp/ohosperf_ui.json";
@@ -872,6 +979,199 @@ declare class UitestCollector implements Collector {
872
979
  }, layout: SceneLayout): Promise<UiNode[]>;
873
980
  }
874
981
 
982
+ /** Fixed device-side path; removed before and after every capture. */
983
+ declare const DEVICE_SCREENSHOT_PATH = "/data/local/tmp/ohosperf_screen.png";
984
+ /** What a successful capture produced, for `scene.json`. */
985
+ interface ScreenshotCapture {
986
+ readonly width: number;
987
+ readonly height: number;
988
+ readonly bytes: number;
989
+ }
990
+ /**
991
+ * Capture a screenshot into `screenshot.png`.
992
+ *
993
+ * `uitest screenCap -p <path>` writes the PNG on the device and prints
994
+ * `ScreenCap saved to <path>`. The marker is required for the same reason the
995
+ * UI dump requires its own: hdc exits 0 even when the device tool refuses, so
996
+ * an exit code proves nothing.
997
+ *
998
+ * The order mirrors the other collectors — remove the fixed device path, run,
999
+ * require the marker, require a non-empty file, `recv`, then verify. The
1000
+ * verification here is a full decode: a truncated transfer is the failure this
1001
+ * collector exists to catch, and a PNG whose dimensions cannot be read is not a
1002
+ * screenshot. A failed capture never leaves `screenshot.png` behind, so a later
1003
+ * analysis cannot mistake the previous screen for this capture's.
1004
+ */
1005
+ declare class ScreenshotCollector implements Collector {
1006
+ readonly id = "screenshot";
1007
+ readonly provides: CapabilityId[];
1008
+ collect(hdc: Hdc, target: string, opts: {
1009
+ timeoutMs?: number;
1010
+ }, layout: SceneLayout): Promise<ScreenshotCapture>;
1011
+ }
1012
+
1013
+ /**
1014
+ * UI gesture injection.
1015
+ *
1016
+ * `uitest uiInput` is the device-side injector. Measured on the Mate 60
1017
+ * (OpenHarmony 7.0.0.111) over plain `hdc shell`:
1018
+ *
1019
+ * - a successful injection prints `No Error` on stdout;
1020
+ * - the host exit code is **always 0**, even when the tool refuses the
1021
+ * gesture and exits 1 inside the device shell — so the marker is the only
1022
+ * proof of acceptance;
1023
+ * - a swipe velocity outside 200..40000 prints a warning and silently uses
1024
+ * the default, so the request would not be what actually happened.
1025
+ *
1026
+ * The driver therefore validates everything it can before the shell call and
1027
+ * quotes text as one shell argument. Every text value is single-quoted;
1028
+ * control characters are rejected because they are not typable and would
1029
+ * smuggle separators into the command line.
1030
+ */
1031
+
1032
+ type Gesture = {
1033
+ readonly action: 'click';
1034
+ readonly x: number;
1035
+ readonly y: number;
1036
+ } | {
1037
+ readonly action: 'swipe';
1038
+ readonly fromX: number;
1039
+ readonly fromY: number;
1040
+ readonly toX: number;
1041
+ readonly toY: number;
1042
+ readonly velocity?: number;
1043
+ } | {
1044
+ readonly action: 'key';
1045
+ readonly key: string | number;
1046
+ } | {
1047
+ readonly action: 'inputText';
1048
+ readonly x: number;
1049
+ readonly y: number;
1050
+ readonly text: string;
1051
+ } | {
1052
+ readonly action: 'text';
1053
+ readonly text: string;
1054
+ };
1055
+ interface GestureResult {
1056
+ /** The gesture as performed, echoed for logs and JSON consumers. */
1057
+ readonly gesture: Gesture;
1058
+ /** The tool's stdout, trimmed (`No Error`, or a warning plus `No Error`). */
1059
+ readonly output: string;
1060
+ }
1061
+ /**
1062
+ * Inject gestures through `uitest uiInput`.
1063
+ *
1064
+ * `perform` takes the transport method it needs rather than the whole `Hdc`,
1065
+ * so a caller (Device) can hand in the shared transport and a test can hand in
1066
+ * a three-line fake.
1067
+ */
1068
+ declare class GestureDriver {
1069
+ perform(hdc: Pick<Hdc, 'shell'>, target: string, gesture: Gesture): Promise<GestureResult>;
1070
+ }
1071
+
1072
+ /**
1073
+ * The human- and machine-readable description of one captured scene.
1074
+ *
1075
+ * `startedAtNs` is device uptime in nanoseconds (read from `/proc/uptime`), the
1076
+ * same clock base as trace `ts` values — never host `Date.now()`. It is the
1077
+ * start marker the startup analyzer falls back to when `app_startup` is empty.
1078
+ * `capture.startedAtMs` is host wall-clock and exists for humans only.
1079
+ */
1080
+ interface SceneStepRef {
1081
+ /** 1-based round within a scenario run. */
1082
+ readonly round: number;
1083
+ /** 0-based position of the step in the scenario's `steps` array. */
1084
+ readonly index: number;
1085
+ readonly id: string;
1086
+ }
1087
+ interface SceneMetadata {
1088
+ version: 1;
1089
+ app: {
1090
+ packageName: string;
1091
+ processNames: string[];
1092
+ };
1093
+ pids: number[];
1094
+ deviceId: string;
1095
+ startedAtNs?: number;
1096
+ /**
1097
+ * Present only when the scene was captured by a scenario step. A scene
1098
+ * copied out of a run therefore still says which step produced it, without
1099
+ * needing the run's `steps.json` beside it.
1100
+ */
1101
+ step?: SceneStepRef;
1102
+ capture?: {
1103
+ startedAtMs: number;
1104
+ durationMs: number;
1105
+ collectors: string[];
1106
+ /**
1107
+ * Present only when a hiperf capture ran. `samples` may be 0: an idle app
1108
+ * yields no samples, which is a real capture, not a missing one.
1109
+ */
1110
+ hiperf?: {
1111
+ samples: number;
1112
+ /**
1113
+ * Present only when the capture passed a symbol directory. `true` means
1114
+ * symbolization was *requested* — the converter was given `--So_dir` —
1115
+ * not that every frame came back named; a directory missing the app's
1116
+ * libraries still leaves addresses. Absent means the scene did not
1117
+ * record the attempt, which is not the same as "no".
1118
+ */
1119
+ symbolized?: boolean;
1120
+ };
1121
+ /**
1122
+ * Present only when a hidumper capture ran. `frames` may be 0: a screen
1123
+ * that presented nothing is a measurement, not a missing capture.
1124
+ */
1125
+ hidumper?: {
1126
+ frames: number;
1127
+ };
1128
+ /**
1129
+ * Present only when a uitest capture ran. `nodes` may be 0: a blank screen
1130
+ * is a measurement, not a missing capture.
1131
+ */
1132
+ uitest?: {
1133
+ nodes: number;
1134
+ };
1135
+ /**
1136
+ * Present only when a screenshot capture ran. `bytes` is the size of
1137
+ * `screenshot.png`; a capture that produced a zero-byte or undecodable file
1138
+ * is a failure, so the counts here are always positive.
1139
+ */
1140
+ screenshot?: {
1141
+ width: number;
1142
+ height: number;
1143
+ bytes: number;
1144
+ };
1145
+ /**
1146
+ * Present only when a hilog capture ran. `lines` may be 0 only if the
1147
+ * collector succeeded on an empty stream, which it treats as a failure;
1148
+ * the field records the count the collector reported.
1149
+ */
1150
+ hilog?: {
1151
+ lines: number;
1152
+ };
1153
+ };
1154
+ }
1155
+ /**
1156
+ * Writes `scene.json` next to the other scene artifacts.
1157
+ *
1158
+ * The scene root is created when needed. The file is pretty-printed with two
1159
+ * spaces and ends with one newline so it is diff-friendly and byte-stable.
1160
+ */
1161
+ declare function writeSceneMetadata(layout: SceneLayout, meta: SceneMetadata): void;
1162
+ /**
1163
+ * Reads a scene's `scene.json`, or `undefined` when it cannot be trusted.
1164
+ *
1165
+ * A missing file, invalid JSON, a non-object document, a `version` other than
1166
+ * `1`, or a document missing the required fields all yield `undefined`: a
1167
+ * partially valid description would be worse than none. `startedAtNs` is
1168
+ * optional, but a non-positive (including zero) or non-finite value is dropped
1169
+ * from the result (the file itself is never rewritten) so consumers can treat
1170
+ * "no marker" as one case. Uptime 0 addresses the trace origin, not the capture
1171
+ * start, so accepting it would only produce a nonsense startup duration.
1172
+ */
1173
+ declare function readSceneMetadata(layout: SceneLayout): SceneMetadata | undefined;
1174
+
875
1175
  /**
876
1176
  * Device probe.
877
1177
  *
@@ -977,10 +1277,40 @@ interface CollectOptions extends TraceCollectOptions {
977
1277
  events?: readonly string[];
978
1278
  callStacks?: boolean;
979
1279
  };
1280
+ /**
1281
+ * A host directory of shared objects to symbolize the hiperf capture with.
1282
+ *
1283
+ * Passed to the perf conversion as `--So_dir`, so frames come out named
1284
+ * instead of `file+0xoffset`. Requires `hiperf`: without a perf capture
1285
+ * there is nothing to symbolize, and the request is refused before any
1286
+ * device call rather than silently ignored. The directory must exist on
1287
+ * this host, which is checked here too.
1288
+ */
1289
+ soDir?: string;
980
1290
  /** Also sample the RenderService fps/hitch counters for `durationMs`. */
981
1291
  hidumper?: boolean;
982
1292
  /** Also dump the on-screen UI tree. */
983
1293
  uitest?: boolean;
1294
+ /**
1295
+ * Also capture a screenshot of the whole screen.
1296
+ *
1297
+ * Independent of `uitest`: a screenshot without a tree is a valid capture,
1298
+ * and the UI analyzer reports the half that is missing rather than zeros.
1299
+ */
1300
+ screenshot?: boolean;
1301
+ /**
1302
+ * Also stream the device's `hilog` for `durationMs`.
1303
+ *
1304
+ * `hilog` is device-wide and needs no app, so this works on an app-less
1305
+ * capture. The raw log lands in `hilog.log`; parsing happens offline.
1306
+ */
1307
+ hilog?: boolean;
1308
+ /**
1309
+ * Record this capture as one step of a scenario run. Written into
1310
+ * `scene.json`, so the scene names its own step after being copied out of
1311
+ * the run directory.
1312
+ */
1313
+ step?: SceneStepRef;
984
1314
  }
985
1315
  interface CollectSession {
986
1316
  /** Capture, then convert and open the scene. */
@@ -996,6 +1326,9 @@ interface DeviceDeps {
996
1326
  hiperf?: HiperfCollector;
997
1327
  hidumper?: HidumperCollector;
998
1328
  uitest?: UitestCollector;
1329
+ screenshot?: ScreenshotCollector;
1330
+ hilog?: HilogCollector;
1331
+ gesture?: GestureDriver;
999
1332
  }
1000
1333
  /**
1001
1334
  * A probed device.
@@ -1026,6 +1359,14 @@ declare class Device {
1026
1359
  stderr: string;
1027
1360
  code: number;
1028
1361
  }>;
1362
+ /**
1363
+ * Inject a UI gesture through `uitest uiInput`.
1364
+ *
1365
+ * The capability gate is the same contract `collect` uses: an unavailable
1366
+ * `ui.gesture` throws before any device call, and the message carries the
1367
+ * matrix's reason (`uitest not present on device`).
1368
+ */
1369
+ gesture(request: Gesture): Promise<GestureResult>;
1029
1370
  /**
1030
1371
  * Prepare a capture session. The capability gate runs here so a device that
1031
1372
  * cannot produce frames fails before any device state is touched.
@@ -1047,6 +1388,331 @@ declare class Device {
1047
1388
  */
1048
1389
  declare function connect(opts?: ConnectOptions): Promise<Device>;
1049
1390
 
1391
+ /**
1392
+ * HarmonyOS emulator lifecycle.
1393
+ *
1394
+ * DevEco Studio ships `Emulator.exe`, which owns the instance directory format,
1395
+ * the image signature check and the QEMU launch. This module drives it rather
1396
+ * than reproducing it: `EmulatorClient` spawns and parses, `EmulatorLifecycle`
1397
+ * proves state transitions with `hdc`.
1398
+ *
1399
+ * Two measured properties shape everything here:
1400
+ *
1401
+ * 1. **The exit code carries no information.** `Unable to start the emulator`,
1402
+ * `Emulator: Unknown option 'bogus'.` and a silently rejected `-create` all
1403
+ * exit 0. Success is proven by re-reading state, never by `$?`.
1404
+ * 2. **`-start` and `-stop` are fire-and-forget.** Both return in well under a
1405
+ * second while the instance is still booting or still shutting down, so a
1406
+ * caller that trusts their output reports the wrong state.
1407
+ */
1408
+
1409
+ /** One instance as `-list -details` reports it. */
1410
+ interface EmulatorInstance {
1411
+ readonly name: string;
1412
+ readonly running: boolean;
1413
+ /** `os.apiVersion`, e.g. `"24"`. */
1414
+ readonly apiVersion?: string;
1415
+ /** `imageSubPath`, e.g. `system-image/HarmonyOS-6.1.1/phone_all_x86/`. */
1416
+ readonly imageDir?: string;
1417
+ /** Absolute instance directory. */
1418
+ readonly instancePath: string;
1419
+ readonly uuid?: string;
1420
+ /** `os.osVersion`, e.g. `HarmonyOS 6.1.1(24)`. */
1421
+ readonly osVersion?: string;
1422
+ /** The hdc target id; present only when it can be attributed unambiguously. */
1423
+ readonly target?: string;
1424
+ /** Why `target` is absent, when it is absent for a reason other than "not running". */
1425
+ readonly targetReason?: string;
1426
+ }
1427
+ /** One row of `-imageList -downloaded true`. */
1428
+ interface EmulatorImage {
1429
+ readonly deviceType: string;
1430
+ /** `osVersion`, e.g. `"HarmonyOS 6.1.1(24)"`. */
1431
+ readonly osVersion: string;
1432
+ readonly downloaded: boolean;
1433
+ /** `SoftWareVersion`, e.g. `"6.1.0.126"`. */
1434
+ readonly softwareVersion: string;
1435
+ readonly releaseType?: string;
1436
+ }
1437
+ /** What `create` needs; validated by the lifecycle layer before it is spawned. */
1438
+ interface CreateEmulatorRequest {
1439
+ readonly name: string;
1440
+ readonly deviceType: string;
1441
+ readonly osVersion: string;
1442
+ readonly screenProfile?: string;
1443
+ readonly memoryGb?: number;
1444
+ readonly storageGb?: number;
1445
+ }
1446
+ interface EmulatorClientOptions {
1447
+ /** Explicit `Emulator.exe`; checked first by {@link EmulatorClient.resolvePath}. */
1448
+ emulatorPath?: string;
1449
+ /** Environment used both for spawning and for the `OHOS_PERF_EMULATOR`/`PATH` lookup. */
1450
+ env?: Env;
1451
+ /**
1452
+ * Override the built-in install candidate list. Tests pass `[]` so the
1453
+ * search list is exactly the one they assert on.
1454
+ */
1455
+ commonPaths?: string[];
1456
+ /** `-instancePath` for every command that accepts it. */
1457
+ instancePath?: string;
1458
+ /** `-imageRoot` for every command that accepts it. */
1459
+ imageRoot?: string;
1460
+ /**
1461
+ * Host platform, for the binary name and the install candidate list.
1462
+ * Defaults to `process.platform`; injectable so a test can exercise the
1463
+ * non-Windows branch on any host. Typed as `string` on purpose: `NodeJS`
1464
+ * types are not part of this package's published declarations.
1465
+ */
1466
+ platform?: string;
1467
+ }
1468
+ /**
1469
+ * The `Emulator.exe` process surface.
1470
+ *
1471
+ * Every method here runs the binary and interprets its output; none of them
1472
+ * decides what a state *means*. That split is what lets the lifecycle layer be
1473
+ * tested with a plain object while this layer is tested against recorded output.
1474
+ */
1475
+ declare class EmulatorClient {
1476
+ private readonly opts;
1477
+ private readonly env;
1478
+ private readonly platform;
1479
+ private resolvedPath?;
1480
+ private parsedVersion?;
1481
+ private configRoots?;
1482
+ constructor(opts?: EmulatorClientOptions);
1483
+ /**
1484
+ * The instance root, in the spec's discovery order: explicit option, then
1485
+ * `OHOS_PERF_EMULATOR_INSTANCE`, then `.emu_config`'s `emuPath`, then
1486
+ * `%LOCALAPPDATA%\Huawei\Emulator\deployed`.
1487
+ *
1488
+ * `undefined` only when none of those exist — off Windows there is no
1489
+ * `%LOCALAPPDATA%` default, and inventing one would pass the binary a
1490
+ * relative path. The resolved root is always passed explicitly rather than
1491
+ * left to the binary's own discovery, so the argv records where the answer
1492
+ * came from.
1493
+ */
1494
+ private resolvedInstanceRoot;
1495
+ /** The image root, discovered the same way via `imagePath` and `%LOCALAPPDATA%\Huawei\Sdk`. */
1496
+ private resolvedImageRoot;
1497
+ /** Read `.emu_config` at most once per client. */
1498
+ private emuConfig;
1499
+ /**
1500
+ * Search order: explicit path -> OHOS_PERF_EMULATOR -> common DevEco
1501
+ * installs -> PATH. Throws {@link EmulatorNotFoundError} listing every
1502
+ * candidate in order, so a caller can see exactly what was tried.
1503
+ */
1504
+ resolvePath(): Promise<string>;
1505
+ /**
1506
+ * Banner version, e.g. `6.1.1.200`. The real binary prints
1507
+ * `HarmonyOS Emulator :6.1.1.200` and exits 0.
1508
+ */
1509
+ version(): Promise<string>;
1510
+ /**
1511
+ * `-list -details`, parsed and sorted by name.
1512
+ *
1513
+ * `[Empty]` is the real binary's answer when the instance root holds none;
1514
+ * it is success with zero instances, not a parse failure.
1515
+ */
1516
+ listDetailed(): Promise<EmulatorInstance[]>;
1517
+ /** `-imageList -downloaded true`, parsed and sorted by type then version. */
1518
+ imageList(): Promise<EmulatorImage[]>;
1519
+ /**
1520
+ * `-start <name>`.
1521
+ *
1522
+ * Fire-and-forget by design: the real binary returns in well under a second
1523
+ * and the instance keeps running after it exits, so the caller must poll
1524
+ * {@link listDetailed} for the state change.
1525
+ */
1526
+ /**
1527
+ * `-start <name>`.
1528
+ *
1529
+ * Measured on 6.1.1.200: a **valid** `-start` does not exit. The process
1530
+ * becomes the emulator (it holds ~1 GB and keeps running), so waiting for
1531
+ * its pipes to close waits forever. An **invalid** one prints `Unable to
1532
+ * start the emulator` and exits 1 in under 100 ms.
1533
+ *
1534
+ * So this settles: it collects output until the child exits or
1535
+ * {@link START_SETTLE_MS} passes, whichever comes first, then drops the
1536
+ * pipes and leaves the child running. The exit code is therefore not a
1537
+ * verdict on success — {@link EmulatorLifecycle.start} proves that by
1538
+ * re-reading state, which is the same rule the rest of this class follows.
1539
+ * Detaching keeps the emulator alive when this process exits.
1540
+ */
1541
+ startInstance(name: string): Promise<void>;
1542
+ /** `-stop <name>`; fire-and-forget, see {@link startInstance}. */
1543
+ stopInstance(name: string): Promise<void>;
1544
+ /**
1545
+ * `-create`, with no validation.
1546
+ *
1547
+ * The binary silently ignores a bad device type, an unknown OS version or a
1548
+ * name that already exists — it prints nothing and exits 0. Deciding those
1549
+ * is {@link EmulatorLifecycle.create}'s job, before this runs.
1550
+ */
1551
+ createInstance(req: CreateEmulatorRequest): Promise<void>;
1552
+ /**
1553
+ * Spawn without a shell so install paths with spaces stay one argv element.
1554
+ *
1555
+ * `opts.settleMs` exists for `-start`, which does not exit on success. When
1556
+ * set, the promise resolves once the child exits or the window elapses —
1557
+ * whichever is first — after which the pipes are destroyed and the child is
1558
+ * detached so it survives this process. Output captured so far is returned
1559
+ * with code 0, and failure-line classification still applies, so a fast
1560
+ * rejection is caught either way.
1561
+ *
1562
+ * `detach` is only set alongside `settleMs`: a child that outlives the
1563
+ * caller must not hold the caller's console or pipes open.
1564
+ */
1565
+ protected spawnProcess(command: string, args: string[], opts?: {
1566
+ settleMs?: number;
1567
+ detach?: boolean;
1568
+ }): Promise<{
1569
+ stdout: string;
1570
+ stderr: string;
1571
+ code: number;
1572
+ }>;
1573
+ /** `-instancePath` when a root was resolved; no flag otherwise. */
1574
+ private instancePathArgs;
1575
+ /** `-imageRoot` when a root was resolved; no flag otherwise. */
1576
+ private imageRootArgs;
1577
+ /** Resolve the binary, spawn, and classify the output. */
1578
+ private run;
1579
+ /**
1580
+ * Classify a completed spawn.
1581
+ *
1582
+ * The exit code is 0 for every failure the binary reports through a failure
1583
+ * line, so a failure line outranks the code: an invalid `-start` prints
1584
+ * `Unable to start the emulator` **and** exits 1, and reporting only
1585
+ * `-start exited 1` would discard the one sentence that says what happened.
1586
+ *
1587
+ * The match is structural (`Emulator: `, `Unable to `) rather than a list of
1588
+ * known sentences: the binary uses its own name as a prefix for argument
1589
+ * errors and `Unable to …` for operational ones, and a future message of
1590
+ * either shape should fail loudly instead of being read as success.
1591
+ */
1592
+ private assertOk;
1593
+ /** Parse a JSON array, naming the first line of output when it is not one. */
1594
+ private parseJson;
1595
+ }
1596
+ /** The client operations the lifecycle needs; `EmulatorClient` satisfies it structurally. */
1597
+ interface EmulatorBackend {
1598
+ listDetailed(): Promise<EmulatorInstance[]>;
1599
+ imageList(): Promise<EmulatorImage[]>;
1600
+ startInstance(name: string): Promise<void>;
1601
+ stopInstance(name: string): Promise<void>;
1602
+ createInstance(req: CreateEmulatorRequest): Promise<void>;
1603
+ }
1604
+ /** What a successful {@link EmulatorLifecycle.start} reports. */
1605
+ interface EmulatorStartResult {
1606
+ readonly name: string;
1607
+ /** The hdc target id, ready for `collect --target`. */
1608
+ readonly target: string;
1609
+ /** True when the instance was already running before this call. */
1610
+ readonly alreadyRunning: boolean;
1611
+ /** Wall-clock milliseconds this call spent waiting for boot. */
1612
+ readonly waitedMs: number;
1613
+ }
1614
+ /** What a successful {@link EmulatorLifecycle.stop} reports. */
1615
+ interface EmulatorStopResult {
1616
+ readonly name: string;
1617
+ /** False when the instance was not running; nothing was sent to `-stop`. */
1618
+ readonly wasRunning: boolean;
1619
+ }
1620
+ /** The `hdc` operations the lifecycle needs; `Hdc` satisfies it structurally. */
1621
+ interface HdcSlice {
1622
+ listTargets(): Promise<HdcTarget[]>;
1623
+ shell(target: string, cmd: string): Promise<{
1624
+ stdout: string;
1625
+ stderr: string;
1626
+ code: number;
1627
+ }>;
1628
+ }
1629
+ interface EmulatorLifecycleOptions {
1630
+ /** Defaults to a real {@link EmulatorClient}; tests inject a plain object. */
1631
+ client?: EmulatorBackend;
1632
+ /** Defaults to a real `Hdc`; tests inject a plain object. */
1633
+ hdc?: HdcSlice;
1634
+ /** Total budget for `start`, across all three phases. */
1635
+ startTimeoutMs?: number;
1636
+ /** Total budget for `stop`. */
1637
+ stopTimeoutMs?: number;
1638
+ /** Poll interval for every wait. */
1639
+ pollMs?: number;
1640
+ /** Injection point for tests; production leaves it unset. */
1641
+ now?: () => number;
1642
+ }
1643
+ /**
1644
+ * State and waiting, as distinct from spawning and parsing.
1645
+ *
1646
+ * `-start` and `-stop` both return before the state they report has settled,
1647
+ * and `-list -details` is the only authority on it. Every method here re-reads
1648
+ * that state rather than trusting a command's exit or its success line.
1649
+ */
1650
+ declare class EmulatorLifecycle {
1651
+ private readonly client;
1652
+ private readonly hdc;
1653
+ private readonly startTimeoutMs;
1654
+ private readonly stopTimeoutMs;
1655
+ private readonly pollMs;
1656
+ private readonly now;
1657
+ constructor(opts?: EmulatorLifecycleOptions);
1658
+ /**
1659
+ * Instances with a `target` attached when it can be attributed.
1660
+ *
1661
+ * The port is not knowable from config — `hw.hdc.port` is `notset` by
1662
+ * default, and the same instance has been observed on different ports in
1663
+ * different sessions. So a target is reported only when there is exactly one
1664
+ * running instance and exactly one connected TCP target; guessing would
1665
+ * produce a plausible-looking wrong answer, which is worse than a reason.
1666
+ */
1667
+ list(): Promise<EmulatorInstance[]>;
1668
+ /**
1669
+ * Start `name` and wait until its guest has finished booting.
1670
+ *
1671
+ * Three phases, one deadline: the instance reports `isRunning`, a new
1672
+ * connected TCP target appears, and `bootevent.boot.completed` turns true.
1673
+ * Each phase has its own timeout message because "it timed out" leaves the
1674
+ * caller unable to tell a slow boot from a broken start.
1675
+ *
1676
+ * A timeout never stops the emulator: a half-booted instance is the evidence
1677
+ * of what went wrong, and the message says how to remove it.
1678
+ */
1679
+ start(name: string, opts?: {
1680
+ timeoutMs?: number;
1681
+ }): Promise<EmulatorStartResult>;
1682
+ /**
1683
+ * Stop `name` and wait until the instance reports `isRunning: false`.
1684
+ *
1685
+ * The real `-stop` prints `Stop emulator <name> successfully` and returns in
1686
+ * about 140 ms, while the instance keeps reporting `isRunning: true` for
1687
+ * several seconds. Trusting its output would report a stop that has not
1688
+ * happened, so this re-reads state.
1689
+ */
1690
+ stop(name: string, opts?: {
1691
+ timeoutMs?: number;
1692
+ }): Promise<EmulatorStopResult>;
1693
+ /**
1694
+ * Create an instance, validating before anything is spawned.
1695
+ *
1696
+ * The binary is silent about every rejection measured — a bad device type, an
1697
+ * unknown OS version, a duplicate name and a missing image all print nothing
1698
+ * and exit 0. So the checks here are the only thing between the caller and a
1699
+ * create that did nothing, and the post-create re-read is the only proof that
1700
+ * it did something.
1701
+ */
1702
+ create(req: CreateEmulatorRequest): Promise<EmulatorInstance>;
1703
+ /**
1704
+ * Poll `attempt` until it returns a value, or the deadline passes.
1705
+ *
1706
+ * The deadline is absolute so one budget covers every phase of `start`;
1707
+ * a per-phase budget would multiply the caller's timeout by three.
1708
+ *
1709
+ * `advice` is the caller's, because the cleanup differs: a start that timed
1710
+ * out left a half-booted instance, while a stop that timed out already ran
1711
+ * the one command that removes it.
1712
+ */
1713
+ private waitUntil;
1714
+ }
1715
+
1050
1716
  /**
1051
1717
  * hiprofiler plugin templates.
1052
1718
  *
@@ -1100,68 +1766,613 @@ declare function memoryPlugin(opts?: MemoryPluginOptions): HiprofilerPlugin;
1100
1766
  declare const PLANE_A_PLUGINS: readonly HiprofilerPlugin[];
1101
1767
 
1102
1768
  /**
1103
- * The human- and machine-readable description of one captured scene.
1769
+ * hilog line parsing.
1104
1770
  *
1105
- * `startedAtNs` is device uptime in nanoseconds (read from `/proc/uptime`), the
1106
- * same clock base as trace `ts` values — never host `Date.now()`. It is the
1107
- * start marker the startup analyzer falls back to when `app_startup` is empty.
1108
- * `capture.startedAtMs` is host wall-clock and exists for humans only.
1771
+ * A hilog line is:
1772
+ *
1773
+ * ```
1774
+ * MM-DD HH:MM:SS.mmm PID TID LEVEL DOMAIN/TAG message
1775
+ * ```
1776
+ *
1777
+ * The timestamp carries **no year**. The year comes from the scene's capture
1778
+ * metadata, and a month/day that would place the line after the capture is
1779
+ * read as the previous year: the alternative (this year) invents a future log,
1780
+ * which no real capture can contain.
1781
+ *
1782
+ * A line that does not match is kept as a raw row (`parsed: false`) rather
1783
+ * than dropped. A rule count computed over silently discarded lines is a
1784
+ * number nobody can check.
1109
1785
  */
1110
- interface SceneMetadata {
1111
- version: 1;
1112
- app: {
1113
- packageName: string;
1114
- processNames: string[];
1786
+ /** The five documented levels, plus whatever character the device printed. */
1787
+ type HilogLevel = 'D' | 'I' | 'W' | 'E' | 'F' | string;
1788
+ /** One log line, parsed or raw. `index` is the file order, 0-based. */
1789
+ interface HilogLine {
1790
+ readonly index: number;
1791
+ /** Nanoseconds since the Unix epoch; `0` on a raw row. */
1792
+ readonly ts: number;
1793
+ readonly level: HilogLevel;
1794
+ readonly pid: number;
1795
+ readonly tid: number;
1796
+ readonly domain: string;
1797
+ readonly tag: string;
1798
+ readonly message: string;
1799
+ readonly parsed: boolean;
1800
+ }
1801
+ /**
1802
+ * Parse one line.
1803
+ *
1804
+ * `year` is the capture year and `captureNs` the capture instant in
1805
+ * nanoseconds — the same clock base as trace `ts` and every query window. A
1806
+ * line later than the capture by more than half a year is moved to `year - 1`,
1807
+ * the only reading that cannot produce a future log from a year-less format.
1808
+ */
1809
+ declare function parseHilogLine(line: string, year: number, captureNs: number): HilogLine;
1810
+ /**
1811
+ * How to place a year-less timestamp on the timeline.
1812
+ *
1813
+ * `year` comes from `scene.json`'s capture time and is **absent** for a scene
1814
+ * with no descriptor. A raw scene still has a log worth counting, so an absent
1815
+ * year yields raw rows (`parsed: false`, `ts: 0`) rather than a guess: 1970 or
1816
+ * the host clock would be a confident wrong instant, and every `hilog.around`
1817
+ * window built from it would be wrong too.
1818
+ */
1819
+ interface HilogParseOptions {
1820
+ readonly year?: number;
1821
+ /** The capture instant, ns since epoch. `0` means unknown. */
1822
+ readonly captureNs: number;
1823
+ }
1824
+ /**
1825
+ * Parse a whole log.
1826
+ *
1827
+ * Splits on `\r?\n` and drops exactly one trailing empty element (the file's
1828
+ * final newline), so `lines.count` equals the number of lines a reader sees.
1829
+ * Interior blank lines stay as raw rows.
1830
+ */
1831
+ declare function parseHilogText(text: string, opts: HilogParseOptions): HilogLine[];
1832
+
1833
+ /** One pattern rule, in the shape HapRay's `hilog.patterns` uses. */
1834
+ interface HilogRule {
1835
+ readonly name: string;
1836
+ readonly regex: string;
1837
+ /**
1838
+ * Which capture groups to extract, 1-based. `0` means the whole match.
1839
+ * Defaults to `[0]`, matching upstream's `groups` default.
1840
+ */
1841
+ readonly groups?: readonly number[];
1842
+ /**
1843
+ * Either one comparison per extracted group (`['!=4', '>512']`) or one
1844
+ * expression over `$1`, `$2`, … (`'$1 * $2 > $3 * $4'`).
1845
+ */
1846
+ readonly conditions?: string | readonly string[];
1847
+ /**
1848
+ * `message` (default) matches the log message only, so a rule cannot match
1849
+ * a tag by accident. `line` matches the whole raw line, with `^`/`$`
1850
+ * anchored per line.
1851
+ */
1852
+ readonly scope?: 'message' | 'line';
1853
+ }
1854
+ /** One rule hit: which rule, which line, and the extracted group values. */
1855
+ interface HilogMatch {
1856
+ readonly ruleName: string;
1857
+ readonly lineIndex: number;
1858
+ readonly groups: readonly string[];
1859
+ }
1860
+ /** A compiled rule: the regex, the condition, and the extraction plan. */
1861
+ interface CompiledRule {
1862
+ readonly name: string;
1863
+ match(line: HilogLine): readonly string[] | undefined;
1864
+ }
1865
+ /**
1866
+ * HapRay's `hilog.patterns`, verbatim from `config.yaml` at `9386e4e`.
1867
+ *
1868
+ * The three `CreatePixelMap` rules share one regex and differ only in their
1869
+ * condition, so a single line can match more than one — upstream counts it
1870
+ * in each, and so does this port.
1871
+ */
1872
+ declare const DEFAULT_HILOG_RULES: readonly HilogRule[];
1873
+ /**
1874
+ * Compile a rule set, sorted by name.
1875
+ *
1876
+ * Sorting is what makes evaluation order independent of the caller's array:
1877
+ * two rule files with the same rules in different orders produce the same
1878
+ * match list.
1879
+ */
1880
+ declare function compileRules(rules: readonly HilogRule[]): CompiledRule[];
1881
+ /**
1882
+ * Every match over every line, ordered by `(lineIndex, ruleName)`.
1883
+ *
1884
+ * One rule's failure never stops another: a non-numeric group is a rule
1885
+ * authoring error, so it is thrown rather than swallowed, and the caller
1886
+ * decides whether to report the rule as broken.
1887
+ */
1888
+ declare function matchRules(rules: readonly CompiledRule[], lines: readonly HilogLine[]): HilogMatch[];
1889
+
1890
+ /**
1891
+ * A decoded image: row-major RGBA, 4 bytes per pixel.
1892
+ *
1893
+ * Alpha is always present after decoding, whatever the source colour type was:
1894
+ * a grey or RGB PNG is expanded to opaque RGBA so every consumer (hashing, the
1895
+ * pixel diff, region marking) handles exactly one layout.
1896
+ */
1897
+ interface RgbaImage {
1898
+ readonly width: number;
1899
+ readonly height: number;
1900
+ /** Row-major RGBA, 4 bytes per pixel, length = width*height*4. */
1901
+ readonly data: Uint8Array;
1902
+ }
1903
+ /**
1904
+ * Decode an 8-bit, non-interlaced PNG into RGBA.
1905
+ *
1906
+ * Deliberately narrow: the device writes 8-bit RGB/RGBA and nothing else, so
1907
+ * palette, 16-bit and interlaced images are refused by name rather than
1908
+ * half-decoded into a plausible-looking wrong image. The five row filters are
1909
+ * all implemented, because those do appear in real encoders.
1910
+ *
1911
+ * A length mismatch after inflation is the truncated-transfer check: the
1912
+ * expected size is exactly `height * (1 + bytesPerPixel * width)`, and any
1913
+ * other length means the IDAT stream ended early (or was padded). Neither is
1914
+ * a picture, so both fail rather than being resized.
1915
+ */
1916
+ declare function decodePng(bytes: Uint8Array): RgbaImage;
1917
+ /**
1918
+ * Encode RGBA as an 8-bit RGBA PNG.
1919
+ *
1920
+ * No ancillary chunks are written — no `tIME`, no `tEXt` — so the bytes depend
1921
+ * only on the pixels. That is what lets a marked image be compared byte for
1922
+ * byte across runs (D5).
1923
+ */
1924
+ declare function encodePng(image: RgbaImage): Uint8Array;
1925
+
1926
+ /** An axis-aligned rectangle in screenshot pixels. */
1927
+ interface Rect {
1928
+ readonly left: number;
1929
+ readonly top: number;
1930
+ readonly right: number;
1931
+ readonly bottom: number;
1932
+ }
1933
+ /**
1934
+ * The result of comparing two screenshots.
1935
+ *
1936
+ * `hamming`/`similarity` answer "is the structure the same" (a 64-bit gradient
1937
+ * hash is insensitive to small colour shifts); `changedRatio` answers "how much
1938
+ * of the picture differs". They can disagree — a solid colour change moves one
1939
+ * and not the other — so both are reported and neither is presented as *the*
1940
+ * answer.
1941
+ */
1942
+ interface ImageComparison {
1943
+ readonly dhashA: string;
1944
+ readonly dhashB: string;
1945
+ /** 0..64, the bit distance between the two dHashes. */
1946
+ readonly hamming: number;
1947
+ /** `1 - hamming/64`. */
1948
+ readonly similarity: number;
1949
+ /** Fraction of compared pixels whose channels differ by more than `tolerance`. */
1950
+ readonly changedRatio: number;
1951
+ /** The per-channel threshold actually applied (0..255). */
1952
+ readonly tolerance: number;
1953
+ /** The downscaled size the pixel comparison ran at. */
1954
+ readonly comparedWidth: number;
1955
+ readonly comparedHeight: number;
1956
+ }
1957
+ /**
1958
+ * A 64-bit difference hash, as 16 hex characters.
1959
+ *
1960
+ * The image is box-averaged down to 9×8 greyscale and each row's 8 horizontal
1961
+ * gradients become 8 bits (`right > left`). Two identical pictures hash the
1962
+ * same; a uniform picture hashes to all zeros whatever its colour, because
1963
+ * every gradient is zero — a property worth knowing before reading a distance
1964
+ * of 0 as "visually identical".
1965
+ */
1966
+ declare function dhash(image: RgbaImage): string;
1967
+ /**
1968
+ * Compare two screenshots.
1969
+ *
1970
+ * Refuses different dimensions: `bounds` from the UI tree and the pixels here
1971
+ * are in the same coordinate space, so a cross-resolution comparison would
1972
+ * silently compare different regions. Normalising sizes is a different feature
1973
+ * with its own honesty problem (layout differences would read as pixel
1974
+ * differences), and it is deliberately absent.
1975
+ */
1976
+ declare function compareImages(a: RgbaImage, b: RgbaImage, opts?: {
1977
+ tolerance?: number;
1978
+ }): ImageComparison;
1979
+ /**
1980
+ * Draw a 1 px red rectangle on each region's edges, returning a new image.
1981
+ *
1982
+ * The rectangle marks the *edges*, not the fill: a filled block would hide the
1983
+ * very pixels the caller is being shown. Regions are clipped to the image, so
1984
+ * a node whose bounds run past the screen still marks its visible part.
1985
+ */
1986
+ declare function markRegions(image: RgbaImage, regions: readonly Rect[]): RgbaImage;
1987
+
1988
+ /** One node-level difference between two captures. */
1989
+ interface UiTreeDifference {
1990
+ readonly change: 'added' | 'removed' | 'changed';
1991
+ /** Document path, e.g. `0.2.1` — the position in the *later* tree for added
1992
+ * and changed nodes, in the earlier tree for removed ones. */
1993
+ readonly path: string;
1994
+ /** The identity the match used, so a caller can find the node again. */
1995
+ readonly identity: string;
1996
+ readonly type: string;
1997
+ readonly bounds?: {
1998
+ readonly left: number;
1999
+ readonly top: number;
2000
+ readonly right: number;
2001
+ readonly bottom: number;
1115
2002
  };
1116
- pids: number[];
1117
- deviceId: string;
1118
- startedAtNs?: number;
1119
- capture?: {
1120
- startedAtMs: number;
1121
- durationMs: number;
1122
- collectors: string[];
1123
- /**
1124
- * Present only when a hiperf capture ran. `samples` may be 0: an idle app
1125
- * yields no samples, which is a real capture, not a missing one.
1126
- */
1127
- hiperf?: {
1128
- samples: number;
1129
- };
1130
- /**
1131
- * Present only when a hidumper capture ran. `frames` may be 0: a screen
1132
- * that presented nothing is a measurement, not a missing capture.
1133
- */
1134
- hidumper?: {
1135
- frames: number;
1136
- };
1137
- /**
1138
- * Present only when a uitest capture ran. `nodes` may be 0: a blank screen
1139
- * is a measurement, not a missing capture.
1140
- */
1141
- uitest?: {
1142
- nodes: number;
1143
- };
2003
+ /** Attribute-level differences; absent for added and removed nodes. */
2004
+ readonly attributes?: Array<{
2005
+ name: string;
2006
+ before: string;
2007
+ after: string;
2008
+ }>;
2009
+ }
2010
+ interface UiTreeDiff {
2011
+ readonly added: UiTreeDifference[];
2012
+ readonly removed: UiTreeDifference[];
2013
+ readonly changed: UiTreeDifference[];
2014
+ /** Matched nodes with no reported difference. */
2015
+ readonly unchanged: number;
2016
+ }
2017
+ /**
2018
+ * Attributes excluded from the comparison.
2019
+ *
2020
+ * HapRay's list, kept for the same reason it exists: these are renderer
2021
+ * internals that change between two captures of an identical screen, so
2022
+ * reporting them would drown a real difference in noise.
2023
+ */
2024
+ declare const IGNORED_ATTRIBUTES: readonly string[];
2025
+ /**
2026
+ * Geometry differences smaller than this are not differences.
2027
+ *
2028
+ * A node that moved by 3 px between two captures of the same screen is layout
2029
+ * jitter, not a UI change; 5 px is HapRay's measured threshold and the one the
2030
+ * diff reports in its own output.
2031
+ */
2032
+ declare const GEOMETRY_TOLERANCE_PX = 5;
2033
+ /**
2034
+ * A node's identity for matching.
2035
+ *
2036
+ * `bundleName | type | id | text`, with an empty `id` or `text` omitted. Text
2037
+ * is part of the identity deliberately: a label *is* what that node is, so a
2038
+ * text change reads as one removed node plus one added one rather than a
2039
+ * "changed" node whose meaning is unclear. Matching by identity instead of by
2040
+ * index is what stops one inserted sibling from shifting every later
2041
+ * comparison.
2042
+ */
2043
+ declare function nodeIdentity(node: UiNode): string;
2044
+ /**
2045
+ * Compare two flattened trees by node identity.
2046
+ *
2047
+ * Children are bucketed by identity and paired in document order within each
2048
+ * bucket, so an insertion consumes one slot instead of shifting the rest. A
2049
+ * node present only on the later side is `added`, only on the earlier side
2050
+ * `removed`, and a matched pair with attribute differences is `changed`.
2051
+ * Output arrays are sorted by path, so the result is byte-stable (D5).
2052
+ */
2053
+ declare function diffTrees(before: readonly UiNode[], after: readonly UiNode[]): UiTreeDiff;
2054
+
2055
+ /** What one side of the comparison contained, as the page and JSON report it. */
2056
+ interface UiDiffSide {
2057
+ readonly dir: string;
2058
+ /** `scene.json`'s capture start, copied as an input; absent without metadata. */
2059
+ readonly startedAtMs?: number;
2060
+ readonly screenshot: {
2061
+ readonly width: number;
2062
+ readonly height: number;
2063
+ } | null;
2064
+ readonly tree: {
2065
+ readonly nodes: number;
2066
+ } | null;
2067
+ }
2068
+ /**
2069
+ * The result of comparing two captured scenes.
2070
+ *
2071
+ * `image` and `tree` are `null` only when neither side has that artifact — a
2072
+ * comparison of two tree-only captures has no image, and saying so in
2073
+ * `degraded` is more useful than failing. A missing artifact on *one* side is
2074
+ * an error, because a missing screen is not an unchanged screen.
2075
+ */
2076
+ interface UiDiff {
2077
+ readonly schemaVersion: 1;
2078
+ readonly a: UiDiffSide;
2079
+ readonly b: UiDiffSide;
2080
+ readonly image: ImageComparison | null;
2081
+ readonly tree: UiTreeDiff | null;
2082
+ readonly regions: Rect[];
2083
+ readonly degraded: string[];
2084
+ }
2085
+ /** Where `compareSceneDirs` writes its artifacts. */
2086
+ interface UiCompareOptions {
2087
+ /** Output directory for the four files. */
2088
+ readonly outDir: string;
2089
+ /** Per-channel pixel tolerance, 0..255; defaults to the image diff's 8. */
2090
+ readonly tolerance?: number;
2091
+ }
2092
+ /**
2093
+ * Compare two scene directories by UI tree and screenshot.
2094
+ *
2095
+ * Both sides are read before anything is written, so a failure leaves no
2096
+ * half-written bundle. `ui-diff.json` carries no clock of its own — the two
2097
+ * `capture.startedAtMs` values are copied from each side's `scene.json` — so
2098
+ * two runs over the same inputs are byte-identical (D5), as are the marked
2099
+ * PNGs, whose encoder writes no ancillary chunks.
2100
+ */
2101
+ declare function compareSceneDirs(a: string, b: string, opts: UiCompareOptions): Promise<UiDiff>;
2102
+ /** The artifact file names, for a caller reporting what was written. */
2103
+ declare const UI_DIFF_FILES: readonly string[];
2104
+
2105
+ /**
2106
+ * Render the UI comparison page.
2107
+ *
2108
+ * Self-contained except for the two marked PNGs beside it: no scripts, no
2109
+ * network access, inline CSS. The tolerance and the geometry threshold are
2110
+ * stated in the page, so a reader can tell how much difference the numbers
2111
+ * already forgive without opening the docs.
2112
+ */
2113
+ declare function renderUiDiffHtml(diff: UiDiff): string;
2114
+
2115
+ /**
2116
+ * Declarative scenario documents.
2117
+ *
2118
+ * A scenario is data, not code: ordered steps, each with a setup phase that
2119
+ * runs before the capture, an action phase that runs inside it, and a cleanup
2120
+ * phase that runs after. This module is the whole trust boundary — every
2121
+ * field is checked here, before a device is touched, and an unknown key is an
2122
+ * error rather than a silently ignored typo.
2123
+ *
2124
+ * The validator is hand-written on purpose. A schema library would be the
2125
+ * first runtime dependency in `@ohos-perf/core`, and the property that makes
2126
+ * this file worth reading — every rejection names the JSON path that caused
2127
+ * it — is the one a generic validator reports least clearly.
2128
+ */
2129
+
2130
+ /** One thing a step does. `wait` and `marker` touch no device. */
2131
+ type ScenarioAction = {
2132
+ readonly kind: 'launch';
2133
+ readonly ability: string;
2134
+ } | {
2135
+ readonly kind: 'forceStop';
2136
+ } | {
2137
+ readonly kind: 'click';
2138
+ readonly x: number;
2139
+ readonly y: number;
2140
+ } | {
2141
+ readonly kind: 'swipe';
2142
+ readonly fromX: number;
2143
+ readonly fromY: number;
2144
+ readonly toX: number;
2145
+ readonly toY: number;
2146
+ readonly velocity?: number;
2147
+ } | {
2148
+ readonly kind: 'key';
2149
+ readonly key: string | number;
2150
+ } | {
2151
+ readonly kind: 'text';
2152
+ readonly text: string;
2153
+ } | {
2154
+ readonly kind: 'inputText';
2155
+ readonly x: number;
2156
+ readonly y: number;
2157
+ readonly text: string;
2158
+ } | {
2159
+ readonly kind: 'wait';
2160
+ readonly ms: number;
2161
+ } | {
2162
+ readonly kind: 'marker';
2163
+ readonly name: string;
2164
+ };
2165
+ /** The collectors a step may ask for, by the name `Device.collect` understands. */
2166
+ declare const COLLECTOR_NAMES: readonly ["hitrace", "hiprofiler", "procfs", "hiperf", "hidumper", "uitest", "hilog"];
2167
+ type CollectorName = (typeof COLLECTOR_NAMES)[number];
2168
+ interface StepCapture {
2169
+ readonly durationMs: number;
2170
+ readonly collectors: readonly CollectorName[];
2171
+ readonly hiprofiler?: {
2172
+ readonly plugins: readonly HiprofilerPluginName[];
2173
+ };
2174
+ readonly hiperf?: {
2175
+ readonly frequency?: number;
1144
2176
  };
1145
2177
  }
2178
+ interface ScenarioStep {
2179
+ readonly id: string;
2180
+ readonly name: string;
2181
+ readonly setup: readonly ScenarioAction[];
2182
+ readonly actions: readonly ScenarioAction[];
2183
+ readonly cleanup: readonly ScenarioAction[];
2184
+ readonly capture: StepCapture;
2185
+ }
2186
+ interface Scenario {
2187
+ readonly version: 1;
2188
+ readonly name: string;
2189
+ readonly description?: string;
2190
+ readonly app: string;
2191
+ readonly rounds: number;
2192
+ readonly steps: readonly ScenarioStep[];
2193
+ }
1146
2194
  /**
1147
- * Writes `scene.json` next to the other scene artifacts.
2195
+ * Parse and validate a scenario document.
1148
2196
  *
1149
- * The scene root is created when needed. The file is pretty-printed with two
1150
- * spaces and ends with one newline so it is diff-friendly and byte-stable.
2197
+ * Throws `OhosPerfError` with code `SCENARIO_BAD_INPUT` for a document-level
2198
+ * problem (invalid JSON, wrong version, unknown key, missing field) and
2199
+ * `SCENARIO_BAD_STEP` for one inside a step. Both name the JSON path.
1151
2200
  */
1152
- declare function writeSceneMetadata(layout: SceneLayout, meta: SceneMetadata): void;
2201
+ declare function parseScenario(text: string): Scenario;
2202
+
1153
2203
  /**
1154
- * Reads a scene's `scene.json`, or `undefined` when it cannot be trusted.
2204
+ * Executing one scenario action against a device.
1155
2205
  *
1156
- * A missing file, invalid JSON, a non-object document, a `version` other than
1157
- * `1`, or a document missing the required fields all yield `undefined`: a
1158
- * partially valid description would be worse than none. `startedAtNs` is
1159
- * optional, but a non-positive (including zero) or non-finite value is dropped
1160
- * from the result (the file itself is never rewritten) so consumers can treat
1161
- * "no marker" as one case. Uptime 0 addresses the trace origin, not the capture
1162
- * start, so accepting it would only produce a nonsense startup duration.
2206
+ * The split with the runner is deliberate: this module performs exactly one
2207
+ * action and throws when it fails, while the runner owns the record — when it
2208
+ * happened, whether the step survived it, and what the trace says. That keeps
2209
+ * "did it work" in one place and "what do we remember about it" in another.
2210
+ *
2211
+ * Quoting lives in `GestureDriver`, not here: it already knows that the device
2212
+ * shell needs `'…'` and that a quote inside a text argument must be escaped.
2213
+ * Quoting again here would send the quote characters to the device.
1163
2214
  */
1164
- declare function readSceneMetadata(layout: SceneLayout): SceneMetadata | undefined;
2215
+
2216
+ /** The device surface actions need. `Device` satisfies it structurally. */
2217
+ interface ActionDevice {
2218
+ readonly id: string;
2219
+ shell(cmd: string): Promise<{
2220
+ stdout: string;
2221
+ stderr: string;
2222
+ code: number;
2223
+ }>;
2224
+ gesture(g: Gesture): Promise<GestureResult>;
2225
+ }
2226
+ /**
2227
+ * Perform one action and return what the device said.
2228
+ *
2229
+ * `launch` and `forceStop` use the scenario's app; a `wait` sleeps without a
2230
+ * device call. A `marker` is refused here — the runner records markers with a
2231
+ * device-uptime instant, and having two layers able to "execute" one would
2232
+ * let them disagree about whether it happened.
2233
+ */
2234
+ declare function executeAction(device: ActionDevice, app: string, action: ScenarioAction): Promise<{
2235
+ output?: string;
2236
+ }>;
2237
+
2238
+ /**
2239
+ * The scenario runner: ordered steps, one capture window each.
2240
+ *
2241
+ * The shape that matters is the phase order. `setup` runs before the capture
2242
+ * so the state you want to measure is already on screen; `actions` run
2243
+ * *inside* the window so the gesture that causes the work is in the trace;
2244
+ * `cleanup` runs after, always. HapRay's DSL parses setup and cleanup and
2245
+ * never executes them — executing all three is why this exists.
2246
+ *
2247
+ * Nothing here analyzes. A step directory is a scene, so `ohos-perf analyze`,
2248
+ * `report` and `query` apply to it unchanged.
2249
+ */
2250
+
2251
+ /** One action's outcome, as `steps.json` records it. */
2252
+ interface ActionOutcome {
2253
+ readonly action: ScenarioAction;
2254
+ /** Device uptime in ns, read immediately before the action; absent when the read failed. */
2255
+ readonly atNs?: number;
2256
+ /** Host clock at the action, ms. */
2257
+ readonly atMs: number;
2258
+ readonly ok: boolean;
2259
+ readonly output?: string;
2260
+ readonly error?: string;
2261
+ }
2262
+ interface RunStepResult {
2263
+ readonly round: number;
2264
+ readonly index: number;
2265
+ readonly id: string;
2266
+ readonly name: string;
2267
+ readonly status: 'ok' | 'failed';
2268
+ /** Present only when a scene exists on disk. */
2269
+ readonly sceneDir?: string;
2270
+ readonly startedAtMs: number;
2271
+ readonly durationMs: number;
2272
+ readonly actions: readonly ActionOutcome[];
2273
+ readonly error?: string;
2274
+ }
2275
+ interface RunResult {
2276
+ readonly scenario: string;
2277
+ readonly app: string;
2278
+ readonly device: {
2279
+ id: string;
2280
+ kind: string;
2281
+ };
2282
+ readonly rounds: number;
2283
+ readonly status: 'completed' | 'failed';
2284
+ readonly steps: readonly RunStepResult[];
2285
+ readonly startedAtMs: number;
2286
+ readonly durationMs: number;
2287
+ readonly pids: {
2288
+ pids: readonly number[];
2289
+ processNames: readonly string[];
2290
+ };
2291
+ /** Absent when the device would not report one. Never a fabricated `0.0.0`. */
2292
+ readonly appVersion?: string;
2293
+ }
2294
+ /** The collect request one step turns into. Mirrors `Device.collect`. */
2295
+ interface RunnerCollectOptions {
2296
+ app: string;
2297
+ durationMs: number;
2298
+ sceneRoot: string;
2299
+ step: SceneStepRef;
2300
+ procfs?: boolean;
2301
+ hiprofiler?: {
2302
+ plugins: readonly HiprofilerPluginName[];
2303
+ };
2304
+ hiperf?: {
2305
+ frequency?: number;
2306
+ };
2307
+ hidumper?: boolean;
2308
+ uitest?: boolean;
2309
+ hilog?: boolean;
2310
+ }
2311
+ /** The device surface the runner needs. `Device` satisfies it structurally. */
2312
+ interface RunnerDevice {
2313
+ readonly id: string;
2314
+ readonly kind: string;
2315
+ shell(cmd: string): Promise<{
2316
+ stdout: string;
2317
+ stderr: string;
2318
+ code: number;
2319
+ }>;
2320
+ gesture(g: Gesture): Promise<GestureResult>;
2321
+ collect(opts: RunnerCollectOptions): Promise<{
2322
+ ingest(): Promise<{
2323
+ close(): void;
2324
+ }>;
2325
+ }>;
2326
+ }
2327
+ interface RunOptions {
2328
+ readonly outDir: string;
2329
+ /** Overrides the scenario's own `rounds` when set. */
2330
+ readonly rounds?: number;
2331
+ /** Step ids to run; order in the scenario wins. */
2332
+ readonly only?: readonly string[];
2333
+ /** Continue after a failed step instead of stopping. */
2334
+ readonly keepGoing?: boolean;
2335
+ /** Injected clock, for tests. */
2336
+ readonly now?: () => number;
2337
+ }
2338
+ /**
2339
+ * Run a scenario: every selected (round, step) pair, one scene each.
2340
+ *
2341
+ * The returned result is what `steps.json` records; the files are written
2342
+ * before returning, on the success and the failure path alike, so a run that
2343
+ * stopped at step 2 still says what step 1 produced.
2344
+ */
2345
+ declare class ScenarioRunner {
2346
+ private readonly device;
2347
+ private readonly opts;
2348
+ private readonly now;
2349
+ constructor(device: RunnerDevice, opts: RunOptions);
2350
+ run(scenario: Scenario): Promise<RunResult>;
2351
+ /**
2352
+ * The steps to run, in scenario order.
2353
+ *
2354
+ * `--only` is a filter, not an ordering: typing `scroll,open` still runs
2355
+ * `open` first, because a step may depend on the state a previous one left.
2356
+ */
2357
+ private selectedSteps;
2358
+ private runStep;
2359
+ /**
2360
+ * Perform one action and record it; never throws.
2361
+ *
2362
+ * A `marker` is recorded here, not executed: it is an annotation with a
2363
+ * device-uptime instant — the thing that lets a later query line a tap up
2364
+ * with a trace row — and there is no trace event behind it. Recording it in
2365
+ * the runner is what keeps "it happened" in the same place as "when".
2366
+ */
2367
+ private perform;
2368
+ }
2369
+ /**
2370
+ * Write `testInfo.json`, `steps.json` and `pids.json` into a run directory.
2371
+ *
2372
+ * Pretty-printed with two spaces and one trailing newline, like `scene.json`,
2373
+ * so a run is diff-friendly and byte-stable apart from its clock fields.
2374
+ */
2375
+ declare function writeRunFiles(outDir: string, result: RunResult): void;
1165
2376
 
1166
2377
  /**
1167
2378
  * Frame status as stored in `frame_slice.flag`.
@@ -1749,6 +2960,46 @@ interface PerfCallchain {
1749
2960
  callchainId: number;
1750
2961
  functions: PerfFunction[];
1751
2962
  }
2963
+ /**
2964
+ * Sample weight attributed to one leaf symbol.
2965
+ *
2966
+ * `event_count` is attributed to the deepest frame of the sample's callchain
2967
+ * (the "self" cost), so rows answer "which function was executing when the
2968
+ * sample was taken". A chain whose deepest frame has an empty symbol is not
2969
+ * attributable and contributes no row.
2970
+ */
2971
+ interface PerfLeafAttribution {
2972
+ symbol: string;
2973
+ filePath: string;
2974
+ samples: number;
2975
+ /** True when `symbol` is a `file+0xoffset` reference, not a name. */
2976
+ unresolved: boolean;
2977
+ }
2978
+ /**
2979
+ * One row of summed sample weight per `(symbol, filePath, unresolved)`.
2980
+ *
2981
+ * This is the population {@link PerfQuery.leafAttribution} returns, plus the
2982
+ * frames no symbol resolves at all, so the rows sum to the window's weight.
2983
+ * `unresolved` separates "the recorder had no symbol" from "the lookup
2984
+ * missed": a `libfoo.so+0x1cce24` symbol is honest, and counting it as
2985
+ * resolved would make the numbers read better than the capture is.
2986
+ */
2987
+ interface SymbolStat {
2988
+ symbol: string;
2989
+ filePath: string;
2990
+ samples: number;
2991
+ unresolved: boolean;
2992
+ }
2993
+ /**
2994
+ * True when a resolved symbol is a `file+0xoffset` reference or empty.
2995
+ *
2996
+ * The converter writes `libfoo.so+0x1cce24` when it has no symbol for an
2997
+ * address, so the text is honest but unnamed. A space means the text is a
2998
+ * sentence or a demangled signature, never that form. The file path is never
2999
+ * part of the test: an unresolved frame still names the library it ran in,
3000
+ * which is what makes the evidence actionable.
3001
+ */
3002
+ declare function isUnresolvedSymbol(symbol: string): boolean;
1752
3003
  /**
1753
3004
  * One folded stack, in the format `flamegraph.pl` and every flamegraph viewer
1754
3005
  * understands: `a;b;c` with `samples` samples ending at `c`.
@@ -1774,6 +3025,14 @@ declare class PerfQuery {
1774
3025
  constructor(db: QueryHandle);
1775
3026
  /** True when `perf_sample` exists and contains at least one row. */
1776
3027
  hasSamples(): boolean;
3028
+ /**
3029
+ * True when `perf_files` exists, so a frame can carry a symbol at all.
3030
+ *
3031
+ * A capture without it has no symbol table to resolve against: every frame
3032
+ * is unnamed for that reason, not because its callchain was truncated. The
3033
+ * distinction matters to the wording a reader gets.
3034
+ */
3035
+ hasSymbolTable(): boolean;
1777
3036
  /**
1778
3037
  * `perf_thread` rows whose `process_id` is one of `pids`, ordered by `id`.
1779
3038
  *
@@ -1815,10 +3074,11 @@ declare class PerfQuery {
1815
3074
  * Mirrors HapRay's `_query_callchains_batch`: per thread at most the first
1816
3075
  * 50 distinct `callchain_id`s (in chain-id order) are considered and at most
1817
3076
  * `maxChainsPerThread` (default 20) non-empty chains are returned. Frames
1818
- * are ordered by `depth`; symbols resolve through `perf_files` by the exact
1819
- * `(file_id, serial_id)` pair first and by `file_id` alone as the fallback.
1820
- * A frame keeps its raw `perf_callchain.name` and an empty path when neither
1821
- * lookup matches.
3077
+ * are ordered by `depth`; a symbol resolves through the exact
3078
+ * `(file_id, symbol_id → serial_id)` row of `perf_files`, then through the
3079
+ * `data_dict` text for `perf_callchain.name`, and never from a neighbouring
3080
+ * row of the same file. The file path still resolves from `file_id` alone,
3081
+ * so an unresolved frame names the library it ran in.
1822
3082
  *
1823
3083
  * If `perf_callchain` or `perf_files` is absent there is nothing to return,
1824
3084
  * so the result is `[]` (HapRay does the same).
@@ -1839,16 +3099,189 @@ declare class PerfQuery {
1839
3099
  * with no frames contributes nothing. An empty `threadIds`, a missing
1840
3100
  * `perf_callchain`/`perf_files`, or no samples in range yields `[]`.
1841
3101
  */
1842
- foldedStacks(threadIds: readonly number[], range: TimeRange, top?: number): FoldedStack[];
3102
+ foldedStacks(threadIds: readonly number[], range: TimeRange, top?: number): FoldedStack[];
3103
+ /**
3104
+ * Attributes each sample's weight to the deepest frame of its callchain.
3105
+ *
3106
+ * This is the "self cost" table a hotspot list needs, as opposed to
3107
+ * {@link foldedStacks}, which preserves the whole stack. Rows are sorted by
3108
+ * `samples` descending, then symbol, then filePath, so equal weights never
3109
+ * fall back to row order (D5). A chain with no frames or with an empty leaf
3110
+ * symbol contributes nothing; an empty `threadIds` or a missing
3111
+ * `perf_sample`/`perf_callchain`/`perf_files` returns `[]`.
3112
+ */
3113
+ leafAttribution(threadIds: readonly number[], range: TimeRange): PerfLeafAttribution[];
3114
+ /**
3115
+ * Summed weight per `(symbol, filePath, unresolved)` over the window.
3116
+ *
3117
+ * This is the typed form of HapRay's `symbol_statistics` table, and the same
3118
+ * population {@link leafAttribution} reports — plus the frames no symbol
3119
+ * resolves at all, which `leafAttribution` drops. Keeping them here is what
3120
+ * makes the rows sum to {@link eventCount} exactly, so a caller can check
3121
+ * that no weight went missing.
3122
+ *
3123
+ * A chain with no frames still holds weight: a truncated conversion or a
3124
+ * dropped kernel chain leaves `perf_sample` rows whose `callchain_id` names
3125
+ * nothing. So does a sample the recorder could not unwind at all, whose
3126
+ * `callchain_id` is NULL — `eventCount` counts that weight too. Both land in
3127
+ * the unresolved `('', '')` row rather than vanishing from the identity.
3128
+ */
3129
+ symbolStats(threadIds: readonly number[], range: TimeRange): SymbolStat[];
3130
+ /**
3131
+ * The unresolved subset of {@link symbolStats}: frames the recorder could
3132
+ * not name.
3133
+ *
3134
+ * A subset, not an addition — the weights are already inside
3135
+ * `symbolStats`, so a caller must not add the two populations together.
3136
+ */
3137
+ unresolvedSymbols(threadIds: readonly number[], range: TimeRange): SymbolStat[];
3138
+ /**
3139
+ * Summed `event_count` per `callchain_id` for the threads and range.
3140
+ *
3141
+ * Shared by {@link foldedStacks} and {@link leafAttribution} so both weight
3142
+ * samples identically. `callchain_id IS NULL` rows are omitted; the map is
3143
+ * ordered by the caller.
3144
+ */
3145
+ private chainWeights;
3146
+ /**
3147
+ * Weight of the samples in the window that recorded no call chain at all.
3148
+ *
3149
+ * `callchain_id` is NULL when the recorder could not unwind — the sample is
3150
+ * still real, and {@link eventCount} counts it. {@link chainWeights} cannot
3151
+ * carry it (there is no chain id to key on), so {@link symbolStats} adds it
3152
+ * to the unresolved `('', '')` row explicitly; without that the documented
3153
+ * identity would be false by exactly this weight.
3154
+ */
3155
+ private nullChainWeight;
3156
+ /**
3157
+ * Resolves each chain id to its frames, ordered by `depth`.
3158
+ *
3159
+ * A symbol comes from the exact `(file_id, symbol_id → serial_id)` row of
3160
+ * `perf_files`; when that row is missing or names nothing, from the
3161
+ * `data_dict` text for `perf_callchain.name`; and when the column holds text
3162
+ * rather than an id (a hand-built database), from that text. A frame whose
3163
+ * `name` is a dangling id gets `''` — the recorder had no symbol, and
3164
+ * repeating the number would claim a name. A missing `perf_callchain` or
3165
+ * `perf_files` yields an empty map (nothing can be resolved).
3166
+ */
3167
+ private chainFunctions;
3168
+ /**
3169
+ * The `data_dict` text for the `name` ids these frames carry.
3170
+ *
3171
+ * Optional table: a hand-built database may omit it, and then every frame
3172
+ * keeps its raw `name` column. Loaded once per call, ordered by id so the
3173
+ * query itself is deterministic.
3174
+ */
3175
+ private loadDataDict;
3176
+ private hasTable;
3177
+ }
3178
+
3179
+ /**
3180
+ * One `native_hook` row with camelCase field names.
3181
+ *
3182
+ * `event_type` is alloc for `'AllocEvent'`/`'MmapEvent'`/`0`, free for
3183
+ * `'FreeEvent'`/`'MunmapEvent'`/`1`, and anything else is neither. `null` means
3184
+ * the column itself was NULL, which is not an allocation: the direction is
3185
+ * unknown, so it stays `null` and the pairing layer counts it as `other`.
3186
+ * `heapSize` is a magnitude: the stored sign carries no meaning, the pairing
3187
+ * layer applies the direction. `allHeapSize` and `currentSizeDur` are read for
3188
+ * callers but are never interpreted — their semantics are undocumented upstream.
3189
+ */
3190
+ interface NativeHookEvent {
3191
+ id: number;
3192
+ callchainId: number;
3193
+ ipid: number;
3194
+ /** `process.pid` resolved through `ipid`; the number space an app is known by. */
3195
+ pid: number;
3196
+ itid: number;
3197
+ eventType: number | string | null;
3198
+ subTypeId: number;
3199
+ startTs: number;
3200
+ endTs: number;
3201
+ dur: number;
3202
+ /** Heap address; `0` means the column was NULL, so the block cannot be freed. */
3203
+ addr: number;
3204
+ heapSize: number;
3205
+ allHeapSize: number;
3206
+ currentSizeDur: number;
3207
+ lastLibId: number;
3208
+ lastSymbolId: number;
3209
+ }
3210
+ /** One frame of a native callchain, ordered by `depth`. */
3211
+ interface NativeHookFrame {
3212
+ id: number;
3213
+ callchainId: number;
3214
+ depth: number;
3215
+ ip: number;
3216
+ symbolId: number;
3217
+ fileId: number;
3218
+ offset: number;
3219
+ symbolOffset: number;
3220
+ vaddr: number;
3221
+ }
3222
+ /**
3223
+ * One `native_hook_statistic` row: a pre-aggregated alloc/free pair per
3224
+ * callchain, with no per-allocation timestamp, thread or address.
3225
+ */
3226
+ interface NativeHookStatistic {
3227
+ id: number;
3228
+ callchainId: number;
3229
+ ipid: number;
3230
+ ts: number;
3231
+ type: number | string;
3232
+ subTypeId: number;
3233
+ applyCount: number;
3234
+ releaseCount: number;
3235
+ applySize: number;
3236
+ releaseSize: number;
3237
+ lastLibId: number;
3238
+ lastSymbolId: number;
3239
+ }
3240
+ /**
3241
+ * Typed, batched access to the `native_hook*` tables.
3242
+ *
3243
+ * The tables exist only when a capture ran `hiprofiler` with the `nativehook`
3244
+ * plugin, so every accessor checks `sqlite_master` first and returns
3245
+ * `[]`/`false`/an empty map instead of letting SQLite throw `no such table`.
3246
+ * That is what lets the analyzer report a degraded proxy with a reason rather
3247
+ * than crash on a plain hitrace capture.
3248
+ *
3249
+ * `events` joins `process` on `ipid` and filters on `process.pid`, which is the
3250
+ * same number space the rest of the package resolves an app to.
3251
+ */
3252
+ declare class NativeHookQuery {
3253
+ private readonly db;
3254
+ constructor(db: QueryHandle);
3255
+ /** True when `native_hook` exists and holds at least one row. */
3256
+ hasData(): boolean;
3257
+ /** True when `native_hook_statistic` exists and holds at least one row. */
3258
+ hasStatistics(): boolean;
3259
+ /**
3260
+ * App events ordered by `(start_ts, id)`, optionally inside an inclusive
3261
+ * `range` on `start_ts`.
3262
+ *
3263
+ * The `(start_ts, id)` tie-break is ours; upstream orders by timestamp alone,
3264
+ * which makes a capture with equal timestamps depend on row order.
3265
+ *
3266
+ * `DISTINCT` on the event columns collapses the duplicate rows a repeated
3267
+ * `process.ipid` would produce: a merged trace can carry two `process` rows
3268
+ * with the same ipid, and a plain join then returns each event once per row,
3269
+ * doubling every byte. `p.pid` is selected from the same ipid group, so the
3270
+ * duplicate rows are identical.
3271
+ */
3272
+ events(pids: readonly number[], range?: TimeRange): NativeHookEvent[];
3273
+ /** Frames of `callchainIds`, ordered by `(callchain_id, depth, id)`. */
3274
+ frames(callchainIds: readonly number[]): Map<number, NativeHookFrame[]>;
1843
3275
  /**
1844
- * Resolves each chain id to its frames, ordered by `depth`.
3276
+ * Statistics rows for the app, ordered by `(ts, id)`.
1845
3277
  *
1846
- * Symbols resolve through `perf_files` by the exact `(file_id, serial_id)`
1847
- * pair first and by `file_id` alone as the fallback; a frame with neither
1848
- * keeps its raw `perf_callchain.name`. A missing `perf_callchain` or
1849
- * `perf_files` yields an empty map (nothing can be resolved).
3278
+ * `DISTINCT` and the `process` guard mirror {@link events} for the same two
3279
+ * reasons: a repeated ipid must not multiply rows, and a missing join table
3280
+ * must degrade rather than throw.
1850
3281
  */
1851
- private chainFunctions;
3282
+ statistics(pids: readonly number[]): NativeHookStatistic[];
3283
+ /** `data_dict` text for `ids`; ids absent from the table are simply missing. */
3284
+ dataDict(ids: readonly number[]): Map<number, string>;
1852
3285
  private hasTable;
1853
3286
  }
1854
3287
 
@@ -1928,7 +3361,7 @@ declare class StartupQuery {
1928
3361
  private hasTable;
1929
3362
  }
1930
3363
 
1931
- type EvidenceKind = 'no_data' | 'jank' | 'empty_frame' | 'vsync_anomaly' | 'fps_baseline' | 'degraded_capability' | 'fault_pattern' | 'binder_hotspot' | 'thread_redundancy' | 'memory_growth' | 'gc_pressure' | 'rs_skip' | 'startup';
3364
+ type EvidenceKind = 'no_data' | 'jank' | 'frame_load' | 'empty_frame' | 'vsync_anomaly' | 'fps_baseline' | 'degraded_capability' | 'fault_pattern' | 'binder_hotspot' | 'thread_redundancy' | 'memory_growth' | 'native_memory' | 'hilog_match' | 'gc_pressure' | 'rs_skip' | 'startup' | 'ui_tree' | 'tech_stack' | 'duplicate_asset' | 'oversized_asset' | 'symbol_stats' | 'unresolved_symbol';
1932
3365
  /**
1933
3366
  * A follow-up query an agent can issue to drill into an evidence item.
1934
3367
  *
@@ -1952,9 +3385,23 @@ interface Evidence {
1952
3385
  thread?: string;
1953
3386
  frameNo?: number;
1954
3387
  pid?: number;
3388
+ /**
3389
+ * The rule a `hilog_match` item reports. It is part of the subject rather
3390
+ * than a signal because two rules firing on one log are two findings, and
3391
+ * the subject is what the id and the human-readable line describe.
3392
+ */
3393
+ rule?: string;
1955
3394
  };
1956
3395
  window: TimeRange;
1957
- signals: Record<string, number | string>;
3396
+ /**
3397
+ * The measured facts behind the finding.
3398
+ *
3399
+ * Scalars are the common case; a `hilog_match` item carries its sample
3400
+ * messages as a list, which the renderers stringify the same way they do a
3401
+ * number. Lists are always ordered by the analyzer, so output stays
3402
+ * byte-stable.
3403
+ */
3404
+ signals: Record<string, number | string | readonly string[]>;
1958
3405
  explain: string;
1959
3406
  drillDown: DrillDownHandle[];
1960
3407
  }
@@ -1975,9 +3422,11 @@ declare function evidence(input: Omit<Evidence, 'id'> & {
1975
3422
 
1976
3423
  /**
1977
3424
  * Unit of a metric value. `none` is for dimensionless values such as rates,
1978
- * ratios expressed as plain numbers, or identifiers.
3425
+ * ratios expressed as plain numbers, or identifiers. `hash` is a computed
3426
+ * fingerprint (a dHash), not a measurement: it is a string, and comparing two
3427
+ * of them is a separate operation from comparing numbers.
1979
3428
  */
1980
- type MetricUnit = 'ms' | 'fps' | '%' | 'count' | 'bytes' | 'none';
3429
+ type MetricUnit = 'ms' | 'fps' | '%' | 'count' | 'bytes' | 'none' | 'hash';
1981
3430
  /**
1982
3431
  * Where a metric came from.
1983
3432
  *
@@ -2068,6 +3517,36 @@ interface AnalyzeContext {
2068
3517
  procfs?: ProcfsSample[];
2069
3518
  /** RenderService counter snapshots; present only when a hidumper capture ran. */
2070
3519
  hidumper?: HidumperCapture;
3520
+ /**
3521
+ * The scene's parsed hilog rows. Absent when the scene carries no
3522
+ * `hilog.log`; the analyzer degrades with a reason rather than reporting
3523
+ * zero matches for a capture that never logged.
3524
+ */
3525
+ hilog?: HilogLine[];
3526
+ /**
3527
+ * The rule set to evaluate. Defaults to HapRay's ported rules, so a capture
3528
+ * with no user configuration still produces HapRay's numbers.
3529
+ */
3530
+ hilogRules?: readonly HilogRule[];
3531
+ /**
3532
+ * The scene's flattened UI tree, when it carried a `ui.json`. The `ui`
3533
+ * analyzer decides from what it is given rather than declaring `ui.tree` as a
3534
+ * requirement: a scene can carry a dump captured on a different device, and a
3535
+ * missing artifact is a degradation with a reason, not a skipped analyzer.
3536
+ */
3537
+ ui?: readonly UiNode[];
3538
+ /**
3539
+ * The scene's decoded screenshot, when it carried a `screenshot.png`. Decoded
3540
+ * by the caller so the analyzer performs no IO; a decode failure reaches it
3541
+ * as an absent field plus a reason.
3542
+ */
3543
+ screenshot?: RgbaImage;
3544
+ /**
3545
+ * Why a `screenshot.png` that exists could not be decoded. Present only when
3546
+ * the file was there and the decoder refused it, so the image half degrades
3547
+ * with the decoder's own message instead of claiming no capture happened.
3548
+ */
3549
+ screenshotError?: string;
2071
3550
  metadata?: SceneMetadata;
2072
3551
  app: AppIdentity;
2073
3552
  window: TimeRange;
@@ -2288,12 +3767,27 @@ interface QueryContext {
2288
3767
  readonly db: QueryHandle;
2289
3768
  readonly app: AppIdentity;
2290
3769
  readonly caps: CapabilityMatrix;
3770
+ /**
3771
+ * The scene's second handle, holding the perf tables when the capture
3772
+ * included `--hiperf`. A scene that carries `perf.data` converts it into
3773
+ * `perf.db`, so `perf_sample` / `perf_thread` / `perf_callchain` are **not**
3774
+ * in `db`; a query that reads them through `db` alone returns nothing on a
3775
+ * real capture. Absent means the scene has no perf capture, and every
3776
+ * `frame.load.*` query returns `[]`.
3777
+ */
3778
+ readonly perfDb?: QueryHandle;
2291
3779
  /**
2292
3780
  * The scene's flattened UI tree, when the capture included a `uitest`
2293
3781
  * dump. Absent means the scene has no `ui.json`; `ui.get` then returns no
2294
3782
  * rows rather than failing.
2295
3783
  */
2296
3784
  readonly uiTree?: readonly UiNode[];
3785
+ /**
3786
+ * The scene's parsed hilog rows, when the capture included `--hilog`. Absent
3787
+ * means the scene has no `hilog.log`; every `hilog.*` query then returns no
3788
+ * rows rather than failing, and the analyzer reports a degraded proxy.
3789
+ */
3790
+ readonly hilog?: readonly HilogLine[];
2297
3791
  }
2298
3792
  /** One argument a query accepts, for `ohos-perf tools` and validation. */
2299
3793
  interface QueryArgument {
@@ -2426,6 +3920,140 @@ declare class FrameAnalyzer implements Analyzer {
2426
3920
  run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
2427
3921
  }
2428
3922
 
3923
+ /** One app thread's share of a frame's sampled-event load. */
3924
+ interface FrameLoadThread {
3925
+ threadId: number;
3926
+ threadName: string;
3927
+ /** Summed `event_count` inside the frame window. */
3928
+ samples: number;
3929
+ }
3930
+ /** Sampled-event weight attributed to one file path. */
3931
+ interface PerfFileAttribution {
3932
+ filePath: string;
3933
+ samples: number;
3934
+ }
3935
+ /** The setup a caller hands {@link FrameLoadIndex.build}. */
3936
+ interface FrameLoadIndexInput {
3937
+ perf: PerfQuery;
3938
+ /** App process ids (`process.pid`), matching `perf_thread.process_id`. */
3939
+ pids: readonly number[];
3940
+ /** The range to read samples for; frame windows must fall inside it. */
3941
+ range: TimeRange;
3942
+ }
3943
+ /**
3944
+ * One batched read of `perf_sample` that answers per-frame load queries.
3945
+ *
3946
+ * Reading the samples once and bucketing in memory is what makes a
3947
+ * per-frame join affordable: issuing one `SUM` per frame does a table scan
3948
+ * per frame, and HapRay's batch path solves the same problem the same way.
3949
+ *
3950
+ * The window is the frame's own **inclusive** `[ts, ts + dur]`; `dur <= 0`
3951
+ * collapses it to the point `[ts, ts]`, so a sample exactly at `ts` counts.
3952
+ * Only threads whose `perf_thread.process_id` is one of the app pids are
3953
+ * included; samples from other processes never contribute.
3954
+ *
3955
+ * ## Overlap
3956
+ *
3957
+ * `load()` is a per-frame window aggregate. When two app frames overlap in
3958
+ * time, the same sample contributes to both frame loads — matching HapRay's
3959
+ * batch path — so summing frame loads can exceed {@link spanWeight}, the
3960
+ * unique sample weight read for the whole range. Callers that need a share of
3961
+ * the app's total work should use `spanWeight`; callers that need a frame's
3962
+ * own cost use `load`.
3963
+ */
3964
+ declare class FrameLoadIndex {
3965
+ private readonly threads;
3966
+ /** `perf_sample` rows read (not the summed weight). */
3967
+ readonly sampleRows: number;
3968
+ /** Distinct app thread ids in `perf_thread`. */
3969
+ readonly threadCount: number;
3970
+ /** Summed `event_count` of every sample read, without frame overlap. */
3971
+ readonly spanWeight: number;
3972
+ private constructor();
3973
+ /**
3974
+ * Reads app-thread samples for `range`.
3975
+ *
3976
+ * Returns `undefined` when there is nothing to measure: no `perf_sample`
3977
+ * rows, no `perf_thread` rows for the app pids, or no samples inside the
3978
+ * range. Callers turn that into a degraded result with a reason rather than
3979
+ * reporting zeros.
3980
+ */
3981
+ static build(input: FrameLoadIndexInput): FrameLoadIndex | undefined;
3982
+ /** Summed sampled-event weight of every app thread inside the frame window. */
3983
+ load(frame: Pick<Frame, 'ts' | 'dur'>): number;
3984
+ /**
3985
+ * Splits a frame window by app thread.
3986
+ *
3987
+ * Only positive-weight threads are returned, sorted by `samples` descending
3988
+ * then `threadId` ascending, so equal weights never depend on row order.
3989
+ */
3990
+ threadLoads(frame: Pick<Frame, 'ts' | 'dur'>): FrameLoadThread[];
3991
+ }
3992
+ /**
3993
+ * Per-frame sampled-event load for the app's rendered actual frames.
3994
+ *
3995
+ * ## What a load is
3996
+ *
3997
+ * The summed `perf_sample.event_count` of every app-process thread whose
3998
+ * `timestamp_trace` falls inside the frame's own inclusive
3999
+ * `[ts, ts + dur]`. `event_count` is sample weight; it is not an instruction
4000
+ * count, CPU time or power.
4001
+ *
4002
+ * Frames from several app processes can overlap in time (ui and render in one
4003
+ * vsync period), so a sample contributes to each frame that contains it.
4004
+ * `frame.load.total` is therefore the sum of per-frame loads and can exceed
4005
+ * `frame.load.span.weight`, the unique weight read for the whole span.
4006
+ *
4007
+ * Only **rendered** app actual frames (`type = 0`, `flag !== 2`) feed the
4008
+ * summary and the top list: expect frames are predictions, and empty frames
4009
+ * are measured by the empty-frame analyzer.
4010
+ *
4011
+ * ## Degraded cases
4012
+ *
4013
+ * No app process, no perf samples, no app threads, or samples that exist but
4014
+ * never land inside a frame window all yield one `frame.load.degraded` proxy
4015
+ * with a reason. The last case matters most: it usually means the frame and
4016
+ * perf tables use different timestamp bases, and exact zeros would read as a
4017
+ * workload-free app.
4018
+ */
4019
+ declare class FrameLoadAnalyzer implements Analyzer {
4020
+ readonly id = "frame-load";
4021
+ readonly requires: CapabilityId[];
4022
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4023
+ }
4024
+
4025
+ /** One tumbling FPS window. */
4026
+ interface FpsWindow {
4027
+ startNs: number;
4028
+ endNs: number;
4029
+ /** Rendered frames whose `ts` falls in `[startNs, endNs)`. */
4030
+ frames: number;
4031
+ fps: number;
4032
+ }
4033
+ /**
4034
+ * Tiles rendered frames into fixed-width FPS windows.
4035
+ *
4036
+ * HapRay's FPS path uses `FPS_WINDOW_SIZE_MS = 1000`; this reproduces the
4037
+ * definition without its vsync-group iteration order, which walks frames
4038
+ * group-by-group rather than chronologically. Frames are therefore sorted by
4039
+ * `(ts, id)` first, and a frame exactly on a boundary belongs to the next
4040
+ * window.
4041
+ *
4042
+ * Every window is exactly `windowMs` long, including the last one: a capture
4043
+ * that ends mid-second reports its final window over the full second, which
4044
+ * under-reports that window. This is the standard tumbling-window artifact
4045
+ * and matches upstream, so `frame.fps.window.*` stays comparable to HapRay.
4046
+ *
4047
+ * Idle gaps longer than one window produce explicit `frames: 0` windows; that
4048
+ * is the observable "the UI stopped drawing" signal, not noise to collapse.
4049
+ *
4050
+ * Only actual rendered frames count: `type = 1` rows are predictions and
4051
+ * `flag = 2` rows drew nothing. Duplicate frame ids are counted once.
4052
+ *
4053
+ * An empty input, or a non-positive `windowMs`, returns `[]`.
4054
+ */
4055
+ declare function computeFpsWindows(frames: readonly Frame[], windowMs?: number): FpsWindow[];
4056
+
2429
4057
  /**
2430
4058
  * HapRay's fault-tree payload, with the exact nesting and key names of
2431
4059
  * `fault_tree_analyzer.py:34-60`.
@@ -2641,6 +4269,190 @@ declare class MemoryMeasureAnalyzer implements Analyzer {
2641
4269
  run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
2642
4270
  }
2643
4271
 
4272
+ /** What an event does to the running total. */
4273
+ type NativeEventKind = 'alloc' | 'free' | 'other';
4274
+ /**
4275
+ * Classifies `native_hook.event_type`.
4276
+ *
4277
+ * The column is numeric on the recorded traces but upstream compares it to
4278
+ * strings, so both forms are accepted. `null` — the column was NULL — and
4279
+ * anything else unrecognised is `other`: it is counted, but it must not move
4280
+ * the total in either direction.
4281
+ */
4282
+ declare function nativeEventKind(eventType: number | string | null): NativeEventKind;
4283
+ /** One allocation still live at a given instant. */
4284
+ interface ActiveAlloc {
4285
+ addr: number;
4286
+ /** Remaining bytes; a partial free leaves a smaller size. */
4287
+ size: number;
4288
+ pid: number;
4289
+ tid: number;
4290
+ /** `0` means the event carried no callchain, so the block is unattributable. */
4291
+ callchainId: number;
4292
+ relativeNs: number;
4293
+ }
4294
+ /** Everything one replay of the events establishes. */
4295
+ interface NativeMemoryResult {
4296
+ /** Events read, including types that are neither alloc nor free. */
4297
+ events: number;
4298
+ allocCount: number;
4299
+ allocBytes: number;
4300
+ freeCount: number;
4301
+ freeBytes: number;
4302
+ /** Highest running total and the timestamp of the event that produced it. */
4303
+ peak: number;
4304
+ peakTs: number;
4305
+ /**
4306
+ * Id of the event that produced the peak, `null` when the peak is the initial
4307
+ * zero before any event. `(peakTs, peakId)` is the position the peak's
4308
+ * unreleased set must be replayed to: several events can share a timestamp,
4309
+ * and replaying all of them would report the set after later events already
4310
+ * ran.
4311
+ */
4312
+ peakId: number | null;
4313
+ /** Lowest running total; negative when the capture started mid-lifetime. */
4314
+ trough: number;
4315
+ /** Running total after the last event. */
4316
+ endTotal: number;
4317
+ /** Allocations whose address was NULL; they can never be freed. */
4318
+ unaddressedAllocs: number;
4319
+ /** Frees of an address with no tracked allocation. */
4320
+ unpairedFrees: number;
4321
+ /** Live bytes at the end whose event carried no callchain. */
4322
+ unattributedBytes: number;
4323
+ /**
4324
+ * Live allocations at the `(ts, id)` position, in event order. Omit `id` to
4325
+ * take the state after every event at `ts`.
4326
+ */
4327
+ unreleasedAt(ts: number, id?: number): ActiveAlloc[];
4328
+ }
4329
+ /**
4330
+ * Pairs allocation and free events by address and derives the memory profile.
4331
+ *
4332
+ * The result is a pure function of the events: ordering, ties and the
4333
+ * unreleased sets never depend on map iteration or input order, so two runs
4334
+ * over the same capture are byte-identical.
4335
+ *
4336
+ * A capture that began after allocations happened starts its total at `0` and
4337
+ * may trough negative. That is reported, not clamped: clamping would make every
4338
+ * absolute figure after the trough look larger than it is.
4339
+ */
4340
+ declare function pairNativeMemory(events: readonly NativeHookEvent[]): NativeMemoryResult;
4341
+ /** Name lookups the aggregation needs, all resolved by the caller once. */
4342
+ interface NativeNames {
4343
+ /** `process.pid` → process name. */
4344
+ processes: Map<number, string>;
4345
+ /** `thread.itid` → thread name. */
4346
+ threads: Map<number, string>;
4347
+ /** `data_dict` id → file path. */
4348
+ files: Map<number, string>;
4349
+ /** `data_dict` id → symbol. */
4350
+ symbols: Map<number, string>;
4351
+ /** `callchain_id` → its deepest frame, the one that owns the allocation. */
4352
+ frameLeaves: Map<number, {
4353
+ fileId: number;
4354
+ symbolId: number;
4355
+ }>;
4356
+ }
4357
+ /** One unreleased-memory row: a callchain and thread at one instant. */
4358
+ interface UnreleasedRow {
4359
+ callchainId: number;
4360
+ pid: number;
4361
+ process: string;
4362
+ tid: number;
4363
+ thread: string;
4364
+ file: string;
4365
+ symbol: string;
4366
+ /** Summed remaining bytes. */
4367
+ size: number;
4368
+ /** Active allocations merged into this row. */
4369
+ count: number;
4370
+ /** Earliest allocation instant, relative to the first app event. */
4371
+ firstRelativeNs: number;
4372
+ category: number;
4373
+ categoryName: string;
4374
+ subCategory: string;
4375
+ }
4376
+ /**
4377
+ * Merges live allocations into rows keyed by `(callchainId, pid, tid)`.
4378
+ *
4379
+ * The process, thread, file and symbol come from the trace's own name tables;
4380
+ * a name the trace does not carry is `''` for a process and `'unknown'` for a
4381
+ * thread, matching how the rest of the package renders a missing name. The
4382
+ * category is resolved from the leaf frame, because the leaf is the allocation
4383
+ * site, not the outermost caller.
4384
+ */
4385
+ declare function aggregateUnreleased(allocs: readonly ActiveAlloc[], names: NativeNames): UnreleasedRow[];
4386
+ /** One timeline bucket; only buckets that saw an event are emitted. */
4387
+ interface NativeTimelineBucket {
4388
+ startNs: number;
4389
+ endNs: number;
4390
+ allocBytes: number;
4391
+ freeBytes: number;
4392
+ /** `allocBytes - freeBytes` for this bucket. */
4393
+ deltaBytes: number;
4394
+ /** Running total after the bucket's last event. */
4395
+ totalBytes: number;
4396
+ isPeak: boolean;
4397
+ }
4398
+ /**
4399
+ * Buckets the events into fixed windows anchored at the first event.
4400
+ *
4401
+ * An empty bucket is omitted rather than emitted as zeros: "the capture
4402
+ * recorded nothing here" and "nothing changed here" are different facts, and a
4403
+ * zero would conflate them. `isPeak` marks the bucket holding the peak event,
4404
+ * so a reader can find the worst instant without re-deriving it.
4405
+ */
4406
+ declare function buildNativeTimeline(events: readonly NativeHookEvent[], bucketNs?: number): NativeTimelineBucket[];
4407
+ /**
4408
+ * Native heap growth from the `nativehook` hiprofiler plugin.
4409
+ *
4410
+ * The analyzer pairs alloc and free events per address and reports the running
4411
+ * total, its peak and trough, and what was still live at the peak and at the
4412
+ * end. "Unreleased" is a statement about the capture window, not a leak claim:
4413
+ * memory still held when the trace stopped may be freed a millisecond later,
4414
+ * and a trace that began mid-lifetime starts at zero and can trough negative.
4415
+ *
4416
+ * When only `native_hook_statistic` exists the analyzer reports the end-of-
4417
+ * capture unreleased bytes per callchain as a proxy and deliberately omits the
4418
+ * peak, the timeline and the thread split — those rows cannot support them.
4419
+ */
4420
+ declare class NativeMemoryAnalyzer implements Analyzer {
4421
+ readonly id = "native-memory";
4422
+ readonly requires: CapabilityId[];
4423
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4424
+ /**
4425
+ * The top rows at one instant, each with the queries that explain it.
4426
+ *
4427
+ * The severity threshold is a concentration signal — a row holding a large
4428
+ * share of live memory is worth a look — not a judgment that it is wrong.
4429
+ */
4430
+ private pointEvidence;
4431
+ /** The statistic-only path: end-of-capture totals, explicitly a proxy. */
4432
+ private statisticsOnly;
4433
+ }
4434
+
4435
+ /** Where a native file or thread belongs in the component hierarchy. */
4436
+ interface NativeCategory {
4437
+ /** `ComponentCategory` id; `-1` when nothing matched. */
4438
+ category: number;
4439
+ categoryName: string;
4440
+ /** Component name, package name, basename or thread name, depending on the rule. */
4441
+ subCategory: string;
4442
+ /** The classified path; the ArkTS package path for a refined `.abc` frame. */
4443
+ file: string;
4444
+ }
4445
+ /**
4446
+ * Classifies a native file, its leaf symbol and its thread.
4447
+ *
4448
+ * Precedence: exact path, then regex rules by priority, then the app bundle
4449
+ * rule, then an exact basename, then `SYS_SDK`. A symbol refines an app `.abc`
4450
+ * frame to its ArkTS package and a KMP frame to its Kotlin package. When there
4451
+ * is no usable file the thread rules decide, and a thread that matches nothing
4452
+ * is reported as `Thread` rather than `SYS_SDK`.
4453
+ */
4454
+ declare function classifyNativePath(filePath: string | null, symbol: string | null, thread: string | null): NativeCategory;
4455
+
2644
4456
  /**
2645
4457
  * Startup analyzer over `app_startup`, with a marker-to-first-frame fallback.
2646
4458
  *
@@ -2690,6 +4502,44 @@ declare class RenderAnalyzer implements Analyzer {
2690
4502
  }>;
2691
4503
  }
2692
4504
 
4505
+ /**
4506
+ * The capture's log, evaluated against the rule set.
4507
+ *
4508
+ * The analyzer reads no tables: the collector wrote a raw log, and the caller
4509
+ * parsed it (`ctx.hilog`). That keeps the capture artifact exactly what the
4510
+ * device printed and makes a parser or rule change a re-analysis rather than a
4511
+ * re-capture.
4512
+ *
4513
+ * Zero matches is a measurement, not an absence: a capture that printed
4514
+ * nothing the rules care about reports a zero per rule with `exact` fidelity.
4515
+ * Only a scene with no log at all degrades, and it says so.
4516
+ */
4517
+ declare class HilogAnalyzer implements Analyzer {
4518
+ readonly id = "hilog";
4519
+ readonly requires: CapabilityId[];
4520
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4521
+ }
4522
+
4523
+ /**
4524
+ * What is on screen: the dump's shape and the screenshot's fingerprint.
4525
+ *
4526
+ * The analyzer requires no capability and decides from the artifacts it is
4527
+ * given. `requires: ['ui.tree']` would skip it on a device without `uitest`,
4528
+ * but a scene can carry a `ui.json` captured elsewhere — and a scene with a
4529
+ * screenshot and no dump still has a width, a height and a hash worth
4530
+ * reporting. Each half degrades on its own, so a capture that produced only one
4531
+ * artifact reports the other's absence instead of discarding what it has.
4532
+ *
4533
+ * Neither artifact present is one `ui.degraded` proxy and one `no_data` item
4534
+ * naming both files, which is how the report says "this scene was not captured
4535
+ * with UI data" rather than reporting four zero node counts as measurements.
4536
+ */
4537
+ declare class UiAnalyzer implements Analyzer {
4538
+ readonly id = "ui";
4539
+ readonly requires: CapabilityId[];
4540
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4541
+ }
4542
+
2693
4543
  interface GcSignals {
2694
4544
  full: number;
2695
4545
  sharedFull: number;
@@ -2892,6 +4742,12 @@ declare class FlamegraphAnalyzer implements Analyzer {
2892
4742
  run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
2893
4743
  }
2894
4744
 
4745
+ declare class SymbolsAnalyzer implements Analyzer {
4746
+ readonly id = "symbols";
4747
+ readonly requires: CapabilityId[];
4748
+ run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
4749
+ }
4750
+
2895
4751
  /** HapRay's payload shape: the busiest component plus per-component counts. */
2896
4752
  interface ComponentReuse {
2897
4753
  max_component: string;
@@ -2947,6 +4803,23 @@ declare class ComponentReuseAnalyzer implements Analyzer {
2947
4803
  run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
2948
4804
  }
2949
4805
 
4806
+ /**
4807
+ * One analyzer's share of a run.
4808
+ *
4809
+ * A skipped analyzer still gets a section, with `status: 'degraded'` and the
4810
+ * placeholder metric/evidence pair the engine synthesizes, so a report can
4811
+ * name the missing capability in place instead of dropping the section.
4812
+ */
4813
+ interface AnalyzerSection {
4814
+ readonly analyzerId: string;
4815
+ readonly status: 'measured' | 'degraded';
4816
+ readonly result: AnalyzeResult;
4817
+ }
4818
+ /** A whole run: the merged result plus the per-analyzer sections it came from. */
4819
+ interface AnalyzerRun {
4820
+ readonly result: AnalyzeResult;
4821
+ readonly sections: AnalyzerSection[];
4822
+ }
2950
4823
  /**
2951
4824
  * Runs every analyzer whose capability requirements are satisfied.
2952
4825
  *
@@ -2955,6 +4828,8 @@ declare class ComponentReuseAnalyzer implements Analyzer {
2955
4828
  * order (D5). An analyzer with an unsatisfied requirement is not called: it
2956
4829
  * contributes one `<id>.degraded` proxy metric and one `degraded_capability`
2957
4830
  * evidence item naming the missing capabilities and the device's own reasons.
4831
+ * Every analyzer also contributes one {@link AnalyzerSection} to `sections`,
4832
+ * in the same id order, so a report can attribute each metric to its source.
2958
4833
  *
2959
4834
  * The returned arrays are new and sorted (`metrics` by `id`, `evidence` by
2960
4835
  * `(kind, window.startNs, id)`). Two analyzers emitting the same metric id
@@ -2963,6 +4838,13 @@ declare class ComponentReuseAnalyzer implements Analyzer {
2963
4838
  * integrity rule applies to evidence ids (`DUPLICATE_EVIDENCE_ID`). Neither
2964
4839
  * the context nor any analyzer (including its result arrays) is mutated.
2965
4840
  */
4841
+ declare function runAnalyzerSections(analyzers: readonly Analyzer[], ctx: AnalyzeContext): Promise<AnalyzerRun>;
4842
+ /**
4843
+ * Runs every analyzer and returns only the merged result.
4844
+ *
4845
+ * A thin wrapper over {@link runAnalyzerSections}; existing callers keep the
4846
+ * old shape and behavior exactly.
4847
+ */
2966
4848
  declare function runAnalyzers(analyzers: readonly Analyzer[], ctx: AnalyzeContext): Promise<AnalyzeResult>;
2967
4849
  /**
2968
4850
  * The analyzers an offline `analyze` run executes by default.
@@ -3005,6 +4887,192 @@ declare function resolveAppIdentity(processes: ProcessQuery, packageName: string
3005
4887
  */
3006
4888
  declare function resolveAppIpids(processes: ProcessQuery, pids: readonly number[]): number[];
3007
4889
 
4890
+ /** One non-directory entry, as the central directory records it. */
4891
+ interface ZipEntry {
4892
+ /** The name exactly as stored; forward slashes. */
4893
+ readonly name: string;
4894
+ readonly size: number;
4895
+ readonly compressedSize: number;
4896
+ readonly crc32: number;
4897
+ readonly method: number;
4898
+ /** Where the entry's payload starts in the archive. */
4899
+ readonly dataOffset: number;
4900
+ }
4901
+ interface ZipArchive {
4902
+ /** Non-directory entries, in central-directory order. */
4903
+ readonly entries: readonly ZipEntry[];
4904
+ /** Inflated bytes, CRC-checked. Throws on a mismatch or a bad stream. */
4905
+ read(entry: ZipEntry): Uint8Array;
4906
+ }
4907
+ /** True when the bytes start with a local file header. */
4908
+ declare function isZip(bytes: Uint8Array): boolean;
4909
+ /** Read the central directory and return an archive over `bytes`. */
4910
+ declare function openZip(bytes: Uint8Array): ZipArchive;
4911
+
4912
+ type FileCategory = 'images' | 'videos' | 'audio' | 'fonts' | 'scripts' | 'styles' | 'binaries' | 'bytecode' | 'data' | 'other';
4913
+ /** One archive entry, measured. Paths are archive names, forward slashes. */
4914
+ interface InventoryFile {
4915
+ readonly path: string;
4916
+ readonly size: number;
4917
+ readonly compressedSize: number;
4918
+ /** 8 lowercase hex chars. */
4919
+ readonly crc32: string;
4920
+ /** Lowercase, without the dot; `''` when the name has no extension. */
4921
+ readonly extension: string;
4922
+ readonly category: FileCategory;
4923
+ }
4924
+ /** HapRay's extension table, verbatim. */
4925
+ declare const CATEGORY_EXTENSIONS: Readonly<Record<FileCategory, readonly string[]>>;
4926
+ /**
4927
+ * HapRay's per-category "max optimal size", in bytes.
4928
+ *
4929
+ * The fractions are HapRay's decimal megabytes (0.5, 0.2), converted once here
4930
+ * so no caller has to guess whether a threshold is 500000 or 524288.
4931
+ */
4932
+ declare const CATEGORY_MAX_BYTES: Readonly<Record<FileCategory, number>>;
4933
+ /** The category a lowercase extension belongs to; unknown is `other`. */
4934
+ declare function categorize(extension: string): FileCategory;
4935
+ /** Every non-directory entry, sorted by path. */
4936
+ declare function buildInventory(archive: ZipArchive): InventoryFile[];
4937
+
4938
+ type RuleMatchKind = 'filename' | 'path' | 'extension' | 'magic' | 'content' | 'combined';
4939
+ /** A content pattern, optionally carrying its own confidence (HapRay's YAML). */
4940
+ interface ContentPattern {
4941
+ readonly pattern: string;
4942
+ readonly confidence?: number;
4943
+ }
4944
+ interface FileRule {
4945
+ readonly kind: RuleMatchKind;
4946
+ /** Regex sources, tried in order. */
4947
+ readonly patterns?: readonly (string | ContentPattern)[];
4948
+ readonly extensions?: readonly string[];
4949
+ readonly bytes?: readonly number[];
4950
+ readonly offset?: number;
4951
+ readonly operator?: 'and' | 'or' | 'not';
4952
+ readonly rules?: readonly FileRule[];
4953
+ /** Multiplies the rule's confidence when this file rule decides the match. */
4954
+ readonly confidence?: number;
4955
+ }
4956
+ /** One field read out of a matched file, beside the match. */
4957
+ interface MetadataPattern {
4958
+ readonly field: string;
4959
+ readonly source: 'content' | 'path' | 'filename';
4960
+ readonly pattern: string;
4961
+ readonly captureGroup?: number;
4962
+ }
4963
+ interface TechRule {
4964
+ readonly id: string;
4965
+ readonly name: string;
4966
+ readonly type: string;
4967
+ readonly confidence: number;
4968
+ readonly fileRules: readonly FileRule[];
4969
+ /** When true, a file match without extracted metadata is not a match. */
4970
+ readonly requireMetadata?: boolean;
4971
+ readonly metadataPatterns?: readonly MetadataPattern[];
4972
+ }
4973
+ interface RuleMatch {
4974
+ readonly ruleId: string;
4975
+ readonly ruleName: string;
4976
+ readonly type: string;
4977
+ readonly confidence: number;
4978
+ readonly files: InventoryFile[];
4979
+ readonly bytes: number;
4980
+ readonly metadata: Readonly<Record<string, string>>;
4981
+ }
4982
+ /**
4983
+ * HapRay's `excludes`: entries under these paths are not offered to any rule.
4984
+ *
4985
+ * Its config excludes `resources/base/.*`, and keeping the exclusion means the
4986
+ * same package yields the same detections here as there.
4987
+ */
4988
+ declare const EXCLUDE_PATTERNS: readonly string[];
4989
+ /**
4990
+ * Run every rule against the inventory and report the rules that matched.
4991
+ *
4992
+ * A rule matches when at least one file matches it; the match carries every
4993
+ * matching file, their summed bytes, and the highest confidence any of them
4994
+ * produced. Rules keep their configured order on the way in; the output is
4995
+ * sorted by `(type, ruleId)` so two runs of the same archive agree byte for
4996
+ * byte.
4997
+ */
4998
+ declare function matchHapRules(rules: readonly TechRule[], archive: ZipArchive, inventory: readonly InventoryFile[]): RuleMatch[];
4999
+ /**
5000
+ * Refuse a rule set that cannot run: an unknown kind, an invalid regex, or a
5001
+ * malformed combined rule. HapRay logs a warning and skips the pattern, which
5002
+ * turns a typo into a detection that never fires; a load-time refusal names
5003
+ * the rule instead.
5004
+ */
5005
+ declare function validateRules(rules: readonly TechRule[]): void;
5006
+ /**
5007
+ * HapRay's shipped detections, in its own order.
5008
+ *
5009
+ * Ids and types are the upstream ones so a comparison against its output is
5010
+ * meaningful. The ELF-backed metadata fields (`soDependencies`, `Key`,
5011
+ * `openSourcePackages`, …) are not ported; see the module comment.
5012
+ */
5013
+ declare const TECH_RULES: readonly TechRule[];
5014
+
5015
+ interface DuplicateGroup {
5016
+ readonly sha256: string;
5017
+ readonly size: number;
5018
+ readonly copies: number;
5019
+ readonly wastedBytes: number;
5020
+ readonly paths: readonly string[];
5021
+ }
5022
+ interface OversizedFile {
5023
+ readonly path: string;
5024
+ readonly category: FileCategory;
5025
+ readonly size: number;
5026
+ readonly threshold: number;
5027
+ }
5028
+ interface HapPackage {
5029
+ readonly name: string;
5030
+ readonly bundleName: string;
5031
+ readonly versionName: string;
5032
+ readonly versionCode: number;
5033
+ readonly appName: string;
5034
+ }
5035
+ interface CategoryTotal {
5036
+ readonly name: FileCategory;
5037
+ readonly files: number;
5038
+ readonly size: number;
5039
+ readonly compressedSize: number;
5040
+ }
5041
+ interface HapAnalysis {
5042
+ readonly schemaVersion: 1;
5043
+ readonly package: HapPackage;
5044
+ readonly totals: {
5045
+ files: number;
5046
+ size: number;
5047
+ compressedSize: number;
5048
+ };
5049
+ readonly categories: CategoryTotal[];
5050
+ readonly technologies: RuleMatch[];
5051
+ readonly duplicates: DuplicateGroup[];
5052
+ readonly oversized: OversizedFile[];
5053
+ readonly largest: Array<{
5054
+ path: string;
5055
+ size: number;
5056
+ }>;
5057
+ /**
5058
+ * Every non-directory entry, measured: the population the totals, categories
5059
+ * and largest lists are taken from. This is what a caller opens when an
5060
+ * evidence item raises a question about one file.
5061
+ */
5062
+ readonly files: readonly InventoryFile[];
5063
+ readonly metrics: Metric[];
5064
+ readonly evidence: Evidence[];
5065
+ }
5066
+ /**
5067
+ * Analyze one HAP's bytes into a deterministic document.
5068
+ *
5069
+ * `packageName` names the archive in the document (the caller's file name, not
5070
+ * an absolute path) so the same bytes under a different path stay identical.
5071
+ */
5072
+ declare function analyzeHap(bytes: Uint8Array, packageName: string): HapAnalysis;
5073
+ /** Wrap an analysis as the `static-hap` section the report renderer takes. */
5074
+ declare function hapSection(analysis: HapAnalysis): AnalyzerSection;
5075
+
3008
5076
  /**
3009
5077
  * Which way a metric improves.
3010
5078
  *
@@ -3060,4 +5128,212 @@ interface BaselineComparison {
3060
5128
  */
3061
5129
  declare function compareResults(baseline: AnalyzeResult, current: AnalyzeResult): BaselineComparison;
3062
5130
 
3063
- export { type AnalyzeContext, type AnalyzeResult, type Analyzer, type AppIdentity, type BaselineComparison, type BelowThresholdPattern, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, type CallchainSample, type CallstackEvent, type CallstackEventWithArgs, CallstackQuery, type CapabilityId, type CapabilityInputs, CapabilityMatrix, type CapabilityState, type CollectOptions, type CollectSession, type Collector, type ComponentReuse, ComponentReuseAnalyzer, type ConnectOptions, DEFAULT_QUERY_LIMIT, DEVICE_PERF_PATH, DEVICE_UI_PATH, type DeltaStatus, Device, type DeviceDeps, type DeviceIdentity, DeviceNotFoundError, type DrillDownHandle, EmptyFrameAnalyzer, type EmptyFrameFilter, type Env, type Evidence, type EvidenceKind, FPS_COMMAND, FTRACE_CATEGORIES, FaultTreeAnalyzer, type FaultTreeSignals, type Fidelity, FlamegraphAnalyzer, type FoldedStack, type FpsBucket, type Frame, FrameAnalyzer, type FrameFlag, FrameQuery, type FrameStats, type FrameType, type FtraceOptions, GcAnalyzer, type GcSignals, HIPROFILER_PLUGIN_NAMES, HITCH_COMMAND, HITRACE_DEFAULT_CATEGORIES, Hdc, HdcNotFoundError, type HdcOptions, type HdcResult, type HdcTarget, type HidumperCapture, HidumperCollector, type HidumperSnapshot, type HiperfCapture, type HiperfCollectOptions, HiperfCollector, type HiprofilerCollectOptions, type HiprofilerCollectRequest, HiprofilerCollector, type HiprofilerConfigOptions, type HiprofilerPlugin, type HiprofilerPluginName, HitraceCollector, IngestError, InstantQuery, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MemMeasureQuery, MemoryAnalyzer, MemoryMeasureAnalyzer, type MemoryPluginOptions, type Metric, type MetricDelta, type MetricDirection, type MetricUnit, type NamedQueryDefinition, type NamedQueryInfo, type NamedQueryResult, type NativehookOptions, OhosPerfError, type OptimizationPotential, PLANE_A_PLUGINS, type PerfCallchain, type PerfFunction, PerfQuery, type PerfSampleRow, type PerfThread, type ProbeResult, type ProbeRunner, type ProbeSnapshot, type ProcessInfo, type ProcessMeasure, type ProcessMeasureFilter, ProcessQuery, ProcfsCollector, type ProcfsSample, type ProcfsStatus, type Provenance, type QueryArgument, type QueryContext, type QueryHandle, type RedundancyLevel, type RedundancyType, type RedundantThreadPattern, type RedundantThreadsSummary, RenderAnalyzer, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, Scene, type SceneLayout, type SceneMetadata, SchedQuery, type SchedSlice, type SmapsRollup, StartupAnalyzer, StartupQuery, type StartupRecord, Streamer, StreamerNotFoundError, type StreamerOptions, type ThreadAnalysis, type ThreadAnalysisSummary, ThreadAnalyzer, type ThreadInfo, ThreadQuery, type ThreadState, ThreadStateQuery, type ThreadWakeupResult, type ThreadWakeupThread, type TimeRange, type TraceCollectOptions, type UiNode, UitestCollector, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, analyzeThreadWakeup, buildHiprofilerConfig, buildMatrix, compareResults, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, createSceneLayout, defaultAnalyzers, evidence, filterEmptyFrames, flattenUiTree, ftracePlugin, gpuPlugin, hiperfRecordCommand, ingestScene, lookupQuery, memoryPlugin, metric, nativehookPlugin, openDb, parseFpsCounts, parseHiperfSummary, parseHitches, parseProcfsStatus, parseSmapsRollup, queryDefinitions, readHidumperCapture, readProcfsSamples, readSceneMetadata, readUiTree, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, round2HalfEven, runAnalyzers, runDrillDown, runNamedQuery, runProbe, tableRowCounts, unknownQueryError, writeProcfsSamples, writeSceneMetadata, xpowerPlugin };
5131
+ /** The report document schema. A change to any shape below bumps this. */
5132
+ declare const REPORT_SCHEMA_VERSION = 1;
5133
+ /** Who produced the report; the version is the CLI package version. */
5134
+ interface ReportGenerator {
5135
+ name: string;
5136
+ version: string;
5137
+ }
5138
+ /** The scene the report describes. Inputs are copied, never referenced. */
5139
+ interface ReportScenario {
5140
+ app: {
5141
+ packageName: string;
5142
+ processNames: string[];
5143
+ };
5144
+ device: string;
5145
+ window: TimeRange;
5146
+ /** Capture start from `scene.json`; absent when the scene did not record one. */
5147
+ startedAtNs?: number;
5148
+ /**
5149
+ * The screenshot the bundle carries at `assets/screenshot.png`. Present only
5150
+ * when the scene had one, so a renderer can tell "no image" from "an image
5151
+ * whose size it was not told".
5152
+ */
5153
+ screenshot?: {
5154
+ width: number;
5155
+ height: number;
5156
+ };
5157
+ }
5158
+ /** One analyzer's contribution, ready for rendering. */
5159
+ interface ReportSection {
5160
+ /** The analyzer id, e.g. `frames`. Also the HTML section anchor. */
5161
+ id: string;
5162
+ title: string;
5163
+ status: 'measured' | 'degraded';
5164
+ /** The engine's explanation of why the analyzer was skipped. */
5165
+ degradedReason?: string;
5166
+ /** Sorted by `id`, as the engine emits them. */
5167
+ metrics: Metric[];
5168
+ /** Sorted by `(kind, window.startNs, id)`, as the engine emits them. */
5169
+ evidence: Evidence[];
5170
+ }
5171
+ interface ReportTotals {
5172
+ metrics: number;
5173
+ evidence: number;
5174
+ bySeverity: {
5175
+ info: number;
5176
+ warn: number;
5177
+ critical: number;
5178
+ };
5179
+ measured: number;
5180
+ degraded: number;
5181
+ }
5182
+ /** The complete, versioned report document. */
5183
+ interface ReportModel {
5184
+ schemaVersion: typeof REPORT_SCHEMA_VERSION;
5185
+ generator: ReportGenerator;
5186
+ scenario: ReportScenario;
5187
+ sections: ReportSection[];
5188
+ totals: ReportTotals;
5189
+ comparison?: BaselineComparison;
5190
+ }
5191
+ /** Everything `buildReport` needs; all values are already measured. */
5192
+ interface ReportInput {
5193
+ generator: ReportGenerator;
5194
+ app: AppIdentity;
5195
+ device: string;
5196
+ window: TimeRange;
5197
+ startedAtNs?: number;
5198
+ sections: readonly AnalyzerSection[];
5199
+ comparison?: BaselineComparison;
5200
+ /**
5201
+ * The scene's screenshot dimensions, when one was captured. The report copies
5202
+ * the file to `assets/screenshot.png` and renders it in the `ui` section; the
5203
+ * dimensions are here so the page can state them without decoding the PNG
5204
+ * again. Absent means no image was captured, and the page says so instead of
5205
+ * pointing at a file that does not exist.
5206
+ */
5207
+ screenshot?: {
5208
+ width: number;
5209
+ height: number;
5210
+ };
5211
+ }
5212
+ /** The compact roll-up written to `summary.json`. */
5213
+ interface ReportSummary {
5214
+ schemaVersion: typeof REPORT_SCHEMA_VERSION;
5215
+ app: string;
5216
+ device: string;
5217
+ window: TimeRange;
5218
+ sections: Array<{
5219
+ id: string;
5220
+ title: string;
5221
+ status: 'measured' | 'degraded';
5222
+ degradedReason?: string;
5223
+ metrics: number;
5224
+ evidence: number;
5225
+ }>;
5226
+ totals: ReportTotals;
5227
+ comparison?: Record<DeltaStatus, number>;
5228
+ }
5229
+ /**
5230
+ * Human titles for the analyzers shipped today.
5231
+ *
5232
+ * An id absent here titles as itself: a new analyzer renders honestly before
5233
+ * anyone writes its title, instead of failing the report.
5234
+ */
5235
+ declare const SECTION_TITLES: Readonly<Record<string, string>>;
5236
+ /**
5237
+ * Builds the report document from a section-aware engine run.
5238
+ *
5239
+ * The inputs are copied and sorted, never mutated. Sorting repeats the engine's
5240
+ * order so a model assembled by hand (as in tests) is just as deterministic as
5241
+ * one produced by `runAnalyzerSections` — the report must be byte-stable (D5)
5242
+ * no matter which layer produced its parts.
5243
+ */
5244
+ declare function buildReport(input: ReportInput): ReportModel;
5245
+ /** Collapses the model to its per-section counts and totals. */
5246
+ declare function summarizeReport(model: ReportModel): ReportSummary;
5247
+ /**
5248
+ * The canonical JSON serialization for `report.json` and `summary.json`.
5249
+ *
5250
+ * Two-space indent plus a trailing newline matches `analyze --json`, so a
5251
+ * consumer reads every document in this package the same way.
5252
+ */
5253
+ declare function renderReportJson(model: ReportModel): string;
5254
+ declare function renderSummaryJson(summary: ReportSummary): string;
5255
+
5256
+ /**
5257
+ * One CSV row per metric, in model order (sections by id, metrics by id).
5258
+ *
5259
+ * The header is a documented contract; adding a column is a schema change and
5260
+ * belongs to a new report schema version, not a silent append.
5261
+ */
5262
+ declare function renderMetricsCsv(model: ReportModel): string;
5263
+ /**
5264
+ * One CSV row per evidence item, in model order.
5265
+ *
5266
+ * `drillDown` is intentionally absent: it is structured data that belongs in
5267
+ * the JSON and HTML, and flattening it would make the cell ambiguous.
5268
+ */
5269
+ declare function renderEvidenceCsv(model: ReportModel): string;
5270
+
5271
+ /**
5272
+ * Render the whole report as one self-contained HTML document.
5273
+ *
5274
+ * No scripts, no stylesheets, no images and no URLs: the page is a pure
5275
+ * function of the model, so it opens offline and renders identically anywhere.
5276
+ * Every interpolation goes through {@link escapeHtml}.
5277
+ */
5278
+ declare function renderReportHtml(model: ReportModel): string;
5279
+
5280
+ /**
5281
+ * Render the whole model as a minimal XLSX workbook.
5282
+ *
5283
+ * Sheets: `Summary`, `Metrics`, `Evidence` and, when a comparison is present,
5284
+ * `Compare`. All names are well under Excel's 31-character limit.
5285
+ */
5286
+ declare function renderReportXlsx(model: ReportModel): Uint8Array;
5287
+
5288
+ /**
5289
+ * HTML-escape every interpolated value.
5290
+ *
5291
+ * `&` first, or the other replacements would double-escape. The result is safe
5292
+ * inside text nodes and double-quoted attributes; no renderer emits single
5293
+ * quotes into attribute values, but escaping them is cheaper than remembering
5294
+ * that at each call site.
5295
+ *
5296
+ * One copy serves every page the package writes — the report, the UI diff and
5297
+ * the flamegraph — so a page cannot escape less than its neighbours.
5298
+ */
5299
+ declare function escapeHtml(value: string): string;
5300
+
5301
+ /** The artifacts a report bundle carries for this view, in write order. */
5302
+ declare const FLAMEGRAPH_FILES: readonly ['flamegraph.svg', 'flamegraph.html'];
5303
+ /**
5304
+ * Render folded stacks as a self-contained SVG document.
5305
+ *
5306
+ * An empty list still renders a valid document that says so, rather than a
5307
+ * zero-sized canvas a viewer would show as a blank rectangle.
5308
+ */
5309
+ declare function renderFlamegraphSvg(stacks: readonly FoldedStack[]): string;
5310
+
5311
+ /** Everything the page states around the drawing. */
5312
+ interface FlamegraphPageInput {
5313
+ readonly stacks: readonly FoldedStack[];
5314
+ readonly app: string;
5315
+ readonly window: TimeRange;
5316
+ /**
5317
+ * Unresolved leaf weight as a percentage of the window, or `null` when the
5318
+ * capture had no samples to measure it from.
5319
+ */
5320
+ readonly unresolvedShare: number | null;
5321
+ /**
5322
+ * Whether the capture *asked* for symbolization: `true`, `false`, or `null`
5323
+ * when the scene did not record it.
5324
+ *
5325
+ * Requested, not achieved: `scene.json` records that `--so-dir` was passed,
5326
+ * and nothing records how many frames the symbolizer actually named. A page
5327
+ * that claimed the frames were resolved would contradict the unresolved
5328
+ * share printed directly above it.
5329
+ */
5330
+ readonly symbolizationRequested: boolean | null;
5331
+ }
5332
+ /**
5333
+ * The page: a header card stating what was measured and what the names mean,
5334
+ * then the drawing inline. Everything is in this one file, so the artifact
5335
+ * opens from a folder with no server and no network.
5336
+ */
5337
+ declare function renderFlamegraphHtml(input: FlamegraphPageInput): string;
5338
+
5339
+ export { type ActionDevice, type ActionOutcome, type ActiveAlloc, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AppIdentity, type BaselineComparison, type BelowThresholdPattern, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, CATEGORY_EXTENSIONS, CATEGORY_MAX_BYTES, COLLECTOR_NAMES, type CallchainSample, type CallstackEvent, type CallstackEventWithArgs, CallstackQuery, type CapabilityId, type CapabilityInputs, CapabilityMatrix, type CapabilityState, type CategoryTotal, type CollectOptions, type CollectSession, type Collector, type CollectorName, type CompiledRule, type ComponentReuse, ComponentReuseAnalyzer, type ConnectOptions, type ContentPattern, type CreateEmulatorRequest, DEFAULT_HILOG_RULES, DEFAULT_QUERY_LIMIT, DEVICE_PERF_PATH, DEVICE_SCREENSHOT_PATH, DEVICE_UI_PATH, type DeltaStatus, Device, type DeviceDeps, type DeviceIdentity, DeviceNotFoundError, type DrillDownHandle, type DuplicateGroup, EXCLUDE_PATTERNS, EmptyFrameAnalyzer, type EmptyFrameFilter, type EmulatorBackend, EmulatorClient, type EmulatorClientOptions, EmulatorCommandError, type EmulatorImage, EmulatorImageMissingError, type EmulatorInstance, EmulatorLifecycle, type EmulatorLifecycleOptions, EmulatorNotFoundError, type EmulatorStartResult, type EmulatorStopResult, type Env, type Evidence, type EvidenceKind, FLAMEGRAPH_FILES, FPS_COMMAND, FTRACE_CATEGORIES, FaultTreeAnalyzer, type FaultTreeSignals, type Fidelity, type FileCategory, type FileRule, FlamegraphAnalyzer, type FlamegraphPageInput, type FoldedStack, type FpsBucket, type FpsWindow, type Frame, FrameAnalyzer, type FrameFlag, FrameLoadAnalyzer, FrameLoadIndex, type FrameLoadIndexInput, type FrameLoadThread, FrameQuery, type FrameStats, type FrameType, type FtraceOptions, GEOMETRY_TOLERANCE_PX, GcAnalyzer, type GcSignals, type Gesture, GestureDriver, type GestureResult, HILOG_COMMAND, HIPROFILER_PLUGIN_NAMES, HITCH_COMMAND, HITRACE_DEFAULT_CATEGORIES, type HapAnalysis, type HapPackage, Hdc, HdcNotFoundError, type HdcOptions, type HdcResult, type HdcSlice, type HdcTarget, type HidumperCapture, HidumperCollector, type HidumperSnapshot, HilogAnalyzer, HilogCollector, type HilogLevel, type HilogLine, type HilogMatch, type HilogParseOptions, type HilogRule, type HiperfCapture, type HiperfCollectOptions, HiperfCollector, type HiprofilerCollectOptions, type HiprofilerCollectRequest, HiprofilerCollector, type HiprofilerConfigOptions, type HiprofilerPlugin, type HiprofilerPluginName, HitraceCollector, IGNORED_ATTRIBUTES, type ImageComparison, IngestError, InstantQuery, type InventoryFile, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MemMeasureQuery, MemoryAnalyzer, MemoryMeasureAnalyzer, type MemoryPluginOptions, type MetadataPattern, type Metric, type MetricDelta, type MetricDirection, type MetricUnit, type NamedQueryDefinition, type NamedQueryInfo, type NamedQueryResult, type NativeCategory, type NativeEventKind, type NativeHookEvent, type NativeHookFrame, NativeHookQuery, type NativeHookStatistic, NativeMemoryAnalyzer, type NativeMemoryResult, type NativeNames, type NativeTimelineBucket, type NativehookOptions, OhosPerfError, type OptimizationPotential, type OversizedFile, PLANE_A_PLUGINS, type PerfCallchain, type PerfFileAttribution, type PerfFunction, type PerfLeafAttribution, PerfQuery, type PerfSampleRow, type PerfThread, type ProbeResult, type ProbeRunner, type ProbeSnapshot, type ProcessInfo, type ProcessMeasure, type ProcessMeasureFilter, ProcessQuery, ProcfsCollector, type ProcfsSample, type ProcfsStatus, type Provenance, type QueryArgument, type QueryContext, type QueryHandle, REPORT_SCHEMA_VERSION, type Rect, type RedundancyLevel, type RedundancyType, type RedundantThreadPattern, type RedundantThreadsSummary, RenderAnalyzer, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RuleMatch, type RuleMatchKind, type RunOptions, type RunResult, type RunStepResult, type RunnerCollectOptions, type RunnerDevice, SECTION_TITLES, type Scenario, type ScenarioAction, ScenarioRunner, type ScenarioStep, Scene, type SceneLayout, type SceneMetadata, type SceneStepRef, SchedQuery, type SchedSlice, type ScreenshotCapture, ScreenshotCollector, type SmapsRollup, StartupAnalyzer, StartupQuery, type StartupRecord, type StepCapture, Streamer, StreamerNotFoundError, type StreamerOptions, type SymbolStat, SymbolsAnalyzer, TECH_RULES, type TechRule, type ThreadAnalysis, type ThreadAnalysisSummary, ThreadAnalyzer, type ThreadInfo, ThreadQuery, type ThreadState, ThreadStateQuery, type ThreadWakeupResult, type ThreadWakeupThread, type TimeRange, type TraceCollectOptions, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnreleasedRow, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, aggregateUnreleased, analyzeHap, analyzeThreadWakeup, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, categorize, classifyNativePath, compareImages, compareResults, compareSceneDirs, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, createSceneLayout, decodePng, defaultAnalyzers, dhash, diffTrees, encodePng, escapeHtml, evidence, executeAction, filterEmptyFrames, flattenUiTree, ftracePlugin, gpuPlugin, hapSection, hiperfRecordCommand, ingestScene, isUnresolvedSymbol, isZip, lookupQuery, markRegions, matchHapRules, matchRules, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, openDb, openZip, pairNativeMemory, parseBounds, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseScenario, parseSmapsRollup, queryDefinitions, readHidumperCapture, readHilogText, readProcfsSamples, readSceneMetadata, readUiTree, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderSummaryJson, renderUiDiffHtml, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, round2HalfEven, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, summarizeReport, tableRowCounts, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };