@qontinui/ui-bridge-wrapper 0.4.1 → 0.5.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.
@@ -224,36 +224,63 @@ var HeadlessTransport = class extends BaseTransport {
224
224
  uiBridgeBase: typeof raw["uiBridgeBase"] === "string" ? raw["uiBridgeBase"] : void 0,
225
225
  waitForUiBridgeMs: typeof raw["waitForUiBridgeMs"] === "number" ? raw["waitForUiBridgeMs"] : void 0,
226
226
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
227
- forwardConsole: typeof raw["forwardConsole"] === "boolean" ? raw["forwardConsole"] : void 0
227
+ forwardConsole: typeof raw["forwardConsole"] === "boolean" ? raw["forwardConsole"] : void 0,
228
+ launchArgs: Array.isArray(raw["launchArgs"]) && raw["launchArgs"].every((a) => typeof a === "string") ? raw["launchArgs"] : void 0,
229
+ storageStatePath: typeof raw["storageStatePath"] === "string" ? raw["storageStatePath"] : void 0
228
230
  };
229
231
  }
230
232
  async onReady() {
231
233
  let launchHeadlessTab;
234
+ const headlessSpecifier = "@qontinui/ui-bridge-headless";
232
235
  try {
233
- ({ launchHeadlessTab } = await import('@qontinui/ui-bridge-headless'));
236
+ const mod = await import(headlessSpecifier);
237
+ ({ launchHeadlessTab } = mod);
234
238
  } catch (err) {
235
239
  const cause = err instanceof Error ? err.message : String(err);
236
- throw new WrapperTransportError(
237
- "INVALID_CONFIG",
238
- `Transport kind '${this.kind}' needs the optional '@qontinui/ui-bridge-headless' peer, which is not installed. Install it and the Chromium browser:
240
+ const code = err?.code;
241
+ if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
242
+ throw new WrapperTransportError(
243
+ "INVALID_CONFIG",
244
+ `Transport kind '${this.kind}' needs the optional '@qontinui/ui-bridge-headless' peer, which is not installed. Install it and the Chromium browser:
239
245
  npm i @qontinui/ui-bridge-headless && npx playwright install chromium
240
246
  (bare \`npx @qontinui/ui-bridge-wrapper \u2026\` does NOT install peers \u2014 pass each peer with \`-p\`, e.g.
241
247
  npx -y -p @qontinui/ui-bridge-wrapper -p @qontinui/ui-bridge -p @qontinui/ui-bridge-headless -p playwright ui-bridge-login-web \u2026)
242
248
  Underlying import error: ${cause}`
249
+ );
250
+ }
251
+ throw new WrapperTransportError(
252
+ "INVALID_CONFIG",
253
+ `'@qontinui/ui-bridge-headless' is installed but failed to load \u2014 this is a broken install (missing transitive dependency or version skew), not a missing peer. Try reinstalling it. Underlying error: ${cause}`
243
254
  );
244
255
  }
245
256
  const initScripts = await this.buildInitScripts();
246
- const tab = await launchHeadlessTab({
247
- url: this.options.targetUrl,
248
- headless: this.headless,
249
- uiBridgeBase: this.options.uiBridgeBase,
250
- waitForUiBridgeMs: this.options.waitForUiBridgeMs,
251
- viewportWidth: this.options.viewportWidth,
252
- viewportHeight: this.options.viewportHeight,
253
- userAgent: this.options.userAgent,
254
- forwardConsole: this.options.forwardConsole,
255
- initScripts: initScripts.length > 0 ? initScripts : void 0
256
- });
257
+ let tab;
258
+ try {
259
+ tab = await launchHeadlessTab({
260
+ url: this.options.targetUrl,
261
+ headless: this.headless,
262
+ uiBridgeBase: this.options.uiBridgeBase,
263
+ waitForUiBridgeMs: this.options.waitForUiBridgeMs,
264
+ viewportWidth: this.options.viewportWidth,
265
+ viewportHeight: this.options.viewportHeight,
266
+ userAgent: this.options.userAgent,
267
+ forwardConsole: this.options.forwardConsole,
268
+ initScripts: initScripts.length > 0 ? initScripts : void 0,
269
+ launchArgs: this.options.launchArgs && this.options.launchArgs.length > 0 ? this.options.launchArgs : void 0,
270
+ storageStatePath: this.options.storageStatePath
271
+ });
272
+ } catch (err) {
273
+ const cause = err instanceof Error ? err.message : String(err);
274
+ if (/Executable doesn't exist|browserType\.launch/i.test(cause)) {
275
+ throw new WrapperTransportError(
276
+ "INVALID_CONFIG",
277
+ `Playwright's Chromium browser is not installed (the '@qontinui/ui-bridge-headless' peer itself loaded fine). Run:
278
+ npx playwright install chromium
279
+ Underlying launch error: ${cause}`
280
+ );
281
+ }
282
+ throw err;
283
+ }
257
284
  this.tab = {
258
285
  browser: tab.browser,
259
286
  context: tab.context,
@@ -737,6 +764,12 @@ Exec (Variant A \u2014 one-shot; presence of any --exec/--exec-stdin selects thi
737
764
  {"action":"...","payload":{...}}
738
765
 
739
766
  Optional:
767
+ --storage-state <path> Seed the browser context from a Playwright storageState
768
+ JSON file (cookies + localStorage) produced by
769
+ 'ui-bridge-login-web --storage-state-out <path>'. This
770
+ carries a saved authenticated session past a login wall,
771
+ so you can drive a login-walled page (e.g. an /admin
772
+ wizard) WITHOUT re-driving the hosted-UI login each run.
740
773
  --headed Launch with a visible window (default: headless)
741
774
  --ready-timeout <ms> Max wait for the injected runtime ready/settle gate (default 30000)
742
775
  --no-settle Gate ready on the runtime being live only, NOT on the DOM
@@ -751,6 +784,13 @@ Optional:
751
784
  before --settle-timeout, ready() fails with a BLOCKED error
752
785
  instead of returning a control-less page.
753
786
  --viewport <WxH> Viewport size, e.g. 1280x720
787
+ --launch-arg <arg> Extra Chromium command-line argument (repeatable),
788
+ passed through to chromium.launch({ args }).
789
+ NOTE: when --url is https and --relay resolves to a
790
+ loopback host, the LNA-disable flags
791
+ (--disable-features=LocalNetworkAccessChecks,...) are
792
+ auto-appended \u2014 Chromium otherwise blocks the
793
+ https-page \u2192 loopback-relay fetch (Local Network Access).
754
794
  --quiet Suppress human-readable logs (JSON results still print)
755
795
  --help, -h Print this help and exit
756
796
 
@@ -766,6 +806,12 @@ Examples:
766
806
  # Variant A: find a control and act on it
767
807
  ui-bridge-inject --url https://example.com/login \\
768
808
  --exec 'find {"text":"Sign in"}'
809
+
810
+ # Reuse a saved login: drive a login-walled page with a captured auth artifact
811
+ ui-bridge-login-web --url "https://qontinui.io/login?next=%2Fadmin" \\
812
+ --success /admin --storage-state-out auth.json
813
+ ui-bridge-inject --url https://qontinui.io/admin \\
814
+ --storage-state auth.json --exec 'getControlSnapshot {}'
769
815
  `;
770
816
  var InjectCliArgError = class extends Error {
771
817
  constructor(message) {
@@ -813,6 +859,8 @@ function parseArgs(argv) {
813
859
  tabId: null,
814
860
  viewportWidth: null,
815
861
  viewportHeight: null,
862
+ storageState: null,
863
+ launchArgs: [],
816
864
  execActions: [],
817
865
  execStdin: false,
818
866
  quiet: false,
@@ -855,17 +903,35 @@ function parseArgs(argv) {
855
903
  case "--tab-id":
856
904
  args.tabId = consumeValue("--tab-id", argv[++i], mkError);
857
905
  break;
858
- case "--exec": {
906
+ case "--storage-state": {
907
+ const raw = consumeValue("--storage-state", argv[++i], mkError);
908
+ if (raw === null || raw.length === 0) {
909
+ throw new InjectCliArgError(
910
+ `--storage-state expects a path to a storageState JSON file (got <missing>)`
911
+ );
912
+ }
913
+ args.storageState = raw;
914
+ break;
915
+ }
916
+ case "--launch-arg": {
859
917
  const raw = argv[++i];
860
- if (raw === void 0) {
918
+ if (raw === void 0 || raw.length === 0) {
919
+ throw new InjectCliArgError(`--launch-arg expects a Chromium argument (got <missing>)`);
920
+ }
921
+ args.launchArgs.push(raw);
922
+ break;
923
+ }
924
+ case "--exec": {
925
+ const raw = consumeValue("--exec", argv[++i], mkError);
926
+ if (raw === null) {
861
927
  throw new InjectCliArgError(`--exec expects '<action> <json-payload>' (got <missing>)`);
862
928
  }
863
929
  args.execActions.push(parseExecValue(raw));
864
930
  break;
865
931
  }
866
932
  case "--registration-metadata": {
867
- const raw = argv[++i];
868
- if (raw === void 0) {
933
+ const raw = consumeValue("--registration-metadata", argv[++i], mkError);
934
+ if (raw === null) {
869
935
  throw new InjectCliArgError(
870
936
  `--registration-metadata expects JSON {"userId","sessionId"} (got <missing>)`
871
937
  );
@@ -887,8 +953,8 @@ function parseArgs(argv) {
887
953
  break;
888
954
  }
889
955
  case "--ready-timeout": {
890
- const raw = argv[++i];
891
- const n = raw === void 0 ? NaN : Number.parseInt(raw, 10);
956
+ const raw = consumeValue("--ready-timeout", argv[++i], mkError);
957
+ const n = raw === null ? NaN : Number.parseInt(raw, 10);
892
958
  if (!Number.isFinite(n) || n <= 0) {
893
959
  throw new InjectCliArgError(
894
960
  `--ready-timeout expects a positive integer (got ${raw ?? "<missing>"})`
@@ -901,8 +967,8 @@ function parseArgs(argv) {
901
967
  args.waitForSettle = false;
902
968
  break;
903
969
  case "--settle-quiet": {
904
- const raw = argv[++i];
905
- const n = raw === void 0 ? NaN : Number.parseInt(raw, 10);
970
+ const raw = consumeValue("--settle-quiet", argv[++i], mkError);
971
+ const n = raw === null ? NaN : Number.parseInt(raw, 10);
906
972
  if (!Number.isFinite(n) || n < 0) {
907
973
  throw new InjectCliArgError(
908
974
  `--settle-quiet expects a non-negative integer (got ${raw ?? "<missing>"})`
@@ -912,8 +978,8 @@ function parseArgs(argv) {
912
978
  break;
913
979
  }
914
980
  case "--settle-timeout": {
915
- const raw = argv[++i];
916
- const n = raw === void 0 ? NaN : Number.parseInt(raw, 10);
981
+ const raw = consumeValue("--settle-timeout", argv[++i], mkError);
982
+ const n = raw === null ? NaN : Number.parseInt(raw, 10);
917
983
  if (!Number.isFinite(n) || n <= 0) {
918
984
  throw new InjectCliArgError(
919
985
  `--settle-timeout expects a positive integer (got ${raw ?? "<missing>"})`
@@ -923,15 +989,15 @@ function parseArgs(argv) {
923
989
  break;
924
990
  }
925
991
  case "--expect-selector": {
926
- const raw = argv[++i];
927
- if (raw === void 0 || raw.length === 0) {
992
+ const raw = consumeValue("--expect-selector", argv[++i], mkError);
993
+ if (raw === null || raw.length === 0) {
928
994
  throw new InjectCliArgError(`--expect-selector expects a CSS selector (got <missing>)`);
929
995
  }
930
996
  args.expectSelector = raw;
931
997
  break;
932
998
  }
933
999
  case "--viewport": {
934
- const raw = argv[++i];
1000
+ const raw = consumeValue("--viewport", argv[++i], mkError);
935
1001
  const match = raw?.match(/^(\d+)x(\d+)$/);
936
1002
  if (!match) {
937
1003
  throw new InjectCliArgError(`--viewport expects WxH (got ${raw ?? "<missing>"})`);
@@ -967,9 +1033,48 @@ function validateArgs(args) {
967
1033
  function selectMode(args) {
968
1034
  return args.execActions.length > 0 || args.execStdin ? "exec" : "relay";
969
1035
  }
1036
+ var LNA_DISABLE_FEATURES = [
1037
+ "LocalNetworkAccessChecks",
1038
+ "PrivateNetworkAccessSendPreflights",
1039
+ "PrivateNetworkAccessRespectPreflightResults"
1040
+ ];
1041
+ function isLoopbackHost(hostname) {
1042
+ const h = hostname.toLowerCase();
1043
+ return h === "localhost" || h.endsWith(".localhost") || h.startsWith("127.") || h === "::1" || h === "[::1]";
1044
+ }
1045
+ function buildLaunchArgs(args) {
1046
+ const launchArgs = [...args.launchArgs];
1047
+ let lnaAutoAppended = false;
1048
+ let relayIsLoopback = false;
1049
+ if (args.relay) {
1050
+ try {
1051
+ relayIsLoopback = isLoopbackHost(new URL(args.relay).hostname);
1052
+ } catch {
1053
+ relayIsLoopback = false;
1054
+ }
1055
+ }
1056
+ if (/^https:\/\//i.test(args.url) && relayIsLoopback) {
1057
+ const prefix = "--disable-features=";
1058
+ const existingIdx = launchArgs.findIndex((a) => a.startsWith(prefix));
1059
+ if (existingIdx === -1) {
1060
+ launchArgs.push(`${prefix}${LNA_DISABLE_FEATURES.join(",")}`);
1061
+ lnaAutoAppended = true;
1062
+ } else {
1063
+ const existing = launchArgs[existingIdx].slice(prefix.length).split(",").filter(Boolean);
1064
+ const missing = LNA_DISABLE_FEATURES.filter((f) => !existing.includes(f));
1065
+ if (missing.length > 0) {
1066
+ launchArgs[existingIdx] = `${prefix}${[...existing, ...missing].join(",")}`;
1067
+ lnaAutoAppended = true;
1068
+ }
1069
+ }
1070
+ }
1071
+ return { launchArgs, lnaAutoAppended };
1072
+ }
970
1073
  function buildTransportOptions(args) {
971
1074
  const options = { targetUrl: args.url };
972
1075
  if (args.relay) options.uiBridgeBase = args.relay;
1076
+ const { launchArgs } = buildLaunchArgs(args);
1077
+ if (launchArgs.length > 0) options.launchArgs = launchArgs;
973
1078
  if (args.authToken) options.authToken = args.authToken;
974
1079
  if (args.registrationMetadata) options.registrationMetadata = args.registrationMetadata;
975
1080
  if (args.headed) options.headed = true;
@@ -983,6 +1088,7 @@ function buildTransportOptions(args) {
983
1088
  if (args.tabId) options.tabId = args.tabId;
984
1089
  if (args.viewportWidth !== null) options.viewportWidth = args.viewportWidth;
985
1090
  if (args.viewportHeight !== null) options.viewportHeight = args.viewportHeight;
1091
+ if (args.storageState) options.storageStatePath = args.storageState;
986
1092
  return options;
987
1093
  }
988
1094
  function die(msg) {
@@ -1044,6 +1150,13 @@ ${USAGE}`);
1044
1150
  process.exit(0);
1045
1151
  }
1046
1152
  const mode = selectMode(args);
1153
+ const { launchArgs, lnaAutoAppended } = buildLaunchArgs(args);
1154
+ if (lnaAutoAppended) {
1155
+ log(
1156
+ args.quiet,
1157
+ `[ui-bridge-inject] https page + loopback relay detected \u2014 auto-appending Chromium LNA-disable flags so the page can fetch the relay: --disable-features=${LNA_DISABLE_FEATURES.join(",")} (effective launch args: ${JSON.stringify(launchArgs)})`
1158
+ );
1159
+ }
1047
1160
  const transport = createTransport({ kind: "injected", options: buildTransportOptions(args) });
1048
1161
  transport.register("__inject_cli_info", (_p, ctx) => {
1049
1162
  const c = ctx;
@@ -1175,8 +1288,11 @@ if (isMain) {
1175
1288
  }
1176
1289
 
1177
1290
  exports.InjectCliArgError = InjectCliArgError;
1291
+ exports.LNA_DISABLE_FEATURES = LNA_DISABLE_FEATURES;
1178
1292
  exports.USAGE = USAGE;
1293
+ exports.buildLaunchArgs = buildLaunchArgs;
1179
1294
  exports.buildTransportOptions = buildTransportOptions;
1295
+ exports.isLoopbackHost = isLoopbackHost;
1180
1296
  exports.parseArgs = parseArgs;
1181
1297
  exports.selectMode = selectMode;
1182
1298
  exports.validateArgs = validateArgs;