@qontinui/ui-bridge-wrapper 0.12.0 → 0.15.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.
Files changed (49) hide show
  1. package/README.md +157 -8
  2. package/dist/capture-specs-cli.cjs +301 -53
  3. package/dist/capture-specs-cli.cjs.map +1 -1
  4. package/dist/capture-specs-cli.d.ts.map +1 -1
  5. package/dist/chunk-IKHDNIU4.js +478 -0
  6. package/dist/chunk-IKHDNIU4.js.map +1 -0
  7. package/dist/chunk-Z32CC665.cjs +488 -0
  8. package/dist/chunk-Z32CC665.cjs.map +1 -0
  9. package/dist/create-transport.d.ts.map +1 -1
  10. package/dist/frame-capture.d.ts +3 -28
  11. package/dist/frame-capture.d.ts.map +1 -1
  12. package/dist/frame-page.d.ts +35 -0
  13. package/dist/frame-page.d.ts.map +1 -0
  14. package/dist/index.cjs +145 -375
  15. package/dist/index.cjs.map +1 -1
  16. package/dist/index.d.ts +1 -0
  17. package/dist/index.d.ts.map +1 -1
  18. package/dist/index.js +90 -351
  19. package/dist/index.js.map +1 -1
  20. package/dist/inject-cli.cjs +407 -134
  21. package/dist/inject-cli.cjs.map +1 -1
  22. package/dist/inject-cli.d.ts +1 -1
  23. package/dist/inject-cli.d.ts.map +1 -1
  24. package/dist/live/index.cjs +40 -0
  25. package/dist/live/index.cjs.map +1 -0
  26. package/dist/live/index.d.ts +32 -0
  27. package/dist/live/index.d.ts.map +1 -0
  28. package/dist/live/index.js +3 -0
  29. package/dist/live/index.js.map +1 -0
  30. package/dist/login-web-cli.cjs +312 -61
  31. package/dist/login-web-cli.cjs.map +1 -1
  32. package/dist/login-web-cli.d.ts.map +1 -1
  33. package/dist/network-throttle.d.ts +5 -0
  34. package/dist/network-throttle.d.ts.map +1 -1
  35. package/dist/screenshot-capture.d.ts +82 -0
  36. package/dist/screenshot-capture.d.ts.map +1 -0
  37. package/dist/timeline-capture.d.ts +74 -10
  38. package/dist/timeline-capture.d.ts.map +1 -1
  39. package/dist/transports/headless.d.ts +46 -1
  40. package/dist/transports/headless.d.ts.map +1 -1
  41. package/dist/transports/injected.d.ts +8 -0
  42. package/dist/transports/injected.d.ts.map +1 -1
  43. package/dist/transports/live.d.ts +27 -1
  44. package/dist/transports/live.d.ts.map +1 -1
  45. package/dist/types.d.ts +3 -1
  46. package/dist/types.d.ts.map +1 -1
  47. package/package.json +11 -8
  48. package/dist/cli-args.d.ts +0 -13
  49. package/dist/cli-args.d.ts.map +0 -1
package/dist/index.js CHANGED
@@ -1,165 +1,9 @@
1
+ import { BaseTransport, WrapperTransportError, LiveSessionTransport } from './chunk-IKHDNIU4.js';
2
+ export { BaseTransport, HandlerRegistry, LiveSessionTransport, SCREENSHOT_ACTION, SCREENSHOT_CAPABILITY, SCREENSHOT_TIMEOUT_MS, WrapperTransportError, captureScreenshotReply, registerScreenshotCapture } from './chunk-IKHDNIU4.js';
1
3
  import { createRequire } from 'module';
2
4
  import { readFileSync } from 'fs';
3
5
  import { randomBytes } from 'crypto';
4
-
5
- // src/types.ts
6
- var WrapperTransportError = class extends Error {
7
- code;
8
- retryable;
9
- cause;
10
- /**
11
- * Optional structured diagnostic payload (error-code-specific shape) so
12
- * programmatic callers can branch on data instead of parsing the message —
13
- * e.g. `INJECTED_EXPECT_SELECTOR_UNMET` attaches
14
- * `{ registeredElements, elementCount }`.
15
- */
16
- details;
17
- constructor(code, message, options = {}) {
18
- super(message);
19
- this.name = "WrapperTransportError";
20
- this.code = code;
21
- this.retryable = options.retryable ?? false;
22
- if (options.cause !== void 0) {
23
- this.cause = options.cause;
24
- }
25
- if (options.details !== void 0) {
26
- this.details = options.details;
27
- }
28
- }
29
- };
30
-
31
- // src/handler-registry.ts
32
- var HandlerRegistry = class {
33
- handlers = /* @__PURE__ */ new Map();
34
- /**
35
- * Register (or replace) a handler for `actionId`. Replacement is explicit
36
- * rather than throwing because live reloading / hot module scenarios need
37
- * to update handlers without tearing the whole transport down.
38
- */
39
- register(actionId, fn) {
40
- this.handlers.set(actionId, fn);
41
- }
42
- /** Remove a handler. Returns `true` if a handler was removed. */
43
- unregister(actionId) {
44
- return this.handlers.delete(actionId);
45
- }
46
- /** All registered action ids. Stable iteration order (insertion order). */
47
- list() {
48
- return Array.from(this.handlers.keys());
49
- }
50
- /** Check whether a handler is registered for `actionId`. */
51
- has(actionId) {
52
- return this.handlers.has(actionId);
53
- }
54
- /**
55
- * Invoke the handler registered under `actionId`.
56
- *
57
- * Throws `WrapperTransportError("NO_HANDLER")` if no handler is registered.
58
- * Propagates handler errors wrapped as `WrapperTransportError("HANDLER_ERROR")`
59
- * so callers can uniformly check `err.code`.
60
- */
61
- async dispatch(actionId, params, ctx) {
62
- const handler = this.handlers.get(actionId);
63
- if (!handler) {
64
- throw new WrapperTransportError(
65
- "NO_HANDLER",
66
- `No handler registered for action '${actionId}'`
67
- );
68
- }
69
- try {
70
- const result = await handler(params, ctx);
71
- return result;
72
- } catch (err) {
73
- if (err instanceof WrapperTransportError) throw err;
74
- const message = err instanceof Error ? err.message : String(err);
75
- throw new WrapperTransportError("HANDLER_ERROR", message, { cause: err });
76
- }
77
- }
78
- };
79
-
80
- // src/base-transport.ts
81
- var BaseTransport = class {
82
- _status = "idle";
83
- listeners = /* @__PURE__ */ new Set();
84
- registry;
85
- readyPromise = null;
86
- constructor(registry) {
87
- this.registry = registry ?? new HandlerRegistry();
88
- }
89
- get status() {
90
- return this._status;
91
- }
92
- /** Expose the underlying registry so wrappers can register handlers. */
93
- get handlerRegistry() {
94
- return this.registry;
95
- }
96
- /** Convenience: register a handler on the transport's registry. */
97
- register(actionId, fn) {
98
- this.registry.register(actionId, fn);
99
- }
100
- /**
101
- * Idempotent async setup. First call runs `onReady()`; subsequent calls
102
- * share the same promise until it settles, after which further calls
103
- * are no-ops if `status === 'ready'`, or re-run setup if it errored.
104
- */
105
- async ready() {
106
- if (this._status === "ready") return;
107
- if (this._status === "closed") {
108
- throw new WrapperTransportError("TRANSPORT_CLOSED", `Transport '${this.kind}' is closed`);
109
- }
110
- if (this.readyPromise) return this.readyPromise;
111
- this.setStatus("connecting");
112
- this.readyPromise = this.onReady().then(() => {
113
- this.setStatus("ready");
114
- }).catch((err) => {
115
- this.setStatus("error");
116
- this.readyPromise = null;
117
- throw err;
118
- });
119
- return this.readyPromise;
120
- }
121
- /** Default dispatch — waits for ready, builds ctx, delegates to registry. */
122
- async dispatch(actionId, params) {
123
- await this.ready();
124
- const ctx = await this.buildContext(actionId, params);
125
- return this.registry.dispatch(actionId, params, ctx);
126
- }
127
- async close() {
128
- if (this._status === "closed") return;
129
- try {
130
- await this.onClose();
131
- } finally {
132
- this.setStatus("closed");
133
- this.listeners.clear();
134
- this.readyPromise = null;
135
- }
136
- }
137
- onStatusChange(listener) {
138
- this.listeners.add(listener);
139
- return () => {
140
- this.listeners.delete(listener);
141
- };
142
- }
143
- /** Update status and notify listeners. Safe to call from subclasses. */
144
- setStatus(next) {
145
- if (this._status === next) return;
146
- this._status = next;
147
- for (const l of this.listeners) {
148
- try {
149
- l(next);
150
- } catch {
151
- }
152
- }
153
- }
154
- /**
155
- * Subclass hook: build the context object passed to handlers. Default is
156
- * `undefined` (api transport). Headless/headed override to provide the
157
- * Playwright `page`; live overrides to provide a response helper.
158
- */
159
- async buildContext(_actionId, _params) {
160
- return void 0;
161
- }
162
- };
6
+ import 'path';
163
7
 
164
8
  // src/transports/api.ts
165
9
  var ApiTransport = class extends BaseTransport {
@@ -234,9 +78,60 @@ var HeadlessTransport = class extends BaseTransport {
234
78
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
235
79
  forwardConsole: typeof raw["forwardConsole"] === "boolean" ? raw["forwardConsole"] : void 0,
236
80
  launchArgs: Array.isArray(raw["launchArgs"]) && raw["launchArgs"].every((a) => typeof a === "string") ? raw["launchArgs"] : void 0,
237
- storageStatePath: typeof raw["storageStatePath"] === "string" ? raw["storageStatePath"] : void 0
81
+ storageStatePath: typeof raw["storageStatePath"] === "string" ? raw["storageStatePath"] : void 0,
82
+ ...this.parseContextOptions(raw)
238
83
  };
239
84
  }
85
+ /**
86
+ * `recordHar`, `recordVideo`, `serviceWorkers` and `initRouter`. Unlike the display
87
+ * options above, a malformed value is REFUSED rather than dropped: dropping
88
+ * `recordHar` would leave a caller waiting for an archive that is never
89
+ * written, and dropping `initRouter` would let requests it meant to answer
90
+ * reach the network.
91
+ */
92
+ parseContextOptions(raw) {
93
+ const out = {};
94
+ const invalid = (what) => new WrapperTransportError("INVALID_CONFIG", `Transport kind '${this.kind}': ${what}`);
95
+ const har = raw["recordHar"];
96
+ if (har !== void 0) {
97
+ if (typeof har !== "object" || har === null || typeof har.path !== "string" || har.path.length === 0) {
98
+ throw invalid("options.recordHar must be an object with a non-empty string `path`");
99
+ }
100
+ out.recordHar = har;
101
+ }
102
+ const video = raw["recordVideo"];
103
+ if (video !== void 0) {
104
+ if (typeof video !== "object" || video === null || typeof video.dir !== "string" || video.dir.length === 0) {
105
+ throw invalid("options.recordVideo must be an object with a non-empty string `dir`");
106
+ }
107
+ const size = video.size;
108
+ if (size !== void 0) {
109
+ const positiveInt = (n) => typeof n === "number" && Number.isInteger(n) && n > 0;
110
+ const s = size;
111
+ if (typeof size !== "object" || s === null || !positiveInt(s.width) || !positiveInt(s.height)) {
112
+ throw invalid(
113
+ "options.recordVideo.size must be { width, height } with positive integer sides"
114
+ );
115
+ }
116
+ }
117
+ out.recordVideo = video;
118
+ }
119
+ const sw = raw["serviceWorkers"];
120
+ if (sw !== void 0) {
121
+ if (sw !== "allow" && sw !== "block") {
122
+ throw invalid(`options.serviceWorkers must be 'allow' or 'block' (got ${String(sw)})`);
123
+ }
124
+ out.serviceWorkers = sw;
125
+ }
126
+ const router = raw["initRouter"];
127
+ if (router !== void 0) {
128
+ if (typeof router !== "function") {
129
+ throw invalid("options.initRouter must be a function (context) => void | Promise<void>");
130
+ }
131
+ out.initRouter = router;
132
+ }
133
+ return out;
134
+ }
240
135
  async onReady() {
241
136
  let launchHeadlessTab;
242
137
  const headlessSpecifier = "@qontinui/ui-bridge-headless";
@@ -264,6 +159,13 @@ Underlying import error: ${cause}`
264
159
  const initScripts = await this.buildInitScripts();
265
160
  const relayAuth = this.relayAuth();
266
161
  const pinnedTabId = this.pinnedTabId();
162
+ const { recordHar, recordVideo, serviceWorkers, initRouter: callerRouter } = this.options;
163
+ const contextOptionsRequested = recordHar !== void 0 || recordVideo !== void 0 || serviceWorkers === "block" || callerRouter !== void 0;
164
+ let routerCalled = false;
165
+ const initRouter = contextOptionsRequested || serviceWorkers !== void 0 ? async (context) => {
166
+ routerCalled = true;
167
+ if (callerRouter) await callerRouter(context);
168
+ } : void 0;
267
169
  let tab;
268
170
  try {
269
171
  tab = await launchHeadlessTab({
@@ -282,7 +184,11 @@ Underlying import error: ${cause}`
282
184
  storageStatePath: this.options.storageStatePath,
283
185
  ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
284
186
  ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
285
- ...pinnedTabId ? { pinnedTabId } : {}
187
+ ...pinnedTabId ? { pinnedTabId } : {},
188
+ ...recordHar !== void 0 ? { recordHar } : {},
189
+ ...recordVideo !== void 0 ? { recordVideo } : {},
190
+ ...serviceWorkers !== void 0 ? { serviceWorkers } : {},
191
+ ...initRouter ? { initRouter } : {}
286
192
  });
287
193
  } catch (err) {
288
194
  const cause = err instanceof Error ? err.message : String(err);
@@ -304,6 +210,24 @@ Underlying launch error: ${cause}`
304
210
  tabId: tab.tabId,
305
211
  close: tab.close
306
212
  };
213
+ if (contextOptionsRequested && !routerCalled) {
214
+ await this.onClose().catch(() => {
215
+ });
216
+ throw new WrapperTransportError(
217
+ "CONTEXT_OPTIONS_NOT_APPLIED",
218
+ `The installed '@qontinui/ui-bridge-headless' peer launched the tab without calling initRouter, so it predates the recordHar / recordVideo / serviceWorkers / initRouter passthrough (0.8.0, ui-bridge#381) and ignored them: no HAR or video would be written and no route installed. Upgrade it to 0.8.0 or later.`,
219
+ {
220
+ details: {
221
+ requested: {
222
+ recordHar: recordHar !== void 0,
223
+ recordVideo: recordVideo !== void 0,
224
+ serviceWorkers: serviceWorkers ?? null,
225
+ initRouter: callerRouter !== void 0
226
+ }
227
+ }
228
+ }
229
+ );
230
+ }
307
231
  await this.verifyEmulation(tab.page);
308
232
  await this.afterLaunch(tab.page);
309
233
  }
@@ -650,6 +574,7 @@ var InjectedTransport = class extends HeadlessTransport {
650
574
  execute,
651
575
  find: (criteria) => execute("find", criteria ?? {}),
652
576
  act: (id, request) => execute("executeElementAction", { id, request }),
577
+ element: (id) => execute("getElement", { id }),
653
578
  snapshot: (options) => execute("getControlSnapshot", options ?? {}),
654
579
  assert: (spec) => execute("aiAssert", spec)
655
580
  };
@@ -661,192 +586,6 @@ function isRegistrationMetadata(value) {
661
586
  return typeof v.userId === "string" && typeof v.sessionId === "string";
662
587
  }
663
588
 
664
- // src/transports/live.ts
665
- var LiveSessionTransport = class extends BaseTransport {
666
- kind = "live";
667
- url;
668
- appId;
669
- appName;
670
- opts;
671
- wsCtor;
672
- ws = null;
673
- ackResolvers = null;
674
- constructor(config, registry, injected) {
675
- super(registry);
676
- if (!config.runnerUrl) {
677
- throw new WrapperTransportError("INVALID_CONFIG", `Transport kind 'live' requires runnerUrl`);
678
- }
679
- this.url = config.runnerUrl;
680
- this.appId = config.appId;
681
- this.appName = config.appName;
682
- this.opts = config.options ?? {};
683
- const fromInjection = injected?.webSocketCtor;
684
- const fromGlobal = typeof globalThis.WebSocket === "function" ? globalThis.WebSocket : void 0;
685
- const resolved = fromInjection ?? fromGlobal;
686
- if (!resolved) {
687
- throw new WrapperTransportError(
688
- "NO_WEBSOCKET",
689
- `No WebSocket constructor available. Provide one via the second constructor arg or run in an environment with global WebSocket.`
690
- );
691
- }
692
- this.wsCtor = resolved;
693
- }
694
- async onReady() {
695
- const ws = new this.wsCtor(this.url);
696
- this.ws = ws;
697
- ws.addEventListener("message", (ev) => this.handleMessage(ev.data));
698
- ws.addEventListener("close", () => this.handleClose());
699
- ws.addEventListener("error", (ev) => this.handleError(ev));
700
- await new Promise((resolve, reject) => {
701
- const onOpen = () => {
702
- try {
703
- const frame = {
704
- type: "register",
705
- transport: "websocket",
706
- appId: this.appId,
707
- appName: this.appName,
708
- appType: this.opts.appType ?? "wrapper"
709
- };
710
- if (this.opts.framework !== void 0) frame.framework = this.opts.framework;
711
- if (this.opts.version !== void 0) frame.version = this.opts.version;
712
- if (this.opts.capabilities !== void 0) frame.capabilities = this.opts.capabilities;
713
- if (this.opts.origin !== void 0) frame.origin = this.opts.origin;
714
- if (this.opts.pageUrl !== void 0) frame.pageUrl = this.opts.pageUrl;
715
- ws.send(JSON.stringify(frame));
716
- } catch (err) {
717
- reject(err instanceof Error ? err : new Error(String(err)));
718
- return;
719
- }
720
- const timeoutMs = this.opts.handshakeTimeoutMs ?? 1e4;
721
- const timer = setTimeout(() => {
722
- this.ackResolvers = null;
723
- reject(
724
- new WrapperTransportError(
725
- "HANDSHAKE_TIMEOUT",
726
- `Did not receive register ack within ${timeoutMs}ms`
727
- )
728
- );
729
- }, timeoutMs);
730
- this.ackResolvers = { resolve, reject, timer };
731
- };
732
- ws.addEventListener("open", onOpen);
733
- });
734
- }
735
- async onClose() {
736
- const ws = this.ws;
737
- this.ws = null;
738
- if (this.ackResolvers) {
739
- clearTimeout(this.ackResolvers.timer);
740
- this.ackResolvers.reject(
741
- new WrapperTransportError("TRANSPORT_CLOSED", "Transport closed during handshake")
742
- );
743
- this.ackResolvers = null;
744
- }
745
- if (ws) {
746
- try {
747
- ws.close();
748
- } catch {
749
- }
750
- }
751
- }
752
- async buildContext() {
753
- return { kind: "live", commandId: null };
754
- }
755
- handleMessage(data) {
756
- let frame;
757
- try {
758
- const text = typeof data === "string" ? data : String(data);
759
- frame = JSON.parse(text);
760
- } catch {
761
- return;
762
- }
763
- switch (frame.type) {
764
- case "ack":
765
- case "registered": {
766
- const f = frame;
767
- if (!this.ackResolvers) return;
768
- clearTimeout(this.ackResolvers.timer);
769
- if (f.ok === false) {
770
- const err = new WrapperTransportError(
771
- f.error?.code ?? "REGISTER_FAILED",
772
- f.error?.message ?? "Runner refused registration"
773
- );
774
- this.ackResolvers.reject(err);
775
- } else {
776
- this.ackResolvers.resolve();
777
- }
778
- this.ackResolvers = null;
779
- return;
780
- }
781
- case "command": {
782
- const f = frame;
783
- void this.handleCommand(f);
784
- return;
785
- }
786
- default:
787
- return;
788
- }
789
- }
790
- async handleCommand(frame) {
791
- const ctx = { kind: "live", commandId: frame.commandId };
792
- let response;
793
- try {
794
- const result = await this.registry.dispatch(frame.action, frame.payload, ctx);
795
- response = {
796
- type: "response",
797
- commandId: frame.commandId,
798
- success: true,
799
- result
800
- };
801
- } catch (err) {
802
- const code = err instanceof WrapperTransportError ? err.code : "HANDLER_ERROR";
803
- const retryable = err instanceof WrapperTransportError ? err.retryable : false;
804
- const message = err instanceof Error ? err.message : String(err);
805
- response = {
806
- type: "response",
807
- commandId: frame.commandId,
808
- success: false,
809
- error: { code, message, retryable }
810
- };
811
- }
812
- try {
813
- this.ws?.send(JSON.stringify(response));
814
- } catch {
815
- }
816
- }
817
- handleClose() {
818
- if (this._status === "closed") return;
819
- this.setStatus("closed");
820
- if (this.ackResolvers) {
821
- clearTimeout(this.ackResolvers.timer);
822
- this.ackResolvers.reject(
823
- new WrapperTransportError("DISCONNECTED", "WebSocket closed before ack")
824
- );
825
- this.ackResolvers = null;
826
- }
827
- }
828
- handleError(ev) {
829
- if (this.ackResolvers) {
830
- clearTimeout(this.ackResolvers.timer);
831
- const message = this.extractErrorMessage(ev);
832
- this.ackResolvers.reject(
833
- new WrapperTransportError("WEBSOCKET_ERROR", message, { retryable: true })
834
- );
835
- this.ackResolvers = null;
836
- } else {
837
- this.setStatus("error");
838
- }
839
- }
840
- extractErrorMessage(ev) {
841
- if (ev && typeof ev === "object" && "message" in ev) {
842
- const m = ev.message;
843
- if (typeof m === "string") return m;
844
- }
845
- if (ev instanceof Error) return ev.message;
846
- return "WebSocket error";
847
- }
848
- };
849
-
850
589
  // src/create-transport.ts
851
590
  function createTransport(config) {
852
591
  switch (config.kind) {
@@ -871,7 +610,7 @@ function createTransport(config) {
871
610
  }
872
611
 
873
612
  // src/helpers/retry.ts
874
- var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
613
+ var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
875
614
  var defaultShouldRetry = (err) => {
876
615
  if (err instanceof WrapperTransportError) {
877
616
  return err.retryable;
@@ -1087,15 +826,15 @@ async function startDispatchServer(transport, port, logName) {
1087
826
  res.writeHead(404, { "Content-Type": "application/json" });
1088
827
  res.end(JSON.stringify({ success: false, error: "not found" }));
1089
828
  });
1090
- await new Promise((resolve, reject) => {
829
+ await new Promise((resolve2, reject) => {
1091
830
  server.once("error", reject);
1092
831
  server.listen(port, "127.0.0.1", () => {
1093
832
  server.removeListener("error", reject);
1094
- resolve();
833
+ resolve2();
1095
834
  });
1096
835
  });
1097
836
  }
1098
837
 
1099
- export { ApiTransport, BaseTransport, HandlerRegistry, HeadedTransport, HeadlessTransport, InjectedTransport, LiveSessionTransport, WrapperTransportError, createTransport, emitManifestOnly, paramSchemaOf, runWrapperEntrypoint, withAuthRefresh, withRetry };
838
+ export { ApiTransport, HeadedTransport, HeadlessTransport, InjectedTransport, createTransport, emitManifestOnly, paramSchemaOf, runWrapperEntrypoint, withAuthRefresh, withRetry };
1100
839
  //# sourceMappingURL=index.js.map
1101
840
  //# sourceMappingURL=index.js.map