@qontinui/ui-bridge-wrapper 0.9.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.
@@ -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,55 @@ 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
+
1514
+ Hiding text for one frame (dev control, served by the injected runtime):
1515
+
1516
+ textVisibility {"hidden":true,"ttlMs":30000}
1517
+ Make every glyph on the page transparent (colour, text fill, SVG text
1518
+ fill, text-shadow), with transitions off so the frame is not caught
1519
+ mid-fade; nothing moves, and currentColor borders and icons keep their
1520
+ colour. Capture frame A before and frame B after: inside a text
1521
+ element's box the two differ exactly where its glyphs paint. A TTL
1522
+ (default 30000 ms) restores the page if the run dies.
1523
+ textVisibility {"hidden":false}
1524
+ Restore exactly (the style attributes read back byte for byte);
1525
+ "restore":{"verified":true} is a clean restore.
1526
+
1207
1527
  Exec output & exit code:
1208
1528
  One JSON line per action, in order, on stdout \u2014 ALWAYS one line per action,
1209
1529
  including failures. An action that succeeded prints {"action":..,"result":..}.
@@ -1257,6 +1577,21 @@ Frames (Variant A):
1257
1577
  that reports anything else fails the run
1258
1578
  (EMULATION_NOT_APPLIED) instead of being measured as if.
1259
1579
 
1580
+ Network (every mode; applied to the page once it is ready, before any action):
1581
+ --throttle <profile> Emulate a slow network on the page (CDP
1582
+ Network.emulateNetworkConditions). <profile> is
1583
+ slow-3g (2000 ms, 400/400 kbit/s), fast-3g (563 ms,
1584
+ 1475/675 kbit/s), or latency=<ms>,down=<kbps>,up=<kbps>.
1585
+ It persists across reloads of the page, so a
1586
+ captureTimeline {"reload":true} loads throttled.
1587
+ --no-cache Disable the HTTP cache too (Network.setCacheDisabled):
1588
+ a warm cache would let a "slow" reload paint at once.
1589
+ What was applied is stamped as "network" on every
1590
+ captureTimeline result, each capture-matrix cell, and
1591
+ the relay info line; CDP has no getter, so the stamp
1592
+ says what Chromium ACCEPTED, and a refused command
1593
+ fails the run rather than measuring unthrottled.
1594
+
1260
1595
  Capture matrix (its own mode):
1261
1596
  --capture-matrix <dir> Run the plan once per --viewport \xD7 --dpr \xD7 --color-scheme
1262
1597
  combination, each a fresh browser context, and store
@@ -1340,6 +1675,9 @@ Examples:
1340
1675
  --exec 'executeElementAction {"id":"open","request":{"action":"click"}}' \\
1341
1676
  --exec 'getControlSnapshot {}'
1342
1677
 
1678
+ # A candidate in its real slot, its slow-network load timeline, then restored
1679
+ 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 {}'
1680
+
1343
1681
  # Capture matrix: 2 breakpoints x 2 schemes x 2 DPRs = 8 frame-and-snapshot pairs
1344
1682
  ui-bridge-inject --url http://127.0.0.1:3000/ --capture-matrix ./matrix \\
1345
1683
  --viewport 390x844,1280x720 --color-scheme light,dark --dpr 1,2
@@ -1350,12 +1688,6 @@ Examples:
1350
1688
  ui-bridge-inject --url https://qontinui.io/admin \\
1351
1689
  --storage-state auth.json --exec 'getControlSnapshot {}'
1352
1690
  `;
1353
- var InjectCliArgError = class extends Error {
1354
- constructor(message) {
1355
- super(message);
1356
- this.name = "InjectCliArgError";
1357
- }
1358
- };
1359
1691
  function parseExecValue(raw) {
1360
1692
  const trimmed = raw.trim();
1361
1693
  if (trimmed.length === 0) {
@@ -1439,6 +1771,8 @@ function parseArgs(argv) {
1439
1771
  screenshot: null,
1440
1772
  captureMatrix: null,
1441
1773
  storageState: null,
1774
+ throttle: null,
1775
+ noCache: false,
1442
1776
  launchArgs: [],
1443
1777
  execActions: [],
1444
1778
  execStdin: false,
@@ -1618,6 +1952,17 @@ function parseArgs(argv) {
1618
1952
  args.screenshot = raw;
1619
1953
  break;
1620
1954
  }
1955
+ case "--throttle": {
1956
+ const raw = (0, cli_args_exports.consumeValue)("--throttle", argv[++i], mkError);
1957
+ if (raw === null)
1958
+ throw new InjectCliArgError("--throttle expects a profile (got <missing>)");
1959
+ if (args.throttle !== null) throw new InjectCliArgError("--throttle given twice");
1960
+ args.throttle = parseThrottle(raw);
1961
+ break;
1962
+ }
1963
+ case "--no-cache":
1964
+ args.noCache = true;
1965
+ break;
1621
1966
  case "--capture-matrix": {
1622
1967
  const raw = (0, cli_args_exports.consumeValue)("--capture-matrix", argv[++i], mkError);
1623
1968
  if (raw === null || raw.length === 0) {
@@ -1811,7 +2156,7 @@ var CLI_WAIT_ACTIONS = ["waitForSelector", "sleep"];
1811
2156
  var WAIT_SELECTOR_STATES = ["attached", "detached", "visible", "hidden"];
1812
2157
  var DEFAULT_WAIT_SELECTOR_TIMEOUT_MS = 1e4;
1813
2158
  var MAX_SLEEP_MS = 6e5;
1814
- function asRecord(payload, action) {
2159
+ function asRecord2(payload, action) {
1815
2160
  if (payload === void 0 || payload === null) return {};
1816
2161
  if (typeof payload !== "object" || Array.isArray(payload)) {
1817
2162
  throw new InjectCliArgError(`${action} payload must be a JSON object`);
@@ -1819,7 +2164,7 @@ function asRecord(payload, action) {
1819
2164
  return payload;
1820
2165
  }
1821
2166
  function parseWaitForSelectorPayload(payload) {
1822
- const obj = asRecord(payload, "waitForSelector");
2167
+ const obj = asRecord2(payload, "waitForSelector");
1823
2168
  const selector = obj["selector"];
1824
2169
  if (typeof selector !== "string" || selector.trim().length === 0) {
1825
2170
  throw new InjectCliArgError(`waitForSelector payload requires a non-empty 'selector' string`);
@@ -1847,7 +2192,7 @@ function parseWaitForSelectorPayload(payload) {
1847
2192
  return { selector: selector.trim(), timeoutMs, state };
1848
2193
  }
1849
2194
  function parseSleepPayload(payload) {
1850
- const obj = asRecord(payload, "sleep");
2195
+ const obj = asRecord2(payload, "sleep");
1851
2196
  const raw = obj["ms"];
1852
2197
  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0 || raw > MAX_SLEEP_MS) {
1853
2198
  throw new InjectCliArgError(
@@ -1860,12 +2205,13 @@ function validateWaitActions(actions) {
1860
2205
  for (const { action, payload } of actions) {
1861
2206
  if (action === "waitForSelector") parseWaitForSelectorPayload(payload);
1862
2207
  else if (action === "sleep") parseSleepPayload(payload);
2208
+ else if (action === CAPTURE_TIMELINE_ACTION) parseCaptureTimelinePayload(payload);
1863
2209
  }
1864
2210
  }
1865
2211
  function registerWaitActions(registrar) {
1866
2212
  registrar.register("sleep", async (params) => {
1867
2213
  const { ms } = parseSleepPayload(params);
1868
- await new Promise((resolve3) => setTimeout(resolve3, ms));
2214
+ await new Promise((resolve4) => setTimeout(resolve4, ms));
1869
2215
  return { slept: ms };
1870
2216
  });
1871
2217
  registrar.register("waitForSelector", async (params, ctx) => {
@@ -1881,6 +2227,22 @@ function registerWaitActions(registrar) {
1881
2227
  return { waited: true, selector, state, elapsedMs: Date.now() - startedAt };
1882
2228
  });
1883
2229
  }
2230
+ var APPLY_NETWORK_ACTION = "__inject_cli_apply_network";
2231
+ function registerNetworkEmulation(registrar, args) {
2232
+ registrar.register(APPLY_NETWORK_ACTION, async (_params, ctx) => {
2233
+ const page = ctx?.page;
2234
+ if (!page || typeof page.context !== "function") {
2235
+ throw new InjectCliArgError(
2236
+ `--throttle/--no-cache need the transport's page handle, which this context does not expose`
2237
+ );
2238
+ }
2239
+ return applyNetworkEmulation(page, args.throttle, args.noCache);
2240
+ });
2241
+ }
2242
+ async function applyNetwork(transport, args) {
2243
+ if (args.throttle === null && !args.noCache) return null;
2244
+ return await transport.dispatch(APPLY_NETWORK_ACTION);
2245
+ }
1884
2246
  function die(msg) {
1885
2247
  process.stderr.write(`${msg}
1886
2248
  `);
@@ -1891,13 +2253,13 @@ function log(quiet, msg) {
1891
2253
  `);
1892
2254
  }
1893
2255
  function readStdin() {
1894
- return new Promise((resolve3, reject) => {
2256
+ return new Promise((resolve4, reject) => {
1895
2257
  let data = "";
1896
2258
  process.stdin.setEncoding("utf8");
1897
2259
  process.stdin.on("data", (chunk) => {
1898
2260
  data += chunk;
1899
2261
  });
1900
- process.stdin.on("end", () => resolve3(data));
2262
+ process.stdin.on("end", () => resolve4(data));
1901
2263
  process.stdin.on("error", reject);
1902
2264
  });
1903
2265
  }
@@ -2056,11 +2418,15 @@ async function runExec(args, transport) {
2056
2418
  if (err instanceof InjectCliArgError) die(err.message);
2057
2419
  throw err;
2058
2420
  }
2421
+ let network = null;
2059
2422
  registerWaitActions(transport);
2060
2423
  registerFrameCapture(transport);
2424
+ registerNetworkEmulation(transport, args);
2425
+ registerTimelineCapture(transport, () => network);
2061
2426
  log(args.quiet, `[ui-bridge-inject] launching injected transport (exec mode)`);
2062
2427
  try {
2063
2428
  await transport.ready();
2429
+ network = await applyNetwork(transport, args);
2064
2430
  } catch (err) {
2065
2431
  const msg = err instanceof Error ? err.message : String(err);
2066
2432
  process.stderr.write(`[ui-bridge-inject] ready failed: ${msg}
@@ -2069,6 +2435,9 @@ async function runExec(args, transport) {
2069
2435
  });
2070
2436
  process.exit(1);
2071
2437
  }
2438
+ if (network) {
2439
+ log(args.quiet, `[ui-bridge-inject] network emulation applied: ${JSON.stringify(network)}`);
2440
+ }
2072
2441
  const screenshot = args.screenshot;
2073
2442
  let anyError;
2074
2443
  try {
@@ -2100,12 +2469,16 @@ async function runMatrixCell(args, cell, plan, dir) {
2100
2469
  kind: "injected",
2101
2470
  options: buildCellTransportOptions(args, cell)
2102
2471
  });
2472
+ let network = null;
2103
2473
  registerWaitActions(transport);
2104
2474
  registerFrameCapture(transport);
2475
+ registerNetworkEmulation(transport, args);
2476
+ registerTimelineCapture(transport, () => network, cellDir);
2105
2477
  log(args.quiet, `[ui-bridge-inject] capture matrix: cell ${id}`);
2106
2478
  try {
2107
2479
  ensurePrivateDir(cellDir);
2108
2480
  await transport.ready();
2481
+ network = await applyNetwork(transport, args);
2109
2482
  } catch (err) {
2110
2483
  await transport.close().catch(() => {
2111
2484
  });
@@ -2148,7 +2521,8 @@ async function runMatrixCell(args, cell, plan, dir) {
2148
2521
  requested: cell,
2149
2522
  status: anyError ? "incomplete" : "captured",
2150
2523
  results: manifestPath(dir, resultsPath),
2151
- pairs
2524
+ pairs,
2525
+ network
2152
2526
  };
2153
2527
  } catch (err) {
2154
2528
  const e = thrownError(err);
@@ -2265,8 +2639,11 @@ async function runRelay(args, transport) {
2265
2639
  `[ui-bridge-inject] launching injected transport (relay mode, ${args.headed ? "headed" : "headless"})`
2266
2640
  );
2267
2641
  log(args.quiet, `[ui-bridge-inject] url: ${args.url} relay: ${args.relay}`);
2642
+ registerNetworkEmulation(transport, args);
2643
+ let network = null;
2268
2644
  try {
2269
2645
  await transport.ready();
2646
+ network = await applyNetwork(transport, args);
2270
2647
  } catch (err) {
2271
2648
  const msg = err instanceof Error ? err.message : String(err);
2272
2649
  process.stderr.write(`[ui-bridge-inject] ready failed: ${msg}
@@ -2280,7 +2657,8 @@ async function runRelay(args, transport) {
2280
2657
  `${JSON.stringify({
2281
2658
  tabId: info.tabId,
2282
2659
  uiBridgeRegistered: info.uiBridgeRegistered,
2283
- url: args.url
2660
+ url: args.url,
2661
+ network
2284
2662
  })}
2285
2663
  `
2286
2664
  );
@@ -2317,6 +2695,7 @@ if (isMain) {
2317
2695
  });
2318
2696
  }
2319
2697
 
2698
+ exports.APPLY_NETWORK_ACTION = APPLY_NETWORK_ACTION;
2320
2699
  exports.CAPTURE_FRAME_ACTION = CAPTURE_FRAME_ACTION;
2321
2700
  exports.CLI_WAIT_ACTIONS = CLI_WAIT_ACTIONS;
2322
2701
  exports.DEFAULT_WAIT_SELECTOR_TIMEOUT_MS = DEFAULT_WAIT_SELECTOR_TIMEOUT_MS;
@@ -2342,6 +2721,7 @@ exports.parseSleepPayload = parseSleepPayload;
2342
2721
  exports.parseViewport = parseViewport;
2343
2722
  exports.parseWaitForSelectorPayload = parseWaitForSelectorPayload;
2344
2723
  exports.registerFrameCapture = registerFrameCapture;
2724
+ exports.registerNetworkEmulation = registerNetworkEmulation;
2345
2725
  exports.registerWaitActions = registerWaitActions;
2346
2726
  exports.resolveAuthToken = resolveAuthToken;
2347
2727
  exports.selectMode = selectMode;