@qontinui/ui-bridge-wrapper 0.6.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
 
@@ -344,6 +354,8 @@ var HeadedTransport = class extends HeadlessTransport {
344
354
  };
345
355
  var require2 = createRequire(import.meta.url);
346
356
  var cachedBundle = null;
357
+ var DIGEST_MAX_ELEMENTS = 10;
358
+ var DIGEST_TIMEOUT_MS = 5e3;
347
359
  function loadInjectedBundle() {
348
360
  if (cachedBundle !== null) return cachedBundle;
349
361
  let bundlePath;
@@ -470,14 +482,66 @@ var InjectedTransport = class extends HeadlessTransport {
470
482
  }
471
483
  if (state.settledByTimeout && !state.expectSatisfied) {
472
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" : ""}` : "";
473
493
  throw new WrapperTransportError(
474
494
  "INJECTED_EXPECT_SELECTOR_UNMET",
475
- 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.`,
476
- { retryable: true }
495
+ `${baseMessage}${summary}`,
496
+ {
497
+ retryable: true,
498
+ details: { registeredElements: digest, elementCount: state.elementCount }
499
+ }
477
500
  );
478
501
  }
479
502
  }
480
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
+ }
481
545
  async buildContext() {
482
546
  if (!this.tab) {
483
547
  throw new WrapperTransportError(