@qontinui/ui-bridge-wrapper 0.8.0 → 0.10.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.
@@ -740,7 +740,7 @@ var LiveSessionTransport = class extends BaseTransport {
740
740
  ws.addEventListener("message", (ev) => this.handleMessage(ev.data));
741
741
  ws.addEventListener("close", () => this.handleClose());
742
742
  ws.addEventListener("error", (ev) => this.handleError(ev));
743
- await new Promise((resolve3, reject) => {
743
+ await new Promise((resolve4, reject) => {
744
744
  const onOpen = () => {
745
745
  try {
746
746
  const frame = {
@@ -770,7 +770,7 @@ var LiveSessionTransport = class extends BaseTransport {
770
770
  )
771
771
  );
772
772
  }, timeoutMs);
773
- this.ackResolvers = { resolve: resolve3, reject, timer };
773
+ this.ackResolvers = { resolve: resolve4, reject, timer };
774
774
  };
775
775
  ws.addEventListener("open", onOpen);
776
776
  });
@@ -917,40 +917,85 @@ function createTransport(config) {
917
917
  var cli_args_exports = {};
918
918
  __reExport(cli_args_exports, ui_bridge_cli_args_star__namespace);
919
919
 
920
- // src/action-outcome.ts
921
- var RETURNED_FAILURE_CODE = "ACTION_FAILED";
922
- function isRecord(v) {
923
- return typeof v === "object" && v !== null && !Array.isArray(v);
924
- }
925
- function nonEmptyString(v) {
926
- return typeof v === "string" && v.length > 0 ? v : null;
927
- }
928
- function isReturnedFailure(result) {
929
- return isRecord(result) && result.success === false;
930
- }
931
- function returnedFailureError(action, result) {
932
- if (!isReturnedFailure(result)) return null;
933
- const r = result;
934
- const failureDetails = isRecord(r.failureDetails) ? r.failureDetails : null;
935
- const errorObj = isRecord(r.error) ? r.error : null;
936
- const code = nonEmptyString(failureDetails?.errorCode) ?? nonEmptyString(errorObj?.code) ?? RETURNED_FAILURE_CODE;
937
- const message = nonEmptyString(r.error) ?? nonEmptyString(errorObj?.message) ?? nonEmptyString(failureDetails?.message) ?? `action '${action}' reported success: false`;
938
- const details = failureDetails ?? errorObj ?? void 0;
939
- const out = { code, message, source: "returned" };
940
- if (details !== void 0) out.details = details;
941
- return out;
920
+ // src/inject-cli-errors.ts
921
+ var InjectCliArgError = class extends Error {
922
+ constructor(message) {
923
+ super(message);
924
+ this.name = "InjectCliArgError";
925
+ }
926
+ };
927
+
928
+ // src/network-throttle.ts
929
+ var NETWORK_PRESETS = {
930
+ "slow-3g": { name: "slow-3g", latencyMs: 2e3, downloadKbps: 400, uploadKbps: 400 },
931
+ "fast-3g": { name: "fast-3g", latencyMs: 563, downloadKbps: 1475, uploadKbps: 675 }
932
+ };
933
+ var MAX_LATENCY_MS = 6e4;
934
+ var MAX_THROUGHPUT_KBPS = 1e7;
935
+ function parsePositiveInt(raw, field, max, allowZero) {
936
+ const n = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
937
+ if (!Number.isFinite(n) || n > max || !allowZero && n === 0) {
938
+ throw new InjectCliArgError(
939
+ `--throttle ${field} must be an integer in ${allowZero ? 0 : 1}..${max} (got ${raw})`
940
+ );
941
+ }
942
+ return n;
942
943
  }
943
- function thrownError(err) {
944
- if (err instanceof WrapperTransportError) {
945
- const out = { code: err.code, message: err.message, source: "thrown" };
946
- if (err.details !== void 0) out.details = err.details;
947
- return out;
944
+ function parseThrottle(raw) {
945
+ const preset = NETWORK_PRESETS[raw];
946
+ if (preset) return { ...preset };
947
+ if (!raw.includes("=")) {
948
+ throw new InjectCliArgError(
949
+ `--throttle expects ${Object.keys(NETWORK_PRESETS).join(" | ")} or latency=<ms>,down=<kbps>,up=<kbps> (got ${raw})`
950
+ );
951
+ }
952
+ const fields = /* @__PURE__ */ new Map();
953
+ for (const part of raw.split(",")) {
954
+ const [k, v, ...rest] = part.split("=").map((s) => s.trim());
955
+ if (!k || v === void 0 || v === "" || rest.length > 0) {
956
+ throw new InjectCliArgError(`--throttle has a malformed item ${JSON.stringify(part)}`);
957
+ }
958
+ if (!["latency", "down", "up"].includes(k)) {
959
+ throw new InjectCliArgError(`--throttle has an unknown key ${JSON.stringify(k)}`);
960
+ }
961
+ if (fields.has(k)) throw new InjectCliArgError(`--throttle lists ${k} twice`);
962
+ fields.set(k, v);
963
+ }
964
+ for (const k of ["latency", "down", "up"]) {
965
+ if (!fields.has(k)) {
966
+ throw new InjectCliArgError(
967
+ `--throttle custom profile needs latency, down and up (missing ${k})`
968
+ );
969
+ }
948
970
  }
949
971
  return {
950
- code: "UNKNOWN",
951
- message: err instanceof Error ? err.message : String(err),
952
- source: "thrown"
972
+ name: "custom",
973
+ latencyMs: parsePositiveInt(fields.get("latency"), "latency", MAX_LATENCY_MS, true),
974
+ downloadKbps: parsePositiveInt(fields.get("down"), "down", MAX_THROUGHPUT_KBPS, false),
975
+ uploadKbps: parsePositiveInt(fields.get("up"), "up", MAX_THROUGHPUT_KBPS, false)
976
+ };
977
+ }
978
+ function cdpConditions(profile) {
979
+ return {
980
+ offline: false,
981
+ latency: profile.latencyMs,
982
+ downloadThroughput: Math.round(profile.downloadKbps * 1e3 / 8),
983
+ uploadThroughput: Math.round(profile.uploadKbps * 1e3 / 8)
984
+ };
985
+ }
986
+ async function applyNetworkEmulation(page, profile, disableCache) {
987
+ if (profile === null && !disableCache) return null;
988
+ const cdp = await page.context().newCDPSession(page);
989
+ await cdp.send("Network.enable");
990
+ if (disableCache) await cdp.send("Network.setCacheDisabled", { cacheDisabled: true });
991
+ const effective = profile ?? {
992
+ name: "unthrottled",
993
+ latencyMs: 0,
994
+ downloadKbps: 0,
995
+ uploadKbps: 0
953
996
  };
997
+ if (profile !== null) await cdp.send("Network.emulateNetworkConditions", cdpConditions(profile));
998
+ return { ...effective, applied: true, cacheDisabled: disableCache };
954
999
  }
955
1000
  var DEFAULT_LOCKSTEP_ATTEMPTS = 3;
956
1001
  var FRAME_SCALE_TOLERANCE_PX = 2;
@@ -1006,19 +1051,19 @@ async function readPageMetrics(page) {
1006
1051
  colorScheme: window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
1007
1052
  }));
1008
1053
  }
1009
- function isRecord2(v) {
1054
+ function isRecord(v) {
1010
1055
  return typeof v === "object" && v !== null && !Array.isArray(v);
1011
1056
  }
1012
1057
  function snapshotGeometry(snapshot) {
1013
- if (!isRecord2(snapshot)) return null;
1058
+ if (!isRecord(snapshot)) return null;
1014
1059
  const data = snapshot["data"];
1015
- const elements = Array.isArray(snapshot["elements"]) ? snapshot["elements"] : isRecord2(data) && Array.isArray(data["elements"]) ? data["elements"] : null;
1060
+ const elements = Array.isArray(snapshot["elements"]) ? snapshot["elements"] : isRecord(data) && Array.isArray(data["elements"]) ? data["elements"] : null;
1016
1061
  if (elements === null) return null;
1017
1062
  const out = /* @__PURE__ */ new Map();
1018
1063
  elements.forEach((el, i) => {
1019
- if (!isRecord2(el)) return;
1064
+ if (!isRecord(el)) return;
1020
1065
  const id = typeof el["id"] === "string" ? el["id"] : `#${i}`;
1021
- const b = isRecord2(el["bbox"]) ? el["bbox"] : null;
1066
+ const b = isRecord(el["bbox"]) ? el["bbox"] : null;
1022
1067
  const box = b ? [b["x"], b["y"], b["width"], b["height"]].map((v) => String(v)).join(",") : "-";
1023
1068
  out.set(id, `${box}|${String(el["visible"])}`);
1024
1069
  });
@@ -1127,6 +1172,232 @@ async function captureFrameInLockstep(opts) {
1127
1172
  }
1128
1173
  };
1129
1174
  }
1175
+
1176
+ // src/timeline-capture.ts
1177
+ var CAPTURE_TIMELINE_ACTION = "captureTimeline";
1178
+ var MAX_TIMELINE_FRAMES = 120;
1179
+ var MAX_TIMELINE_INTERVAL_MS = 1e4;
1180
+ var DEFAULT_TIMELINE_READY_TIMEOUT_MS = 3e4;
1181
+ function asRecord(payload) {
1182
+ if (payload === void 0 || payload === null) return {};
1183
+ if (typeof payload !== "object" || Array.isArray(payload)) {
1184
+ throw new InjectCliArgError(`${CAPTURE_TIMELINE_ACTION} payload must be a JSON object`);
1185
+ }
1186
+ return payload;
1187
+ }
1188
+ function intIn(raw, field, min, max, fallback) {
1189
+ if (raw === void 0 && fallback !== void 0) return fallback;
1190
+ if (typeof raw !== "number" || !Number.isInteger(raw) || raw < min || raw > max) {
1191
+ throw new InjectCliArgError(
1192
+ `${CAPTURE_TIMELINE_ACTION} '${field}' must be an integer in ${min}..${max} (got ${JSON.stringify(raw)})`
1193
+ );
1194
+ }
1195
+ return raw;
1196
+ }
1197
+ function parseCaptureTimelinePayload(payload) {
1198
+ const o = asRecord(payload);
1199
+ if (typeof o.dir !== "string" || o.dir.trim().length === 0) {
1200
+ throw new InjectCliArgError(`${CAPTURE_TIMELINE_ACTION} payload requires a non-empty 'dir'`);
1201
+ }
1202
+ if (o.reload !== void 0 && typeof o.reload !== "boolean") {
1203
+ throw new InjectCliArgError(`${CAPTURE_TIMELINE_ACTION} 'reload' must be a boolean`);
1204
+ }
1205
+ let during = null;
1206
+ if (o.during !== void 0) {
1207
+ const d = o.during;
1208
+ if (d === null || typeof d !== "object" || Array.isArray(d) || typeof d.action !== "string" || d.action.length === 0) {
1209
+ throw new InjectCliArgError(
1210
+ `${CAPTURE_TIMELINE_ACTION} 'during' must be {"action":"<in-page action>","payload":{...}}`
1211
+ );
1212
+ }
1213
+ if (d.action === CAPTURE_TIMELINE_ACTION || d.action.startsWith("__")) {
1214
+ throw new InjectCliArgError(
1215
+ `${CAPTURE_TIMELINE_ACTION} 'during' takes an in-page action, not ${JSON.stringify(d.action)}`
1216
+ );
1217
+ }
1218
+ if (o.reload === true) {
1219
+ throw new InjectCliArgError(
1220
+ `${CAPTURE_TIMELINE_ACTION} cannot combine 'during' with 'reload': the reload replaces the document the action would act on`
1221
+ );
1222
+ }
1223
+ during = { action: d.action, payload: d.payload ?? {} };
1224
+ }
1225
+ return {
1226
+ dir: o.dir,
1227
+ frames: intIn(o.frames, "frames", 1, MAX_TIMELINE_FRAMES),
1228
+ intervalMs: intIn(o.intervalMs, "intervalMs", 0, MAX_TIMELINE_INTERVAL_MS),
1229
+ reload: o.reload === true,
1230
+ readyTimeoutMs: intIn(
1231
+ o.readyTimeoutMs,
1232
+ "readyTimeoutMs",
1233
+ 1,
1234
+ 6e5,
1235
+ DEFAULT_TIMELINE_READY_TIMEOUT_MS
1236
+ ),
1237
+ during
1238
+ };
1239
+ }
1240
+ function assertEmptyDir(dir) {
1241
+ let entries;
1242
+ try {
1243
+ entries = fs.readdirSync(dir);
1244
+ } catch (err) {
1245
+ const code = err.code;
1246
+ if (code === "ENOENT") return;
1247
+ throw new InjectCliArgError(
1248
+ `${CAPTURE_TIMELINE_ACTION}: ${dir} is not a usable directory (${code})`
1249
+ );
1250
+ }
1251
+ if (entries.length > 0) {
1252
+ throw new InjectCliArgError(
1253
+ `${CAPTURE_TIMELINE_ACTION}: ${dir} is not empty; pass an empty directory or one that does not exist yet (frames are never overwritten)`
1254
+ );
1255
+ }
1256
+ }
1257
+ var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
1258
+ async function captureTimeline(page, payload, now = Date.now, execute) {
1259
+ const concurrent = payload.during ?? null;
1260
+ if (concurrent !== null && !execute) {
1261
+ throw new InjectCliArgError(
1262
+ `${CAPTURE_TIMELINE_ACTION} 'during' needs the transport's in-page execute, which this context does not expose`
1263
+ );
1264
+ }
1265
+ const dir = path.resolve(payload.dir);
1266
+ assertEmptyDir(dir);
1267
+ ensurePrivateDir(dir);
1268
+ if (payload.reload) await page.reload({ waitUntil: "commit", timeout: payload.readyTimeoutMs });
1269
+ const t0 = now();
1270
+ const frames = [];
1271
+ const duringRun = concurrent !== null && execute ? (async () => {
1272
+ const { action, payload: p } = concurrent;
1273
+ try {
1274
+ const result = await execute(action, p);
1275
+ const failed2 = typeof result === "object" && result !== null && result.success === false;
1276
+ return { action, result, answeredAtMs: now() - t0, failed: failed2 };
1277
+ } catch (err) {
1278
+ return {
1279
+ action,
1280
+ result: { success: false, error: err instanceof Error ? err.message : String(err) },
1281
+ answeredAtMs: now() - t0,
1282
+ failed: true
1283
+ };
1284
+ }
1285
+ })() : null;
1286
+ for (let k = 1; k <= payload.frames; k++) {
1287
+ const due = t0 + (k - 1) * payload.intervalMs;
1288
+ for (let wait = due - now(); wait > 0; wait = due - now()) await sleep(wait);
1289
+ const at = now();
1290
+ const capturedAt = new Date(at).toISOString();
1291
+ try {
1292
+ const png = await page.screenshot({ type: "png", scale: "device", fullPage: false });
1293
+ const { width, height } = pngDimensions(png);
1294
+ const path$1 = path.join(dir, `frame-${k}.png`);
1295
+ writePrivateFile(path$1, png);
1296
+ frames.push({ index: k, path: path$1, offsetMs: at - t0, capturedAt, width, height });
1297
+ } catch (err) {
1298
+ frames.push({
1299
+ index: k,
1300
+ path: null,
1301
+ offsetMs: at - t0,
1302
+ capturedAt,
1303
+ width: null,
1304
+ height: null,
1305
+ error: err instanceof Error ? err.message : String(err)
1306
+ });
1307
+ }
1308
+ }
1309
+ const during = duringRun ? await duringRun : void 0;
1310
+ let runtimeReady = null;
1311
+ let error;
1312
+ if (during?.failed) error = `the concurrent ${during.action} failed`;
1313
+ if (payload.reload) {
1314
+ try {
1315
+ await page.waitForFunction(
1316
+ () => window.__uiBridgeInjected?.settled === true,
1317
+ void 0,
1318
+ { timeout: payload.readyTimeoutMs }
1319
+ );
1320
+ runtimeReady = true;
1321
+ } catch (err) {
1322
+ runtimeReady = false;
1323
+ error = `the injected runtime did not settle within ${payload.readyTimeoutMs} ms after the reload: ${err instanceof Error ? err.message : String(err)}`;
1324
+ }
1325
+ }
1326
+ const metrics = await readPageMetrics(page);
1327
+ const failed = frames.filter((f) => f.error !== void 0).length;
1328
+ if (failed > 0 && error === void 0) error = `${failed} of ${frames.length} frames failed`;
1329
+ return {
1330
+ success: failed === 0 && runtimeReady !== false && !during?.failed,
1331
+ dir,
1332
+ reloaded: payload.reload,
1333
+ intervalMs: payload.intervalMs,
1334
+ startedAt: new Date(t0).toISOString(),
1335
+ frames,
1336
+ devicePixelRatio: metrics.devicePixelRatio,
1337
+ cssViewport: { width: metrics.innerWidth, height: metrics.innerHeight },
1338
+ colorScheme: metrics.colorScheme,
1339
+ runtimeReady,
1340
+ ...during ? { during } : {},
1341
+ ...error !== void 0 ? { error } : {}
1342
+ };
1343
+ }
1344
+ function registerTimelineCapture(registrar, network, baseDir) {
1345
+ registrar.register(CAPTURE_TIMELINE_ACTION, async (params, ctx) => {
1346
+ const parsed = parseCaptureTimelinePayload(params);
1347
+ const payload = baseDir !== void 0 && !path.isAbsolute(parsed.dir) ? { ...parsed, dir: path.join(baseDir, parsed.dir) } : parsed;
1348
+ const c = ctx;
1349
+ const page = c?.page;
1350
+ if (!page || typeof page.screenshot !== "function" || typeof page.reload !== "function") {
1351
+ throw new InjectCliArgError(
1352
+ `${CAPTURE_TIMELINE_ACTION} needs the transport's page handle, which this context does not expose`
1353
+ );
1354
+ }
1355
+ const execute = c?.execute;
1356
+ const result = await captureTimeline(
1357
+ page,
1358
+ payload,
1359
+ Date.now,
1360
+ typeof execute === "function" ? (a, p) => execute(a, p) : void 0
1361
+ );
1362
+ return { ...result, network: network() };
1363
+ });
1364
+ }
1365
+
1366
+ // src/action-outcome.ts
1367
+ var RETURNED_FAILURE_CODE = "ACTION_FAILED";
1368
+ function isRecord2(v) {
1369
+ return typeof v === "object" && v !== null && !Array.isArray(v);
1370
+ }
1371
+ function nonEmptyString(v) {
1372
+ return typeof v === "string" && v.length > 0 ? v : null;
1373
+ }
1374
+ function isReturnedFailure(result) {
1375
+ return isRecord2(result) && result.success === false;
1376
+ }
1377
+ function returnedFailureError(action, result) {
1378
+ if (!isReturnedFailure(result)) return null;
1379
+ const r = result;
1380
+ const failureDetails = isRecord2(r.failureDetails) ? r.failureDetails : null;
1381
+ const errorObj = isRecord2(r.error) ? r.error : null;
1382
+ const code = nonEmptyString(failureDetails?.errorCode) ?? nonEmptyString(errorObj?.code) ?? RETURNED_FAILURE_CODE;
1383
+ const message = nonEmptyString(r.error) ?? nonEmptyString(errorObj?.message) ?? nonEmptyString(failureDetails?.message) ?? `action '${action}' reported success: false`;
1384
+ const details = failureDetails ?? errorObj ?? void 0;
1385
+ const out = { code, message, source: "returned" };
1386
+ if (details !== void 0) out.details = details;
1387
+ return out;
1388
+ }
1389
+ function thrownError(err) {
1390
+ if (err instanceof WrapperTransportError) {
1391
+ const out = { code: err.code, message: err.message, source: "thrown" };
1392
+ if (err.details !== void 0) out.details = err.details;
1393
+ return out;
1394
+ }
1395
+ return {
1396
+ code: "UNKNOWN",
1397
+ message: err instanceof Error ? err.message : String(err),
1398
+ source: "thrown"
1399
+ };
1400
+ }
1130
1401
  function expandMatrix(axes) {
1131
1402
  const viewports = axes.viewports.length > 0 ? axes.viewports : [null];
1132
1403
  const dprs = axes.dprs.length > 0 ? axes.dprs : [null];
@@ -1204,6 +1475,42 @@ Exec (Variant A \u2014 one-shot; presence of any --exec/--exec-stdin selects thi
1204
1475
  so an N-step run still prints N lines in order. Neither shadows an in-page
1205
1476
  action id \u2014 the injected dispatcher defines neither.
1206
1477
 
1478
+ A timed multi-frame capture (CLI-side too):
1479
+
1480
+ captureTimeline {"dir":"<dir>","frames":8,"intervalMs":250,"reload":false}
1481
+ Screenshot the page 'frames' times (1..120), one every 'intervalMs'
1482
+ (0..10000), into <dir>/frame-<k>.png \u2014 the loading-to-loaded timeline
1483
+ of a slot, NOT a lockstep pair (it records movement on purpose). <dir>
1484
+ must be empty or not exist. With "reload":true the clock starts at a
1485
+ fresh navigation commit, so frame 1 is the page before it painted; the
1486
+ reload drops any media override, and the action waits for the injected
1487
+ runtime to settle again ('readyTimeoutMs', default 30000) so the next
1488
+ step finds a drivable page. In --capture-matrix a relative <dir> lands
1489
+ inside each cell's directory.
1490
+ Result: {"success","dir","reloaded","intervalMs","startedAt",
1491
+ "frames":[{"index","path","offsetMs","capturedAt","width","height"}],
1492
+ "devicePixelRatio","cssViewport","colorScheme","runtimeReady","network"}
1493
+ A frame that could not be taken carries "error" and fails the step.
1494
+ "during":{"action":"mediaOverride","payload":{...}} runs that in-page
1495
+ action CONCURRENTLY with the frames, so the timeline shows the candidate
1496
+ ARRIVING (under --throttle, its slow-network load) while the override
1497
+ still confirms decode before it answers; its result rides on the line
1498
+ as "during" and a failed action fails the step. Not with "reload".
1499
+
1500
+ Swapping an image in place (dev control, served by the injected runtime):
1501
+
1502
+ mediaOverride {"slotId":"hero","src":"/candidate.png"}
1503
+ mediaOverride {"elementId":"img-logo","srcset":"/c-1x.avif 1x, /c-2x.avif 2x"}
1504
+ mediaOverride {"slotId":"hero","src":"/c.png","sources":[{"type":"image/avif","srcset":"/c.avif"}]}
1505
+ mediaOverride {"slotId":"banner","backgroundImage":"/c.png","ttlMs":60000}
1506
+ Swap one slot's image, wait for decode() and confirm currentSrc before
1507
+ answering (an override that cannot be confirmed is rolled back and
1508
+ fails). Inside a <picture> every <source srcset> is replaced too.
1509
+ mediaOverrideRestore {"overrideId":"mo-\u2026"} (or {} for all)
1510
+ Put the originals back and verify each attribute reads back.
1511
+ mediaOverrideList {}
1512
+ What is still overridden \u2014 the proof the page ended restored.
1513
+
1207
1514
  Exec output & exit code:
1208
1515
  One JSON line per action, in order, on stdout \u2014 ALWAYS one line per action,
1209
1516
  including failures. An action that succeeded prints {"action":..,"result":..}.
@@ -1257,6 +1564,21 @@ Frames (Variant A):
1257
1564
  that reports anything else fails the run
1258
1565
  (EMULATION_NOT_APPLIED) instead of being measured as if.
1259
1566
 
1567
+ Network (every mode; applied to the page once it is ready, before any action):
1568
+ --throttle <profile> Emulate a slow network on the page (CDP
1569
+ Network.emulateNetworkConditions). <profile> is
1570
+ slow-3g (2000 ms, 400/400 kbit/s), fast-3g (563 ms,
1571
+ 1475/675 kbit/s), or latency=<ms>,down=<kbps>,up=<kbps>.
1572
+ It persists across reloads of the page, so a
1573
+ captureTimeline {"reload":true} loads throttled.
1574
+ --no-cache Disable the HTTP cache too (Network.setCacheDisabled):
1575
+ a warm cache would let a "slow" reload paint at once.
1576
+ What was applied is stamped as "network" on every
1577
+ captureTimeline result, each capture-matrix cell, and
1578
+ the relay info line; CDP has no getter, so the stamp
1579
+ says what Chromium ACCEPTED, and a refused command
1580
+ fails the run rather than measuring unthrottled.
1581
+
1260
1582
  Capture matrix (its own mode):
1261
1583
  --capture-matrix <dir> Run the plan once per --viewport \xD7 --dpr \xD7 --color-scheme
1262
1584
  combination, each a fresh browser context, and store
@@ -1340,6 +1662,9 @@ Examples:
1340
1662
  --exec 'executeElementAction {"id":"open","request":{"action":"click"}}' \\
1341
1663
  --exec 'getControlSnapshot {}'
1342
1664
 
1665
+ # A candidate in its real slot, its slow-network load timeline, then restored
1666
+ ui-bridge-inject --url http://127.0.0.1:3000/ --throttle slow-3g --no-cache --exec 'mediaOverride {"slotId":"hero","src":"http://127.0.0.1:8080/cand.png"}' --exec 'captureTimeline {"dir":"./tl","frames":6,"intervalMs":200}' --exec 'mediaOverrideRestore {}' --exec 'mediaOverrideList {}'
1667
+
1343
1668
  # Capture matrix: 2 breakpoints x 2 schemes x 2 DPRs = 8 frame-and-snapshot pairs
1344
1669
  ui-bridge-inject --url http://127.0.0.1:3000/ --capture-matrix ./matrix \\
1345
1670
  --viewport 390x844,1280x720 --color-scheme light,dark --dpr 1,2
@@ -1350,12 +1675,6 @@ Examples:
1350
1675
  ui-bridge-inject --url https://qontinui.io/admin \\
1351
1676
  --storage-state auth.json --exec 'getControlSnapshot {}'
1352
1677
  `;
1353
- var InjectCliArgError = class extends Error {
1354
- constructor(message) {
1355
- super(message);
1356
- this.name = "InjectCliArgError";
1357
- }
1358
- };
1359
1678
  function parseExecValue(raw) {
1360
1679
  const trimmed = raw.trim();
1361
1680
  if (trimmed.length === 0) {
@@ -1439,6 +1758,8 @@ function parseArgs(argv) {
1439
1758
  screenshot: null,
1440
1759
  captureMatrix: null,
1441
1760
  storageState: null,
1761
+ throttle: null,
1762
+ noCache: false,
1442
1763
  launchArgs: [],
1443
1764
  execActions: [],
1444
1765
  execStdin: false,
@@ -1618,6 +1939,17 @@ function parseArgs(argv) {
1618
1939
  args.screenshot = raw;
1619
1940
  break;
1620
1941
  }
1942
+ case "--throttle": {
1943
+ const raw = (0, cli_args_exports.consumeValue)("--throttle", argv[++i], mkError);
1944
+ if (raw === null)
1945
+ throw new InjectCliArgError("--throttle expects a profile (got <missing>)");
1946
+ if (args.throttle !== null) throw new InjectCliArgError("--throttle given twice");
1947
+ args.throttle = parseThrottle(raw);
1948
+ break;
1949
+ }
1950
+ case "--no-cache":
1951
+ args.noCache = true;
1952
+ break;
1621
1953
  case "--capture-matrix": {
1622
1954
  const raw = (0, cli_args_exports.consumeValue)("--capture-matrix", argv[++i], mkError);
1623
1955
  if (raw === null || raw.length === 0) {
@@ -1811,7 +2143,7 @@ var CLI_WAIT_ACTIONS = ["waitForSelector", "sleep"];
1811
2143
  var WAIT_SELECTOR_STATES = ["attached", "detached", "visible", "hidden"];
1812
2144
  var DEFAULT_WAIT_SELECTOR_TIMEOUT_MS = 1e4;
1813
2145
  var MAX_SLEEP_MS = 6e5;
1814
- function asRecord(payload, action) {
2146
+ function asRecord2(payload, action) {
1815
2147
  if (payload === void 0 || payload === null) return {};
1816
2148
  if (typeof payload !== "object" || Array.isArray(payload)) {
1817
2149
  throw new InjectCliArgError(`${action} payload must be a JSON object`);
@@ -1819,7 +2151,7 @@ function asRecord(payload, action) {
1819
2151
  return payload;
1820
2152
  }
1821
2153
  function parseWaitForSelectorPayload(payload) {
1822
- const obj = asRecord(payload, "waitForSelector");
2154
+ const obj = asRecord2(payload, "waitForSelector");
1823
2155
  const selector = obj["selector"];
1824
2156
  if (typeof selector !== "string" || selector.trim().length === 0) {
1825
2157
  throw new InjectCliArgError(`waitForSelector payload requires a non-empty 'selector' string`);
@@ -1847,7 +2179,7 @@ function parseWaitForSelectorPayload(payload) {
1847
2179
  return { selector: selector.trim(), timeoutMs, state };
1848
2180
  }
1849
2181
  function parseSleepPayload(payload) {
1850
- const obj = asRecord(payload, "sleep");
2182
+ const obj = asRecord2(payload, "sleep");
1851
2183
  const raw = obj["ms"];
1852
2184
  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0 || raw > MAX_SLEEP_MS) {
1853
2185
  throw new InjectCliArgError(
@@ -1860,12 +2192,13 @@ function validateWaitActions(actions) {
1860
2192
  for (const { action, payload } of actions) {
1861
2193
  if (action === "waitForSelector") parseWaitForSelectorPayload(payload);
1862
2194
  else if (action === "sleep") parseSleepPayload(payload);
2195
+ else if (action === CAPTURE_TIMELINE_ACTION) parseCaptureTimelinePayload(payload);
1863
2196
  }
1864
2197
  }
1865
2198
  function registerWaitActions(registrar) {
1866
2199
  registrar.register("sleep", async (params) => {
1867
2200
  const { ms } = parseSleepPayload(params);
1868
- await new Promise((resolve3) => setTimeout(resolve3, ms));
2201
+ await new Promise((resolve4) => setTimeout(resolve4, ms));
1869
2202
  return { slept: ms };
1870
2203
  });
1871
2204
  registrar.register("waitForSelector", async (params, ctx) => {
@@ -1881,6 +2214,22 @@ function registerWaitActions(registrar) {
1881
2214
  return { waited: true, selector, state, elapsedMs: Date.now() - startedAt };
1882
2215
  });
1883
2216
  }
2217
+ var APPLY_NETWORK_ACTION = "__inject_cli_apply_network";
2218
+ function registerNetworkEmulation(registrar, args) {
2219
+ registrar.register(APPLY_NETWORK_ACTION, async (_params, ctx) => {
2220
+ const page = ctx?.page;
2221
+ if (!page || typeof page.context !== "function") {
2222
+ throw new InjectCliArgError(
2223
+ `--throttle/--no-cache need the transport's page handle, which this context does not expose`
2224
+ );
2225
+ }
2226
+ return applyNetworkEmulation(page, args.throttle, args.noCache);
2227
+ });
2228
+ }
2229
+ async function applyNetwork(transport, args) {
2230
+ if (args.throttle === null && !args.noCache) return null;
2231
+ return await transport.dispatch(APPLY_NETWORK_ACTION);
2232
+ }
1884
2233
  function die(msg) {
1885
2234
  process.stderr.write(`${msg}
1886
2235
  `);
@@ -1891,13 +2240,13 @@ function log(quiet, msg) {
1891
2240
  `);
1892
2241
  }
1893
2242
  function readStdin() {
1894
- return new Promise((resolve3, reject) => {
2243
+ return new Promise((resolve4, reject) => {
1895
2244
  let data = "";
1896
2245
  process.stdin.setEncoding("utf8");
1897
2246
  process.stdin.on("data", (chunk) => {
1898
2247
  data += chunk;
1899
2248
  });
1900
- process.stdin.on("end", () => resolve3(data));
2249
+ process.stdin.on("end", () => resolve4(data));
1901
2250
  process.stdin.on("error", reject);
1902
2251
  });
1903
2252
  }
@@ -2056,11 +2405,15 @@ async function runExec(args, transport) {
2056
2405
  if (err instanceof InjectCliArgError) die(err.message);
2057
2406
  throw err;
2058
2407
  }
2408
+ let network = null;
2059
2409
  registerWaitActions(transport);
2060
2410
  registerFrameCapture(transport);
2411
+ registerNetworkEmulation(transport, args);
2412
+ registerTimelineCapture(transport, () => network);
2061
2413
  log(args.quiet, `[ui-bridge-inject] launching injected transport (exec mode)`);
2062
2414
  try {
2063
2415
  await transport.ready();
2416
+ network = await applyNetwork(transport, args);
2064
2417
  } catch (err) {
2065
2418
  const msg = err instanceof Error ? err.message : String(err);
2066
2419
  process.stderr.write(`[ui-bridge-inject] ready failed: ${msg}
@@ -2069,6 +2422,9 @@ async function runExec(args, transport) {
2069
2422
  });
2070
2423
  process.exit(1);
2071
2424
  }
2425
+ if (network) {
2426
+ log(args.quiet, `[ui-bridge-inject] network emulation applied: ${JSON.stringify(network)}`);
2427
+ }
2072
2428
  const screenshot = args.screenshot;
2073
2429
  let anyError;
2074
2430
  try {
@@ -2100,12 +2456,16 @@ async function runMatrixCell(args, cell, plan, dir) {
2100
2456
  kind: "injected",
2101
2457
  options: buildCellTransportOptions(args, cell)
2102
2458
  });
2459
+ let network = null;
2103
2460
  registerWaitActions(transport);
2104
2461
  registerFrameCapture(transport);
2462
+ registerNetworkEmulation(transport, args);
2463
+ registerTimelineCapture(transport, () => network, cellDir);
2105
2464
  log(args.quiet, `[ui-bridge-inject] capture matrix: cell ${id}`);
2106
2465
  try {
2107
2466
  ensurePrivateDir(cellDir);
2108
2467
  await transport.ready();
2468
+ network = await applyNetwork(transport, args);
2109
2469
  } catch (err) {
2110
2470
  await transport.close().catch(() => {
2111
2471
  });
@@ -2148,7 +2508,8 @@ async function runMatrixCell(args, cell, plan, dir) {
2148
2508
  requested: cell,
2149
2509
  status: anyError ? "incomplete" : "captured",
2150
2510
  results: manifestPath(dir, resultsPath),
2151
- pairs
2511
+ pairs,
2512
+ network
2152
2513
  };
2153
2514
  } catch (err) {
2154
2515
  const e = thrownError(err);
@@ -2265,8 +2626,11 @@ async function runRelay(args, transport) {
2265
2626
  `[ui-bridge-inject] launching injected transport (relay mode, ${args.headed ? "headed" : "headless"})`
2266
2627
  );
2267
2628
  log(args.quiet, `[ui-bridge-inject] url: ${args.url} relay: ${args.relay}`);
2629
+ registerNetworkEmulation(transport, args);
2630
+ let network = null;
2268
2631
  try {
2269
2632
  await transport.ready();
2633
+ network = await applyNetwork(transport, args);
2270
2634
  } catch (err) {
2271
2635
  const msg = err instanceof Error ? err.message : String(err);
2272
2636
  process.stderr.write(`[ui-bridge-inject] ready failed: ${msg}
@@ -2280,7 +2644,8 @@ async function runRelay(args, transport) {
2280
2644
  `${JSON.stringify({
2281
2645
  tabId: info.tabId,
2282
2646
  uiBridgeRegistered: info.uiBridgeRegistered,
2283
- url: args.url
2647
+ url: args.url,
2648
+ network
2284
2649
  })}
2285
2650
  `
2286
2651
  );
@@ -2317,6 +2682,7 @@ if (isMain) {
2317
2682
  });
2318
2683
  }
2319
2684
 
2685
+ exports.APPLY_NETWORK_ACTION = APPLY_NETWORK_ACTION;
2320
2686
  exports.CAPTURE_FRAME_ACTION = CAPTURE_FRAME_ACTION;
2321
2687
  exports.CLI_WAIT_ACTIONS = CLI_WAIT_ACTIONS;
2322
2688
  exports.DEFAULT_WAIT_SELECTOR_TIMEOUT_MS = DEFAULT_WAIT_SELECTOR_TIMEOUT_MS;
@@ -2342,6 +2708,7 @@ exports.parseSleepPayload = parseSleepPayload;
2342
2708
  exports.parseViewport = parseViewport;
2343
2709
  exports.parseWaitForSelectorPayload = parseWaitForSelectorPayload;
2344
2710
  exports.registerFrameCapture = registerFrameCapture;
2711
+ exports.registerNetworkEmulation = registerNetworkEmulation;
2345
2712
  exports.registerWaitActions = registerWaitActions;
2346
2713
  exports.resolveAuthToken = resolveAuthToken;
2347
2714
  exports.selectMode = selectMode;