@qontinui/ui-bridge-wrapper 0.12.0 → 0.14.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.
@@ -5,48 +5,14 @@ var fs = require('fs');
5
5
  var path = require('path');
6
6
  var module$1 = require('module');
7
7
  var crypto = require('crypto');
8
- var ui_bridge_cli_args_star = require('@qontinui/ui-bridge-cli-args');
9
8
 
10
9
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
11
- function _interopNamespace(e) {
12
- if (e && e.__esModule) return e;
13
- var n = Object.create(null);
14
- if (e) {
15
- Object.keys(e).forEach(function (k) {
16
- if (k !== 'default') {
17
- var d = Object.getOwnPropertyDescriptor(e, k);
18
- Object.defineProperty(n, k, d.get ? d : {
19
- enumerable: true,
20
- get: function () { return e[k]; }
21
- });
22
- }
23
- });
24
- }
25
- n.default = e;
26
- return Object.freeze(n);
27
- }
28
-
29
- var ui_bridge_cli_args_star__namespace = /*#__PURE__*/_interopNamespace(ui_bridge_cli_args_star);
30
-
31
- var __defProp = Object.defineProperty;
32
- var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
33
- var __getOwnPropNames = Object.getOwnPropertyNames;
34
- var __hasOwnProp = Object.prototype.hasOwnProperty;
35
10
  var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
36
11
  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
37
12
  }) : x)(function(x) {
38
13
  if (typeof require !== "undefined") return require.apply(this, arguments);
39
14
  throw Error('Dynamic require of "' + x + '" is not supported');
40
15
  });
41
- var __copyProps = (to, from, except, desc) => {
42
- if (from && typeof from === "object" || typeof from === "function") {
43
- for (let key of __getOwnPropNames(from))
44
- if (!__hasOwnProp.call(to, key) && key !== except)
45
- __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
46
- }
47
- return to;
48
- };
49
- var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget);
50
16
 
51
17
  // src/types.ts
52
18
  var WrapperTransportError = class extends Error {
@@ -280,9 +246,60 @@ var HeadlessTransport = class extends BaseTransport {
280
246
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
281
247
  forwardConsole: typeof raw["forwardConsole"] === "boolean" ? raw["forwardConsole"] : void 0,
282
248
  launchArgs: Array.isArray(raw["launchArgs"]) && raw["launchArgs"].every((a) => typeof a === "string") ? raw["launchArgs"] : void 0,
283
- storageStatePath: typeof raw["storageStatePath"] === "string" ? raw["storageStatePath"] : void 0
249
+ storageStatePath: typeof raw["storageStatePath"] === "string" ? raw["storageStatePath"] : void 0,
250
+ ...this.parseContextOptions(raw)
284
251
  };
285
252
  }
253
+ /**
254
+ * `recordHar`, `recordVideo`, `serviceWorkers` and `initRouter`. Unlike the display
255
+ * options above, a malformed value is REFUSED rather than dropped: dropping
256
+ * `recordHar` would leave a caller waiting for an archive that is never
257
+ * written, and dropping `initRouter` would let requests it meant to answer
258
+ * reach the network.
259
+ */
260
+ parseContextOptions(raw) {
261
+ const out = {};
262
+ const invalid = (what) => new WrapperTransportError("INVALID_CONFIG", `Transport kind '${this.kind}': ${what}`);
263
+ const har = raw["recordHar"];
264
+ if (har !== void 0) {
265
+ if (typeof har !== "object" || har === null || typeof har.path !== "string" || har.path.length === 0) {
266
+ throw invalid("options.recordHar must be an object with a non-empty string `path`");
267
+ }
268
+ out.recordHar = har;
269
+ }
270
+ const video = raw["recordVideo"];
271
+ if (video !== void 0) {
272
+ if (typeof video !== "object" || video === null || typeof video.dir !== "string" || video.dir.length === 0) {
273
+ throw invalid("options.recordVideo must be an object with a non-empty string `dir`");
274
+ }
275
+ const size = video.size;
276
+ if (size !== void 0) {
277
+ const positiveInt = (n) => typeof n === "number" && Number.isInteger(n) && n > 0;
278
+ const s = size;
279
+ if (typeof size !== "object" || s === null || !positiveInt(s.width) || !positiveInt(s.height)) {
280
+ throw invalid(
281
+ "options.recordVideo.size must be { width, height } with positive integer sides"
282
+ );
283
+ }
284
+ }
285
+ out.recordVideo = video;
286
+ }
287
+ const sw = raw["serviceWorkers"];
288
+ if (sw !== void 0) {
289
+ if (sw !== "allow" && sw !== "block") {
290
+ throw invalid(`options.serviceWorkers must be 'allow' or 'block' (got ${String(sw)})`);
291
+ }
292
+ out.serviceWorkers = sw;
293
+ }
294
+ const router = raw["initRouter"];
295
+ if (router !== void 0) {
296
+ if (typeof router !== "function") {
297
+ throw invalid("options.initRouter must be a function (context) => void | Promise<void>");
298
+ }
299
+ out.initRouter = router;
300
+ }
301
+ return out;
302
+ }
286
303
  async onReady() {
287
304
  let launchHeadlessTab;
288
305
  const headlessSpecifier = "@qontinui/ui-bridge-headless";
@@ -310,6 +327,13 @@ Underlying import error: ${cause}`
310
327
  const initScripts = await this.buildInitScripts();
311
328
  const relayAuth = this.relayAuth();
312
329
  const pinnedTabId = this.pinnedTabId();
330
+ const { recordHar, recordVideo, serviceWorkers, initRouter: callerRouter } = this.options;
331
+ const contextOptionsRequested = recordHar !== void 0 || recordVideo !== void 0 || serviceWorkers === "block" || callerRouter !== void 0;
332
+ let routerCalled = false;
333
+ const initRouter = contextOptionsRequested || serviceWorkers !== void 0 ? async (context) => {
334
+ routerCalled = true;
335
+ if (callerRouter) await callerRouter(context);
336
+ } : void 0;
313
337
  let tab;
314
338
  try {
315
339
  tab = await launchHeadlessTab({
@@ -328,7 +352,11 @@ Underlying import error: ${cause}`
328
352
  storageStatePath: this.options.storageStatePath,
329
353
  ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
330
354
  ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
331
- ...pinnedTabId ? { pinnedTabId } : {}
355
+ ...pinnedTabId ? { pinnedTabId } : {},
356
+ ...recordHar !== void 0 ? { recordHar } : {},
357
+ ...recordVideo !== void 0 ? { recordVideo } : {},
358
+ ...serviceWorkers !== void 0 ? { serviceWorkers } : {},
359
+ ...initRouter ? { initRouter } : {}
332
360
  });
333
361
  } catch (err) {
334
362
  const cause = err instanceof Error ? err.message : String(err);
@@ -350,6 +378,24 @@ Underlying launch error: ${cause}`
350
378
  tabId: tab.tabId,
351
379
  close: tab.close
352
380
  };
381
+ if (contextOptionsRequested && !routerCalled) {
382
+ await this.onClose().catch(() => {
383
+ });
384
+ throw new WrapperTransportError(
385
+ "CONTEXT_OPTIONS_NOT_APPLIED",
386
+ `The installed '@qontinui/ui-bridge-headless' peer launched the tab without calling initRouter, so it predates the recordHar / recordVideo / serviceWorkers / initRouter passthrough (0.8.0, ui-bridge#381) and ignored them: no HAR or video would be written and no route installed. Upgrade it to 0.8.0 or later.`,
387
+ {
388
+ details: {
389
+ requested: {
390
+ recordHar: recordHar !== void 0,
391
+ recordVideo: recordVideo !== void 0,
392
+ serviceWorkers: serviceWorkers ?? null,
393
+ initRouter: callerRouter !== void 0
394
+ }
395
+ }
396
+ }
397
+ );
398
+ }
353
399
  await this.verifyEmulation(tab.page);
354
400
  await this.afterLaunch(tab.page);
355
401
  }
@@ -696,6 +742,7 @@ var InjectedTransport = class extends HeadlessTransport {
696
742
  execute,
697
743
  find: (criteria) => execute("find", criteria ?? {}),
698
744
  act: (id, request) => execute("executeElementAction", { id, request }),
745
+ element: (id) => execute("getElement", { id }),
699
746
  snapshot: (options) => execute("getControlSnapshot", options ?? {}),
700
747
  assert: (spec) => execute("aiAssert", spec)
701
748
  };
@@ -916,9 +963,33 @@ function createTransport(config) {
916
963
  }
917
964
  }
918
965
 
919
- // src/cli-args.ts
920
- var cli_args_exports = {};
921
- __reExport(cli_args_exports, ui_bridge_cli_args_star__namespace);
966
+ // ../ui-bridge-cli-args/dist/index.js
967
+ function isFlagShaped(value) {
968
+ return value.startsWith("--");
969
+ }
970
+ function consumeValue(flag, raw, error) {
971
+ if (raw === void 0) return null;
972
+ if (isFlagShaped(raw)) {
973
+ throw error(
974
+ `${flag} expects a value but got the flag '${raw}' \u2014 did you omit ${flag}'s argument?`
975
+ );
976
+ }
977
+ return raw;
978
+ }
979
+ function parseNonNegativeInt(flag, raw, error) {
980
+ const n = raw !== null && /^\d+$/.test(raw) ? Number(raw) : NaN;
981
+ if (!Number.isSafeInteger(n)) {
982
+ throw error(`${flag} expects a non-negative integer (got ${raw ?? "<missing>"})`);
983
+ }
984
+ return n;
985
+ }
986
+ function parsePositiveInt(flag, raw, error) {
987
+ const n = raw !== null && /^\d+$/.test(raw) ? Number(raw) : NaN;
988
+ if (!Number.isSafeInteger(n) || n <= 0) {
989
+ throw error(`${flag} expects a positive integer (got ${raw ?? "<missing>"})`);
990
+ }
991
+ return n;
992
+ }
922
993
 
923
994
  // src/inject-cli-errors.ts
924
995
  var InjectCliArgError = class extends Error {
@@ -935,7 +1006,7 @@ var NETWORK_PRESETS = {
935
1006
  };
936
1007
  var MAX_LATENCY_MS = 6e4;
937
1008
  var MAX_THROUGHPUT_KBPS = 1e7;
938
- function parsePositiveInt(raw, field, max, allowZero) {
1009
+ function parsePositiveInt2(raw, field, max, allowZero) {
939
1010
  const n = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
940
1011
  if (!Number.isFinite(n) || n > max || !allowZero && n === 0) {
941
1012
  throw new InjectCliArgError(
@@ -973,9 +1044,9 @@ function parseThrottle(raw) {
973
1044
  }
974
1045
  return {
975
1046
  name: "custom",
976
- latencyMs: parsePositiveInt(fields.get("latency"), "latency", MAX_LATENCY_MS, true),
977
- downloadKbps: parsePositiveInt(fields.get("down"), "down", MAX_THROUGHPUT_KBPS, false),
978
- uploadKbps: parsePositiveInt(fields.get("up"), "up", MAX_THROUGHPUT_KBPS, false)
1047
+ latencyMs: parsePositiveInt2(fields.get("latency"), "latency", MAX_LATENCY_MS, true),
1048
+ downloadKbps: parsePositiveInt2(fields.get("down"), "down", MAX_THROUGHPUT_KBPS, false),
1049
+ uploadKbps: parsePositiveInt2(fields.get("up"), "up", MAX_THROUGHPUT_KBPS, false)
979
1050
  };
980
1051
  }
981
1052
  function cdpConditions(profile) {
@@ -1181,6 +1252,9 @@ var CAPTURE_TIMELINE_ACTION = "captureTimeline";
1181
1252
  var MAX_TIMELINE_FRAMES = 120;
1182
1253
  var MAX_TIMELINE_INTERVAL_MS = 1e4;
1183
1254
  var DEFAULT_TIMELINE_READY_TIMEOUT_MS = 3e4;
1255
+ var NO_COMPOSITOR_FRAME = /Unable to capture screenshot/;
1256
+ var NO_COMPOSITOR_FRAME_RETRY_MS = 16;
1257
+ var MAX_SLEEPS_PER_FRAME_WAIT = 3;
1184
1258
  function asRecord(payload) {
1185
1259
  if (payload === void 0 || payload === null) return {};
1186
1260
  if (typeof payload !== "object" || Array.isArray(payload)) {
@@ -1258,6 +1332,24 @@ function assertEmptyDir(dir) {
1258
1332
  }
1259
1333
  }
1260
1334
  var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
1335
+ async function takeFrameByDeadline(page, deadline, now) {
1336
+ const start = now();
1337
+ const maxAttempts = Math.ceil((deadline - start) / NO_COMPOSITOR_FRAME_RETRY_MS) + 2;
1338
+ let at = start;
1339
+ for (let attempts = 1; ; attempts++) {
1340
+ try {
1341
+ const png = await page.screenshot({ type: "png", scale: "device", fullPage: false });
1342
+ return { png, at, attempts };
1343
+ } catch (err) {
1344
+ const error = err instanceof Error ? err.message : String(err);
1345
+ if (!NO_COMPOSITOR_FRAME.test(error) || attempts >= maxAttempts || now() + NO_COMPOSITOR_FRAME_RETRY_MS >= deadline) {
1346
+ return { error, at, attempts };
1347
+ }
1348
+ }
1349
+ await sleep(NO_COMPOSITOR_FRAME_RETRY_MS);
1350
+ at = now();
1351
+ }
1352
+ }
1261
1353
  async function captureTimeline(page, payload, now = Date.now, execute) {
1262
1354
  const concurrent = payload.during ?? null;
1263
1355
  if (concurrent !== null && !execute) {
@@ -1288,26 +1380,33 @@ async function captureTimeline(page, payload, now = Date.now, execute) {
1288
1380
  })() : null;
1289
1381
  for (let k = 1; k <= payload.frames; k++) {
1290
1382
  const due = t0 + (k - 1) * payload.intervalMs;
1291
- for (let wait = due - now(); wait > 0; wait = due - now()) await sleep(wait);
1292
- const at = now();
1293
- const capturedAt = new Date(at).toISOString();
1294
- try {
1295
- const png = await page.screenshot({ type: "png", scale: "device", fullPage: false });
1296
- const { width, height } = pngDimensions(png);
1297
- const path$1 = path.join(dir, `frame-${k}.png`);
1298
- writePrivateFile(path$1, png);
1299
- frames.push({ index: k, path: path$1, offsetMs: at - t0, capturedAt, width, height });
1300
- } catch (err) {
1301
- frames.push({
1302
- index: k,
1303
- path: null,
1304
- offsetMs: at - t0,
1305
- capturedAt,
1306
- width: null,
1307
- height: null,
1308
- error: err instanceof Error ? err.message : String(err)
1309
- });
1383
+ for (let wait = due - now(), sleeps = 0; wait > 0 && sleeps < MAX_SLEEPS_PER_FRAME_WAIT; wait = due - now(), sleeps++) {
1384
+ await sleep(wait);
1385
+ }
1386
+ const deadline = k === 1 && payload.reload ? t0 + payload.readyTimeoutMs : t0 + k * payload.intervalMs;
1387
+ const shot = await takeFrameByDeadline(page, deadline, now);
1388
+ const frame = {
1389
+ index: k,
1390
+ path: null,
1391
+ offsetMs: shot.at - t0,
1392
+ capturedAt: new Date(shot.at).toISOString(),
1393
+ width: null,
1394
+ height: null,
1395
+ ...shot.attempts > 1 ? { attempts: shot.attempts } : {}
1396
+ };
1397
+ if ("error" in shot) {
1398
+ frame.error = shot.error;
1399
+ } else {
1400
+ try {
1401
+ const { width, height } = pngDimensions(shot.png);
1402
+ const path$1 = path.join(dir, `frame-${k}.png`);
1403
+ writePrivateFile(path$1, shot.png);
1404
+ Object.assign(frame, { path: path$1, width, height });
1405
+ } catch (err) {
1406
+ frame.error = err instanceof Error ? err.message : String(err);
1407
+ }
1310
1408
  }
1409
+ frames.push(frame);
1311
1410
  }
1312
1411
  const during = duringRun ? await duringRun : void 0;
1313
1412
  let runtimeReady = null;
@@ -1478,27 +1577,96 @@ Exec (Variant A \u2014 one-shot; presence of any --exec/--exec-stdin selects thi
1478
1577
  so an N-step run still prints N lines in order. Neither shadows an in-page
1479
1578
  action id \u2014 the injected dispatcher defines neither.
1480
1579
 
1481
- A timed multi-frame capture (CLI-side too):
1580
+ Reading and acting on one element (in-page actions):
1581
+
1582
+ getElement {"id":"<id>"}
1583
+ One element as a snapshot carries it: identity (id, type, tagName,
1584
+ label, role, accessibleName), "state", box ("bbox", "visible") and
1585
+ "actions" \u2014 the same object as the matching getControlSnapshot element,
1586
+ redaction included. {"elementId":"<id>"} is accepted too; given both,
1587
+ they must name the same element. Nothing settles first: run
1588
+ waitForSelector before it for a settled read. Beside the id it
1589
+ tolerates, and ignores, settleTimeout and skipSettle (it does not
1590
+ settle), targetTabId, and the WebSocket protocol's "includeState" (the
1591
+ state is always included); any other key is refused with
1592
+ INVALID_REQUEST. An unknown id, or one whose DOM node is gone, is a
1593
+ RETURNED ELEMENT_NOT_FOUND (an "error" line, exit 1), never a null
1594
+ result.
1595
+
1596
+ getElementState {"id":"<id>"}
1597
+ The state alone (visible, enabled, focused, ariaPressed, value, ...).
1598
+ It reads "id" only, and an unknown id is a THROWN error (HANDLER_ERROR).
1599
+
1600
+ executeElementAction {"id":"<id>","request":{"action":"click"}}
1601
+ Act on one element. "request" holds the verb and the fields it reads
1602
+ ("value", "text", "clear", "params", "fromSnapshotId", ...). Two other
1603
+ spellings are accepted:
1604
+ {"elementId":"<id>","request":{"action":"focus"}} "elementId" for "id"
1605
+ {"id":"<id>","action":"type","text":"hi"} flat: the payload,
1606
+ minus "id"/"elementId", IS the request
1607
+ No key BESIDE a "request" object is silently dropped: a top-level
1608
+ "action" or request field ("value", "text", ...) there must equal the
1609
+ same field inside "request" (an agreeing duplicate is accepted); one
1610
+ that is only at the top level, or at both levels with different
1611
+ values, is refused, and so are an "id" and an "elementId" that name
1612
+ different elements. settleTimeout, skipSettle and targetTabId stay
1613
+ allowed at the top level. The request fields themselves (the keys
1614
+ inside "request", or every key of a flat payload but the id) reach
1615
+ the action as sent, so a misspelt one there ("txt" for "text") is not
1616
+ caught. Every refused shape is a RETURNED INVALID_REQUEST (an "error"
1617
+ line, exit 1; never a thrown TypeError) whose message names the
1618
+ canonical shape
1619
+ {"id":"<elementId>","request":{"action":"<action>", \u2026}}
1620
+ and both accepted spellings, and names keys and the kinds of values,
1621
+ never a value, with one exception: an "id" and an "elementId" that
1622
+ disagree are both named (they are the element ids the caller sent, and
1623
+ naming both is what makes the conflict diagnosable); "error.details"
1624
+ adds "expectedPayload" and "receivedKeys". A well-formed payload with
1625
+ an unknown verb is refused with UNSUPPORTED_ACTION, naming the
1626
+ accepted verbs.
1627
+
1628
+ A timed multi-frame capture (CLI-side, like the waits):
1482
1629
 
1483
1630
  captureTimeline {"dir":"<dir>","frames":8,"intervalMs":250,"reload":false}
1484
1631
  Screenshot the page 'frames' times (1..120), one every 'intervalMs'
1485
1632
  (0..10000), into <dir>/frame-<k>.png \u2014 the loading-to-loaded timeline
1486
1633
  of a slot, NOT a lockstep pair (it records movement on purpose). <dir>
1487
1634
  must be empty or not exist. With "reload":true the clock starts at a
1488
- fresh navigation commit, so frame 1 is the page before it painted; the
1635
+ fresh navigation commit, and frame 1 is the first frame the page
1636
+ produced after that commit. Right after the commit the new document can
1637
+ have no compositor frame yet, and Chromium refuses the screenshot
1638
+ ("Unable to capture screenshot"); frame 1 retries that refusal every
1639
+ 16 ms until 'readyTimeoutMs' after the commit. A frame's "offsetMs" is
1640
+ when the screenshot that produced it was requested, so a frame 1 that
1641
+ had to wait reads the tens of ms its retries took, not 0. Under
1642
+ --throttle that first frame can still be the previous document's held
1643
+ frame; "offsetMs" dates it either way. Every other frame retries the
1644
+ same refusal only while the retry falls due before the next frame's
1645
+ due time ("intervalMs":0 is one attempt), so retries never take a
1646
+ later frame's slot; an attempt still under way when the next frame
1647
+ falls due delays it by what is left of that attempt, as any slow
1648
+ screenshot does. No other error is retried. A frame that took more
1649
+ than one attempt says how many in "attempts". The
1489
1650
  reload drops any media override, and the action waits for the injected
1490
1651
  runtime to settle again ('readyTimeoutMs', default 30000) so the next
1491
1652
  step finds a drivable page. In --capture-matrix a relative <dir> lands
1492
1653
  inside each cell's directory.
1493
1654
  Result: {"success","dir","reloaded","intervalMs","startedAt",
1494
- "frames":[{"index","path","offsetMs","capturedAt","width","height"}],
1655
+ "frames":[{"index","path","offsetMs","capturedAt","width","height",
1656
+ "attempts" (only when > 1)}],
1495
1657
  "devicePixelRatio","cssViewport","colorScheme","runtimeReady","network"}
1496
- A frame that could not be taken carries "error" and fails the step.
1658
+ A frame that could not be taken, or was still refused at its deadline,
1659
+ carries "error" and fails the step.
1497
1660
  "during":{"action":"mediaOverride","payload":{...}} runs that in-page
1498
1661
  action CONCURRENTLY with the frames, so the timeline shows the candidate
1499
1662
  ARRIVING (under --throttle, its slow-network load) while the override
1500
1663
  still confirms decode before it answers; its result rides on the line
1501
1664
  as "during" and a failed action fails the step. Not with "reload".
1665
+ An image URL this document already decoded is NOT observed arriving:
1666
+ Chromium 158 serves it again with no request, even under --no-cache
1667
+ (Chromium 147 refetched it); only a new URL or a reload reaches the
1668
+ network. So give the candidate a URL the document has not decoded,
1669
+ such as a per-candidate query string ("cand.png?2").
1502
1670
 
1503
1671
  Swapping an image in place (dev control, served by the injected runtime):
1504
1672
 
@@ -1509,6 +1677,10 @@ Exec (Variant A \u2014 one-shot; presence of any --exec/--exec-stdin selects thi
1509
1677
  Swap one slot's image, wait for decode() and confirm currentSrc before
1510
1678
  answering (an override that cannot be confirmed is rolled back and
1511
1679
  fails). Inside a <picture> every <source srcset> is replaced too.
1680
+ On Chromium 158 a candidate URL this document already decoded is
1681
+ served with no request, even under --no-cache: only a new URL or a
1682
+ reload reaches the network, so a slow-network candidate needs its own
1683
+ URL (a per-candidate query string).
1512
1684
  mediaOverrideRestore {"overrideId":"mo-\u2026"} (or {} for all)
1513
1685
  Put the originals back and verify each attribute reads back.
1514
1686
  mediaOverrideList {}
@@ -1589,6 +1761,11 @@ Network (every mode; applied to the page once it is ready, before any action):
1589
1761
  captureTimeline {"reload":true} loads throttled.
1590
1762
  --no-cache Disable the HTTP cache too (Network.setCacheDisabled):
1591
1763
  a warm cache would let a "slow" reload paint at once.
1764
+ It does NOT reach the document's in-memory image
1765
+ cache: on Chromium 158 a URL this page already
1766
+ decoded is answered at once, throttle or not -- give
1767
+ a repeated mediaOverride candidate its own URL
1768
+ (e.g. ?2).
1592
1769
  What was applied is stamped as "network" on every
1593
1770
  captureTimeline result, each capture-matrix cell, and
1594
1771
  the relay info line; CDP has no getter, so the stamp
@@ -1802,16 +1979,16 @@ function parseArgs(argv) {
1802
1979
  // String value-flags: guard each consumed value against the flag-shaped
1803
1980
  // swallow (`--url --headed` must error, not capture `--headed` as the url).
1804
1981
  case "--url":
1805
- args.url = (0, cli_args_exports.consumeValue)("--url", argv[++i], mkError) ?? "";
1982
+ args.url = consumeValue("--url", argv[++i], mkError) ?? "";
1806
1983
  break;
1807
1984
  case "--relay":
1808
- args.relay = (0, cli_args_exports.consumeValue)("--relay", argv[++i], mkError);
1985
+ args.relay = consumeValue("--relay", argv[++i], mkError);
1809
1986
  break;
1810
1987
  case "--auth-token":
1811
- args.authToken = (0, cli_args_exports.consumeValue)("--auth-token", argv[++i], mkError);
1988
+ args.authToken = consumeValue("--auth-token", argv[++i], mkError);
1812
1989
  break;
1813
1990
  case "--auth-token-file": {
1814
- const raw = (0, cli_args_exports.consumeValue)("--auth-token-file", argv[++i], mkError);
1991
+ const raw = consumeValue("--auth-token-file", argv[++i], mkError);
1815
1992
  if (raw === null || raw.length === 0) {
1816
1993
  throw new InjectCliArgError(
1817
1994
  `--auth-token-file expects a path to a file holding the bearer token (got <missing>)`
@@ -1821,16 +1998,16 @@ function parseArgs(argv) {
1821
1998
  break;
1822
1999
  }
1823
2000
  case "--app-id":
1824
- args.appId = (0, cli_args_exports.consumeValue)("--app-id", argv[++i], mkError);
2001
+ args.appId = consumeValue("--app-id", argv[++i], mkError);
1825
2002
  break;
1826
2003
  case "--app-name":
1827
- args.appName = (0, cli_args_exports.consumeValue)("--app-name", argv[++i], mkError);
2004
+ args.appName = consumeValue("--app-name", argv[++i], mkError);
1828
2005
  break;
1829
2006
  case "--tab-id":
1830
- args.tabId = (0, cli_args_exports.consumeValue)("--tab-id", argv[++i], mkError);
2007
+ args.tabId = consumeValue("--tab-id", argv[++i], mkError);
1831
2008
  break;
1832
2009
  case "--storage-state": {
1833
- const raw = (0, cli_args_exports.consumeValue)("--storage-state", argv[++i], mkError);
2010
+ const raw = consumeValue("--storage-state", argv[++i], mkError);
1834
2011
  if (raw === null || raw.length === 0) {
1835
2012
  throw new InjectCliArgError(
1836
2013
  `--storage-state expects a path to a storageState JSON file (got <missing>)`
@@ -1848,7 +2025,7 @@ function parseArgs(argv) {
1848
2025
  break;
1849
2026
  }
1850
2027
  case "--exec": {
1851
- const raw = (0, cli_args_exports.consumeValue)("--exec", argv[++i], mkError);
2028
+ const raw = consumeValue("--exec", argv[++i], mkError);
1852
2029
  if (raw === null) {
1853
2030
  throw new InjectCliArgError(`--exec expects '<action> <json-payload>' (got <missing>)`);
1854
2031
  }
@@ -1856,7 +2033,7 @@ function parseArgs(argv) {
1856
2033
  break;
1857
2034
  }
1858
2035
  case "--registration-metadata": {
1859
- const raw = (0, cli_args_exports.consumeValue)("--registration-metadata", argv[++i], mkError);
2036
+ const raw = consumeValue("--registration-metadata", argv[++i], mkError);
1860
2037
  if (raw === null) {
1861
2038
  throw new InjectCliArgError(
1862
2039
  `--registration-metadata expects JSON {"userId","sessionId"} (got <missing>)`
@@ -1878,44 +2055,32 @@ function parseArgs(argv) {
1878
2055
  args.registrationMetadata = { userId: m.userId, sessionId: m.sessionId };
1879
2056
  break;
1880
2057
  }
1881
- case "--ready-timeout": {
1882
- const raw = (0, cli_args_exports.consumeValue)("--ready-timeout", argv[++i], mkError);
1883
- const n = raw === null ? NaN : Number.parseInt(raw, 10);
1884
- if (!Number.isFinite(n) || n <= 0) {
1885
- throw new InjectCliArgError(
1886
- `--ready-timeout expects a positive integer (got ${raw ?? "<missing>"})`
1887
- );
1888
- }
1889
- args.readyTimeoutMs = n;
2058
+ case "--ready-timeout":
2059
+ args.readyTimeoutMs = parsePositiveInt(
2060
+ "--ready-timeout",
2061
+ consumeValue("--ready-timeout", argv[++i], mkError),
2062
+ mkError
2063
+ );
1890
2064
  break;
1891
- }
1892
2065
  case "--no-settle":
1893
2066
  args.waitForSettle = false;
1894
2067
  break;
1895
- case "--settle-quiet": {
1896
- const raw = (0, cli_args_exports.consumeValue)("--settle-quiet", argv[++i], mkError);
1897
- const n = raw === null ? NaN : Number.parseInt(raw, 10);
1898
- if (!Number.isFinite(n) || n < 0) {
1899
- throw new InjectCliArgError(
1900
- `--settle-quiet expects a non-negative integer (got ${raw ?? "<missing>"})`
1901
- );
1902
- }
1903
- args.settleQuietMs = n;
2068
+ case "--settle-quiet":
2069
+ args.settleQuietMs = parseNonNegativeInt(
2070
+ "--settle-quiet",
2071
+ consumeValue("--settle-quiet", argv[++i], mkError),
2072
+ mkError
2073
+ );
1904
2074
  break;
1905
- }
1906
- case "--settle-timeout": {
1907
- const raw = (0, cli_args_exports.consumeValue)("--settle-timeout", argv[++i], mkError);
1908
- const n = raw === null ? NaN : Number.parseInt(raw, 10);
1909
- if (!Number.isFinite(n) || n <= 0) {
1910
- throw new InjectCliArgError(
1911
- `--settle-timeout expects a positive integer (got ${raw ?? "<missing>"})`
1912
- );
1913
- }
1914
- args.settleTimeoutMs = n;
2075
+ case "--settle-timeout":
2076
+ args.settleTimeoutMs = parsePositiveInt(
2077
+ "--settle-timeout",
2078
+ consumeValue("--settle-timeout", argv[++i], mkError),
2079
+ mkError
2080
+ );
1915
2081
  break;
1916
- }
1917
2082
  case "--expect-selector": {
1918
- const raw = (0, cli_args_exports.consumeValue)("--expect-selector", argv[++i], mkError);
2083
+ const raw = consumeValue("--expect-selector", argv[++i], mkError);
1919
2084
  if (raw === null || raw.length === 0) {
1920
2085
  throw new InjectCliArgError(`--expect-selector expects a CSS selector (got <missing>)`);
1921
2086
  }
@@ -1926,19 +2091,19 @@ function parseArgs(argv) {
1926
2091
  // list and every occurrence appends; `validateArgs` then allows more than
1927
2092
  // one value only under --capture-matrix, where they are an axis.
1928
2093
  case "--viewport": {
1929
- const raw = (0, cli_args_exports.consumeValue)("--viewport", argv[++i], mkError);
2094
+ const raw = consumeValue("--viewport", argv[++i], mkError);
1930
2095
  if (raw === null) throw new InjectCliArgError(`--viewport expects WxH (got <missing>)`);
1931
2096
  for (const item of splitList("--viewport", raw)) args.viewports.push(parseViewport(item));
1932
2097
  break;
1933
2098
  }
1934
2099
  case "--dpr": {
1935
- const raw = (0, cli_args_exports.consumeValue)("--dpr", argv[++i], mkError);
2100
+ const raw = consumeValue("--dpr", argv[++i], mkError);
1936
2101
  if (raw === null) throw new InjectCliArgError(`--dpr expects a number (got <missing>)`);
1937
2102
  for (const item of splitList("--dpr", raw)) args.dprs.push(parseDpr(item));
1938
2103
  break;
1939
2104
  }
1940
2105
  case "--color-scheme": {
1941
- const raw = (0, cli_args_exports.consumeValue)("--color-scheme", argv[++i], mkError);
2106
+ const raw = consumeValue("--color-scheme", argv[++i], mkError);
1942
2107
  if (raw === null) {
1943
2108
  throw new InjectCliArgError(`--color-scheme expects dark or light (got <missing>)`);
1944
2109
  }
@@ -1948,7 +2113,7 @@ function parseArgs(argv) {
1948
2113
  break;
1949
2114
  }
1950
2115
  case "--screenshot": {
1951
- const raw = (0, cli_args_exports.consumeValue)("--screenshot", argv[++i], mkError);
2116
+ const raw = consumeValue("--screenshot", argv[++i], mkError);
1952
2117
  if (raw === null || raw.length === 0) {
1953
2118
  throw new InjectCliArgError(`--screenshot expects a PNG path (got <missing>)`);
1954
2119
  }
@@ -1956,7 +2121,7 @@ function parseArgs(argv) {
1956
2121
  break;
1957
2122
  }
1958
2123
  case "--throttle": {
1959
- const raw = (0, cli_args_exports.consumeValue)("--throttle", argv[++i], mkError);
2124
+ const raw = consumeValue("--throttle", argv[++i], mkError);
1960
2125
  if (raw === null)
1961
2126
  throw new InjectCliArgError("--throttle expects a profile (got <missing>)");
1962
2127
  if (args.throttle !== null) throw new InjectCliArgError("--throttle given twice");
@@ -1967,7 +2132,7 @@ function parseArgs(argv) {
1967
2132
  args.noCache = true;
1968
2133
  break;
1969
2134
  case "--capture-matrix": {
1970
- const raw = (0, cli_args_exports.consumeValue)("--capture-matrix", argv[++i], mkError);
2135
+ const raw = consumeValue("--capture-matrix", argv[++i], mkError);
1971
2136
  if (raw === null || raw.length === 0) {
1972
2137
  throw new InjectCliArgError(
1973
2138
  `--capture-matrix expects an output directory (got <missing>)`