@qontinui/ui-bridge-wrapper 0.5.0 → 0.7.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.
package/dist/index.js CHANGED
@@ -6,6 +6,13 @@ var WrapperTransportError = class extends Error {
6
6
  code;
7
7
  retryable;
8
8
  cause;
9
+ /**
10
+ * Optional structured diagnostic payload (error-code-specific shape) so
11
+ * programmatic callers can branch on data instead of parsing the message —
12
+ * e.g. `INJECTED_EXPECT_SELECTOR_UNMET` attaches
13
+ * `{ registeredElements, elementCount }`.
14
+ */
15
+ details;
9
16
  constructor(code, message, options = {}) {
10
17
  super(message);
11
18
  this.name = "WrapperTransportError";
@@ -14,6 +21,9 @@ var WrapperTransportError = class extends Error {
14
21
  if (options.cause !== void 0) {
15
22
  this.cause = options.cause;
16
23
  }
24
+ if (options.details !== void 0) {
25
+ this.details = options.details;
26
+ }
17
27
  }
18
28
  };
19
29
 
@@ -249,6 +259,7 @@ Underlying import error: ${cause}`
249
259
  );
250
260
  }
251
261
  const initScripts = await this.buildInitScripts();
262
+ const relayAuth = this.relayAuth();
252
263
  let tab;
253
264
  try {
254
265
  tab = await launchHeadlessTab({
@@ -262,7 +273,9 @@ Underlying import error: ${cause}`
262
273
  forwardConsole: this.options.forwardConsole,
263
274
  initScripts: initScripts.length > 0 ? initScripts : void 0,
264
275
  launchArgs: this.options.launchArgs && this.options.launchArgs.length > 0 ? this.options.launchArgs : void 0,
265
- storageStatePath: this.options.storageStatePath
276
+ storageStatePath: this.options.storageStatePath,
277
+ ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
278
+ ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {}
266
279
  });
267
280
  } catch (err) {
268
281
  const cause = err instanceof Error ? err.message : String(err);
@@ -294,6 +307,15 @@ Underlying launch error: ${cause}`
294
307
  async buildInitScripts() {
295
308
  return [];
296
309
  }
310
+ /**
311
+ * Subclass hook: credentials for the launcher's Node-side relay registration
312
+ * poll (`<uiBridgeBase>/tabs`). Default: none (anonymous poll — correct for an
313
+ * ungated relay). Injected mode overrides this with the `--auth-token` bearer
314
+ * and the `--registration-metadata` userId.
315
+ */
316
+ relayAuth() {
317
+ return {};
318
+ }
297
319
  /**
298
320
  * Subclass hook: run after launch + navigation, before `ready()` resolves.
299
321
  * Default: no-op. Injected mode overrides it to await the in-page runtime.
@@ -332,6 +354,8 @@ var HeadedTransport = class extends HeadlessTransport {
332
354
  };
333
355
  var require2 = createRequire(import.meta.url);
334
356
  var cachedBundle = null;
357
+ var DIGEST_MAX_ELEMENTS = 10;
358
+ var DIGEST_TIMEOUT_MS = 5e3;
335
359
  function loadInjectedBundle() {
336
360
  if (cachedBundle !== null) return cachedBundle;
337
361
  let bundlePath;
@@ -387,8 +411,8 @@ var InjectedTransport = class extends HeadlessTransport {
387
411
  cfg.registrationMetadata = this.injected.registrationMetadata;
388
412
  if (this.injected.appId) cfg.appId = this.injected.appId;
389
413
  if (this.injected.appName) cfg.appName = this.injected.appName;
390
- if (this.injected.tabId) cfg.tabId = this.injected.tabId;
391
414
  }
415
+ if (this.injected.tabId) cfg.tabId = this.injected.tabId;
392
416
  if (this.injected.settleQuietMs !== void 0)
393
417
  cfg.settleQuietMs = this.injected.settleQuietMs;
394
418
  if (this.injected.settleTimeoutMs !== void 0)
@@ -397,6 +421,18 @@ var InjectedTransport = class extends HeadlessTransport {
397
421
  cfg.expectSelector = this.injected.expectSelector;
398
422
  return Object.keys(cfg).length > 0 ? cfg : null;
399
423
  }
424
+ /**
425
+ * The relay credentials the Node-side registration poll needs. Same bearer the
426
+ * page-side client gets via `__uiBridgeInjectedConfig.authToken`; without it
427
+ * the poll against a gated relay 401s and the CLI reports `tabId: null` on a
428
+ * launch that actually registered.
429
+ */
430
+ relayAuth() {
431
+ return {
432
+ ...this.injected.authToken ? { authToken: this.injected.authToken } : {},
433
+ ...this.injected.registrationMetadata?.userId ? { callerUserId: this.injected.registrationMetadata.userId } : {}
434
+ };
435
+ }
400
436
  async buildInitScripts() {
401
437
  const scripts = [];
402
438
  const cfg = this.injectedConfig();
@@ -446,14 +482,66 @@ var InjectedTransport = class extends HeadlessTransport {
446
482
  }
447
483
  if (state.settledByTimeout && !state.expectSatisfied) {
448
484
  const sel = this.injected.expectSelector;
485
+ 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.`;
486
+ const digest = await this.registeredElementDigest(page);
487
+ if (digest === null) {
488
+ throw new WrapperTransportError("INJECTED_EXPECT_SELECTOR_UNMET", baseMessage, {
489
+ retryable: true
490
+ });
491
+ }
492
+ const summary = digest.length > 0 ? ` Registered: ${digest.map((el) => el.role ? `${el.id} (${el.role})` : el.id).join(", ")}${state.elementCount > digest.length ? ", \u2026" : ""}` : "";
449
493
  throw new WrapperTransportError(
450
494
  "INJECTED_EXPECT_SELECTOR_UNMET",
451
- 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.`,
452
- { retryable: true }
495
+ `${baseMessage}${summary}`,
496
+ {
497
+ retryable: true,
498
+ details: { registeredElements: digest, elementCount: state.elementCount }
499
+ }
453
500
  );
454
501
  }
455
502
  }
456
503
  }
504
+ /**
505
+ * Best-effort digest of the first {@link DIGEST_MAX_ELEMENTS} registered
506
+ * interactive elements, read through the in-page dispatcher's
507
+ * `getControlSnapshot` action (the snapshot's per-element projection is
508
+ * already redaction-safe — we never read raw DOM labels here). Returns
509
+ * `null` on ANY failure or timeout: this feeds error diagnostics only, and a
510
+ * broken page realm must never mask the error being reported.
511
+ */
512
+ async registeredElementDigest(page) {
513
+ let timer;
514
+ try {
515
+ const snapshotPromise = page.evaluate(
516
+ () => window.__uiBridgeInjected.execute("getControlSnapshot", { skipSettle: true })
517
+ );
518
+ const snapshot = await Promise.race([
519
+ snapshotPromise,
520
+ new Promise((_, reject) => {
521
+ timer = setTimeout(() => reject(new Error("digest fetch timed out")), DIGEST_TIMEOUT_MS);
522
+ })
523
+ ]);
524
+ if (!snapshot || typeof snapshot !== "object") return null;
525
+ const elements = snapshot.elements;
526
+ if (!Array.isArray(elements)) return null;
527
+ const digest = [];
528
+ for (const el of elements.slice(0, DIGEST_MAX_ELEMENTS)) {
529
+ if (!el || typeof el !== "object") continue;
530
+ const e = el;
531
+ if (typeof e.id !== "string") continue;
532
+ digest.push({
533
+ id: e.id,
534
+ ...typeof e.role === "string" ? { role: e.role } : {},
535
+ ...typeof e.label === "string" ? { label: e.label } : {}
536
+ });
537
+ }
538
+ return digest;
539
+ } catch {
540
+ return null;
541
+ } finally {
542
+ if (timer !== void 0) clearTimeout(timer);
543
+ }
544
+ }
457
545
  async buildContext() {
458
546
  if (!this.tab) {
459
547
  throw new WrapperTransportError(