@qontinui/ui-bridge-wrapper 0.6.0 → 0.7.1

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.
@@ -4,13 +4,55 @@
4
4
  var url = require('url');
5
5
  var module$1 = require('module');
6
6
  var fs = require('fs');
7
+ var ui_bridge_cli_args_star = require('@qontinui/ui-bridge-cli-args');
7
8
 
8
9
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
10
+ function _interopNamespace(e) {
11
+ if (e && e.__esModule) return e;
12
+ var n = Object.create(null);
13
+ if (e) {
14
+ Object.keys(e).forEach(function (k) {
15
+ if (k !== 'default') {
16
+ var d = Object.getOwnPropertyDescriptor(e, k);
17
+ Object.defineProperty(n, k, d.get ? d : {
18
+ enumerable: true,
19
+ get: function () { return e[k]; }
20
+ });
21
+ }
22
+ });
23
+ }
24
+ n.default = e;
25
+ return Object.freeze(n);
26
+ }
27
+
28
+ var ui_bridge_cli_args_star__namespace = /*#__PURE__*/_interopNamespace(ui_bridge_cli_args_star);
29
+
30
+ var __defProp = Object.defineProperty;
31
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
32
+ var __getOwnPropNames = Object.getOwnPropertyNames;
33
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
34
+ var __copyProps = (to, from, except, desc) => {
35
+ if (from && typeof from === "object" || typeof from === "function") {
36
+ for (let key of __getOwnPropNames(from))
37
+ if (!__hasOwnProp.call(to, key) && key !== except)
38
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
39
+ }
40
+ return to;
41
+ };
42
+ var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget);
43
+
9
44
  // src/types.ts
10
45
  var WrapperTransportError = class extends Error {
11
46
  code;
12
47
  retryable;
13
48
  cause;
49
+ /**
50
+ * Optional structured diagnostic payload (error-code-specific shape) so
51
+ * programmatic callers can branch on data instead of parsing the message —
52
+ * e.g. `INJECTED_EXPECT_SELECTOR_UNMET` attaches
53
+ * `{ registeredElements, elementCount }`.
54
+ */
55
+ details;
14
56
  constructor(code, message, options = {}) {
15
57
  super(message);
16
58
  this.name = "WrapperTransportError";
@@ -19,6 +61,9 @@ var WrapperTransportError = class extends Error {
19
61
  if (options.cause !== void 0) {
20
62
  this.cause = options.cause;
21
63
  }
64
+ if (options.details !== void 0) {
65
+ this.details = options.details;
66
+ }
22
67
  }
23
68
  };
24
69
 
@@ -349,6 +394,8 @@ var HeadedTransport = class extends HeadlessTransport {
349
394
  };
350
395
  var require2 = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('inject-cli.cjs', document.baseURI).href)));
351
396
  var cachedBundle = null;
397
+ var DIGEST_MAX_ELEMENTS = 10;
398
+ var DIGEST_TIMEOUT_MS = 5e3;
352
399
  function loadInjectedBundle() {
353
400
  if (cachedBundle !== null) return cachedBundle;
354
401
  let bundlePath;
@@ -475,14 +522,66 @@ var InjectedTransport = class extends HeadlessTransport {
475
522
  }
476
523
  if (state.settledByTimeout && !state.expectSatisfied) {
477
524
  const sel = this.injected.expectSelector;
525
+ const baseMessage = sel ? `The injected runtime settled at its cap without the expected control (selector '${sel}') appearing \u2014 ${state.elementCount} element(s) were registered, but none matched. The control may mount slower than the settle cap (raise options.settleTimeoutMs), the selector may be wrong, or the inject failed. Treat as BLOCKED/UNVERIFIED, not a clean page.` : `The injected runtime settled at its cap with an empty registry (0 elements). The page never rendered interactive content within the settle cap, or the inject failed. Raise options.settleTimeoutMs for a slow page; otherwise treat as BLOCKED/UNVERIFIED.`;
526
+ const digest = await this.registeredElementDigest(page);
527
+ if (digest === null) {
528
+ throw new WrapperTransportError("INJECTED_EXPECT_SELECTOR_UNMET", baseMessage, {
529
+ retryable: true
530
+ });
531
+ }
532
+ const summary = digest.length > 0 ? ` Registered: ${digest.map((el) => el.role ? `${el.id} (${el.role})` : el.id).join(", ")}${state.elementCount > digest.length ? ", \u2026" : ""}` : "";
478
533
  throw new WrapperTransportError(
479
534
  "INJECTED_EXPECT_SELECTOR_UNMET",
480
- sel ? `The injected runtime settled at its cap without the expected control (selector '${sel}') appearing \u2014 ${state.elementCount} element(s) were registered, but none matched. The control may mount slower than the settle cap (raise options.settleTimeoutMs), the selector may be wrong, or the inject failed. Treat as BLOCKED/UNVERIFIED, not a clean page.` : `The injected runtime settled at its cap with an empty registry (0 elements). The page never rendered interactive content within the settle cap, or the inject failed. Raise options.settleTimeoutMs for a slow page; otherwise treat as BLOCKED/UNVERIFIED.`,
481
- { retryable: true }
535
+ `${baseMessage}${summary}`,
536
+ {
537
+ retryable: true,
538
+ details: { registeredElements: digest, elementCount: state.elementCount }
539
+ }
482
540
  );
483
541
  }
484
542
  }
485
543
  }
544
+ /**
545
+ * Best-effort digest of the first {@link DIGEST_MAX_ELEMENTS} registered
546
+ * interactive elements, read through the in-page dispatcher's
547
+ * `getControlSnapshot` action (the snapshot's per-element projection is
548
+ * already redaction-safe — we never read raw DOM labels here). Returns
549
+ * `null` on ANY failure or timeout: this feeds error diagnostics only, and a
550
+ * broken page realm must never mask the error being reported.
551
+ */
552
+ async registeredElementDigest(page) {
553
+ let timer;
554
+ try {
555
+ const snapshotPromise = page.evaluate(
556
+ () => window.__uiBridgeInjected.execute("getControlSnapshot", { skipSettle: true })
557
+ );
558
+ const snapshot = await Promise.race([
559
+ snapshotPromise,
560
+ new Promise((_, reject) => {
561
+ timer = setTimeout(() => reject(new Error("digest fetch timed out")), DIGEST_TIMEOUT_MS);
562
+ })
563
+ ]);
564
+ if (!snapshot || typeof snapshot !== "object") return null;
565
+ const elements = snapshot.elements;
566
+ if (!Array.isArray(elements)) return null;
567
+ const digest = [];
568
+ for (const el of elements.slice(0, DIGEST_MAX_ELEMENTS)) {
569
+ if (!el || typeof el !== "object") continue;
570
+ const e = el;
571
+ if (typeof e.id !== "string") continue;
572
+ digest.push({
573
+ id: e.id,
574
+ ...typeof e.role === "string" ? { role: e.role } : {},
575
+ ...typeof e.label === "string" ? { label: e.label } : {}
576
+ });
577
+ }
578
+ return digest;
579
+ } catch {
580
+ return null;
581
+ } finally {
582
+ if (timer !== void 0) clearTimeout(timer);
583
+ }
584
+ }
486
585
  async buildContext() {
487
586
  if (!this.tab) {
488
587
  throw new WrapperTransportError(
@@ -751,16 +850,8 @@ function createTransport(config) {
751
850
  }
752
851
 
753
852
  // src/cli-args.ts
754
- function isFlagShaped(value) {
755
- return value.startsWith("--");
756
- }
757
- function consumeValue(flag, raw, error) {
758
- if (raw === void 0) return null;
759
- if (isFlagShaped(raw)) {
760
- throw error(`${flag} expects a value but got the flag '${raw}' \u2014 did you omit ${flag}'s argument?`);
761
- }
762
- return raw;
763
- }
853
+ var cli_args_exports = {};
854
+ __reExport(cli_args_exports, ui_bridge_cli_args_star__namespace);
764
855
 
765
856
  // src/inject-cli.ts
766
857
  var USAGE = `ui-bridge-inject \u2014 drive UI Bridge's injected transport against a UI-Bridge-free page
@@ -910,25 +1001,25 @@ function parseArgs(argv) {
910
1001
  // String value-flags: guard each consumed value against the flag-shaped
911
1002
  // swallow (`--url --headed` must error, not capture `--headed` as the url).
912
1003
  case "--url":
913
- args.url = consumeValue("--url", argv[++i], mkError) ?? "";
1004
+ args.url = (0, cli_args_exports.consumeValue)("--url", argv[++i], mkError) ?? "";
914
1005
  break;
915
1006
  case "--relay":
916
- args.relay = consumeValue("--relay", argv[++i], mkError);
1007
+ args.relay = (0, cli_args_exports.consumeValue)("--relay", argv[++i], mkError);
917
1008
  break;
918
1009
  case "--auth-token":
919
- args.authToken = consumeValue("--auth-token", argv[++i], mkError);
1010
+ args.authToken = (0, cli_args_exports.consumeValue)("--auth-token", argv[++i], mkError);
920
1011
  break;
921
1012
  case "--app-id":
922
- args.appId = consumeValue("--app-id", argv[++i], mkError);
1013
+ args.appId = (0, cli_args_exports.consumeValue)("--app-id", argv[++i], mkError);
923
1014
  break;
924
1015
  case "--app-name":
925
- args.appName = consumeValue("--app-name", argv[++i], mkError);
1016
+ args.appName = (0, cli_args_exports.consumeValue)("--app-name", argv[++i], mkError);
926
1017
  break;
927
1018
  case "--tab-id":
928
- args.tabId = consumeValue("--tab-id", argv[++i], mkError);
1019
+ args.tabId = (0, cli_args_exports.consumeValue)("--tab-id", argv[++i], mkError);
929
1020
  break;
930
1021
  case "--storage-state": {
931
- const raw = consumeValue("--storage-state", argv[++i], mkError);
1022
+ const raw = (0, cli_args_exports.consumeValue)("--storage-state", argv[++i], mkError);
932
1023
  if (raw === null || raw.length === 0) {
933
1024
  throw new InjectCliArgError(
934
1025
  `--storage-state expects a path to a storageState JSON file (got <missing>)`
@@ -946,7 +1037,7 @@ function parseArgs(argv) {
946
1037
  break;
947
1038
  }
948
1039
  case "--exec": {
949
- const raw = consumeValue("--exec", argv[++i], mkError);
1040
+ const raw = (0, cli_args_exports.consumeValue)("--exec", argv[++i], mkError);
950
1041
  if (raw === null) {
951
1042
  throw new InjectCliArgError(`--exec expects '<action> <json-payload>' (got <missing>)`);
952
1043
  }
@@ -954,7 +1045,7 @@ function parseArgs(argv) {
954
1045
  break;
955
1046
  }
956
1047
  case "--registration-metadata": {
957
- const raw = consumeValue("--registration-metadata", argv[++i], mkError);
1048
+ const raw = (0, cli_args_exports.consumeValue)("--registration-metadata", argv[++i], mkError);
958
1049
  if (raw === null) {
959
1050
  throw new InjectCliArgError(
960
1051
  `--registration-metadata expects JSON {"userId","sessionId"} (got <missing>)`
@@ -977,7 +1068,7 @@ function parseArgs(argv) {
977
1068
  break;
978
1069
  }
979
1070
  case "--ready-timeout": {
980
- const raw = consumeValue("--ready-timeout", argv[++i], mkError);
1071
+ const raw = (0, cli_args_exports.consumeValue)("--ready-timeout", argv[++i], mkError);
981
1072
  const n = raw === null ? NaN : Number.parseInt(raw, 10);
982
1073
  if (!Number.isFinite(n) || n <= 0) {
983
1074
  throw new InjectCliArgError(
@@ -991,7 +1082,7 @@ function parseArgs(argv) {
991
1082
  args.waitForSettle = false;
992
1083
  break;
993
1084
  case "--settle-quiet": {
994
- const raw = consumeValue("--settle-quiet", argv[++i], mkError);
1085
+ const raw = (0, cli_args_exports.consumeValue)("--settle-quiet", argv[++i], mkError);
995
1086
  const n = raw === null ? NaN : Number.parseInt(raw, 10);
996
1087
  if (!Number.isFinite(n) || n < 0) {
997
1088
  throw new InjectCliArgError(
@@ -1002,7 +1093,7 @@ function parseArgs(argv) {
1002
1093
  break;
1003
1094
  }
1004
1095
  case "--settle-timeout": {
1005
- const raw = consumeValue("--settle-timeout", argv[++i], mkError);
1096
+ const raw = (0, cli_args_exports.consumeValue)("--settle-timeout", argv[++i], mkError);
1006
1097
  const n = raw === null ? NaN : Number.parseInt(raw, 10);
1007
1098
  if (!Number.isFinite(n) || n <= 0) {
1008
1099
  throw new InjectCliArgError(
@@ -1013,7 +1104,7 @@ function parseArgs(argv) {
1013
1104
  break;
1014
1105
  }
1015
1106
  case "--expect-selector": {
1016
- const raw = consumeValue("--expect-selector", argv[++i], mkError);
1107
+ const raw = (0, cli_args_exports.consumeValue)("--expect-selector", argv[++i], mkError);
1017
1108
  if (raw === null || raw.length === 0) {
1018
1109
  throw new InjectCliArgError(`--expect-selector expects a CSS selector (got <missing>)`);
1019
1110
  }
@@ -1021,7 +1112,7 @@ function parseArgs(argv) {
1021
1112
  break;
1022
1113
  }
1023
1114
  case "--viewport": {
1024
- const raw = consumeValue("--viewport", argv[++i], mkError);
1115
+ const raw = (0, cli_args_exports.consumeValue)("--viewport", argv[++i], mkError);
1025
1116
  const match = raw?.match(/^(\d+)x(\d+)$/);
1026
1117
  if (!match) {
1027
1118
  throw new InjectCliArgError(`--viewport expects WxH (got ${raw ?? "<missing>"})`);