@qontinui/ui-bridge-wrapper 0.7.2 → 0.9.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/README.md CHANGED
@@ -62,7 +62,7 @@ or a global/dev install:
62
62
 
63
63
  | Bin | What it does |
64
64
  | --- | --- |
65
- | `ui-bridge-inject` | Drive the injected transport against a UI-Bridge-free page (exec one-shot actions, or register as a relay tab). |
65
+ | `ui-bridge-inject` | Drive the injected transport against a UI-Bridge-free page (exec one-shot actions, register as a relay tab, or capture frame-and-snapshot pairs — one, or a viewport × DPR × colour-scheme matrix). |
66
66
  | `ui-bridge-login-web` | Automated web login via the injected transport — drives the full Cognito OAuth redirect chain in one headless tab. Optionally asserts on-page text (`--expect-text`) and screenshots the authed landing (`--screenshot`/`--scroll-to`). Prints one JSON result line; exit 0 = login confirmed AND all expected text present. |
67
67
  | `ui-bridge-capture-specs` | Log in (same flow) then `goto` + snapshot a set of authed pages, writing one `<slug>.snapshot.json` per page. |
68
68
 
@@ -129,6 +129,56 @@ ui-bridge-login-web \
129
129
  ui-bridge-capture-specs --out ./spec-capture
130
130
  ```
131
131
 
132
+ ### Frames, device pixel ratio and the capture matrix (`ui-bridge-inject`)
133
+
134
+ `--screenshot <path>` captures a PNG frame **in lockstep** with every
135
+ `getControlSnapshot` action: snapshot, frame, snapshot again, retried until the
136
+ two snapshots agree on every element's box. The action's output line gains a
137
+ `frame` object whose every field is read off the page or the PNG at capture time
138
+ — `width`/`height`, `devicePixelRatio`, `cssViewport`, `colorScheme`,
139
+ `capturedAt` and `lockstep: {verified, attempts, changedElements}` — never
140
+ copied from the flags. `{n}` in the path's file name becomes the action's
141
+ 1-based position and is required when a run takes more than one snapshot (a
142
+ `{n}` in a directory name is refused). A frame that cannot be produced leaves
143
+ `"frame": null` plus `"frameError": {code, message}` (the snapshot still
144
+ stands) and the process exits 1.
145
+
146
+ A frame is **raw pixels** of the page: `data-bridge-redact` masks elements in
147
+ snapshots and over the relay, never in a screenshot, so a frame shows whatever
148
+ the page showed — including anything an authenticated session displays.
149
+ Directories created for frames (and the capture matrix's snapshots) are
150
+ `0700` and every file `0600`.
151
+
152
+ `--dpr <n>` and `--color-scheme <dark|light>` set the browser context's
153
+ `deviceScaleFactor` and `prefers-color-scheme`, and the page is checked after
154
+ launch: one that reports anything else fails with `EMULATION_NOT_APPLIED`
155
+ rather than being measured as if it had applied. (Chromium's
156
+ `--force-device-scale-factor` passed through `--launch-arg` does **not** reach
157
+ the page — Playwright's viewport emulation overrides it.) Needs
158
+ `@qontinui/ui-bridge-headless` with `deviceScaleFactor`/`colorScheme` support
159
+ (0.6.0 or later).
160
+
161
+ ```bash
162
+ # one frame at a Retina DPR in dark mode, paired with its snapshot
163
+ ui-bridge-inject --url http://127.0.0.1:3000/ --viewport 1280x720 --dpr 2 \
164
+ --color-scheme dark --screenshot ./frame.png --exec 'getControlSnapshot {}'
165
+
166
+ # every combination: 2 breakpoints x 2 schemes x 2 DPRs = 8 cells
167
+ ui-bridge-inject --url http://127.0.0.1:3000/ --capture-matrix ./matrix \
168
+ --viewport 390x844,1280x720 --color-scheme light,dark --dpr 1,2
169
+ ```
170
+
171
+ `--capture-matrix <dir>` runs the plan (`--exec`/`--exec-stdin`, default one
172
+ `getControlSnapshot {}`) once per combination in a fresh browser context and
173
+ writes `<dir>/<cell>/frame-<n>.png`, `snapshot-<n>.json` and `results.ndjson`,
174
+ plus `<dir>/matrix.json`: the URL, the producer and its version, the axes, the
175
+ plan and every cell's requested values, status (`captured` / `incomplete` /
176
+ `failed`) and pairs with their frame provenance. An axis left out stays at the
177
+ browser default and says so in the cell id (`390x844_dpr-default_dark`). The
178
+ directory must be empty or not exist yet: a non-empty one is refused before any
179
+ browser launches, and is never cleared. `--viewport` sides are at most 8192 CSS
180
+ pixels.
181
+
132
182
  #### Sourcing credentials from SSM (qontinui operators)
133
183
 
134
184
  The bins read credentials from env / flags only — they intentionally do **not**
@@ -0,0 +1,105 @@
1
+ /**
2
+ * The capture matrix: one page, captured at every combination of breakpoint ×
3
+ * colour scheme × device pixel ratio, each combination a fresh browser context,
4
+ * with every frame-and-snapshot pair stored beside its provenance.
5
+ *
6
+ * Plan 2026-10-13-image-generation-and-visual-judgment, Phase 9 item 4. The axes
7
+ * come from flags today; once that plan's Phase 14 lands, an image slot spec's
8
+ * `contexts {breakpoints, themes, dpr}` is the other source of the same three
9
+ * lists, and it feeds {@link expandMatrix} unchanged.
10
+ *
11
+ * This module is pure (axis expansion, cell ids, the manifest shape). Driving a
12
+ * browser per cell is the CLI's job (`inject-cli.ts`, `runMatrix`).
13
+ */
14
+ import type { FrameColorScheme, FrameError, FrameRecord } from './frame-capture.js';
15
+ /** A CSS-pixel viewport. */
16
+ export interface MatrixViewport {
17
+ width: number;
18
+ height: number;
19
+ }
20
+ /**
21
+ * One combination. A `null` axis value means "not set by the caller": the
22
+ * browser default applies (Playwright's 1280×720 viewport, DPR 1, no colour
23
+ * scheme override) and the frame's own provenance records what that was.
24
+ */
25
+ export interface MatrixCell {
26
+ viewport: MatrixViewport | null;
27
+ dpr: number | null;
28
+ colorScheme: FrameColorScheme | null;
29
+ }
30
+ /** The three axes. An empty axis contributes one `null` value (the default). */
31
+ export interface MatrixAxes {
32
+ viewports: MatrixViewport[];
33
+ dprs: number[];
34
+ colorSchemes: FrameColorScheme[];
35
+ }
36
+ /**
37
+ * Every combination of the axes, viewport-major, in the order each axis was
38
+ * given — so a run is reproducible and its cells read in a predictable order.
39
+ */
40
+ export declare function expandMatrix(axes: MatrixAxes): MatrixCell[];
41
+ /**
42
+ * A filesystem-safe, human-readable id for a cell — also its directory name.
43
+ * e.g. `390x844_dpr2_dark`; an unset axis reads `viewport-default`,
44
+ * `dpr-default` or `scheme-default`, so a default is never mistaken for a
45
+ * measured value.
46
+ */
47
+ export declare function cellId(cell: MatrixCell): string;
48
+ /** One stored frame-and-snapshot pair. Paths are relative to the manifest's directory. */
49
+ export interface MatrixPair {
50
+ /** The plan action's 1-based position (the `n` in `frame-<n>.png`). */
51
+ position: number;
52
+ /** The control snapshot file. */
53
+ snapshot: string;
54
+ /** The frame's provenance, its `path` made relative; `null` when no frame was produced. */
55
+ frame: FrameRecord | null;
56
+ frameError?: FrameError;
57
+ }
58
+ /** What happened to one cell. */
59
+ export type MatrixCellStatus =
60
+ /** Every action ran and every requested frame was produced. */
61
+ 'captured'
62
+ /** The page loaded, but an action failed or a frame could not be produced. */
63
+ | 'incomplete'
64
+ /** The cell never reached a drivable page (launch, emulation or ready failed). */
65
+ | 'failed';
66
+ export interface MatrixCellReport {
67
+ id: string;
68
+ /** What the caller asked for. The frames' own provenance says what was rendered. */
69
+ requested: MatrixCell;
70
+ status: MatrixCellStatus;
71
+ /** Why the cell failed outright (`status: 'failed'`). */
72
+ error?: {
73
+ code: string;
74
+ message: string;
75
+ };
76
+ /** Every action's output line, exactly as exec mode prints it (relative path). */
77
+ results: string | null;
78
+ pairs: MatrixPair[];
79
+ }
80
+ /** `<dir>/matrix.json`. */
81
+ export interface MatrixManifest {
82
+ kind: 'ui-bridge-capture-matrix';
83
+ /** Bumped on any incompatible change to this shape. */
84
+ schemaVersion: 1;
85
+ url: string;
86
+ producer: {
87
+ name: 'ui-bridge-inject';
88
+ package: string;
89
+ version: string | null;
90
+ };
91
+ startedAt: string;
92
+ finishedAt: string;
93
+ /** The axes as given; an empty list means that axis was left at the browser default. */
94
+ axes: MatrixAxes;
95
+ /** The per-cell plan, run in every cell. */
96
+ plan: {
97
+ position: number;
98
+ action: string;
99
+ payload: unknown;
100
+ }[];
101
+ cells: MatrixCellReport[];
102
+ }
103
+ /** A path relative to the manifest directory, with forward slashes on every OS. */
104
+ export declare function manifestPath(manifestDir: string, absPath: string): string;
105
+ //# sourceMappingURL=capture-matrix.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"capture-matrix.d.ts","sourceRoot":"","sources":["../src/capture-matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEpF,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC;AAED,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,YAAY,EAAE,gBAAgB,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,EAAE,CAc3D;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAK/C;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,iCAAiC;AACjC,MAAM,MAAM,gBAAgB;AAC1B,+DAA+D;AAC7D,UAAU;AACZ,8EAA8E;GAC5E,YAAY;AACd,kFAAkF;GAChF,QAAQ,CAAC;AAEb,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,oFAAoF;IACpF,SAAS,EAAE,UAAU,CAAC;IACtB,MAAM,EAAE,gBAAgB,CAAC;IACzB,yDAAyD;IACzD,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,kFAAkF;IAClF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,2BAA2B;AAC3B,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,0BAA0B,CAAC;IACjC,uDAAuD;IACvD,aAAa,EAAE,CAAC,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE;QAAE,IAAI,EAAE,kBAAkB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,IAAI,EAAE,UAAU,CAAC;IACjB,4CAA4C;IAC5C,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC/D,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE"}
@@ -4,6 +4,7 @@
4
4
  var fs = require('fs');
5
5
  var path = require('path');
6
6
  var module$1 = require('module');
7
+ var crypto = require('crypto');
7
8
  var ui_bridge_cli_args_star = require('@qontinui/ui-bridge-cli-args');
8
9
 
9
10
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -276,6 +277,8 @@ var HeadlessTransport = class extends BaseTransport {
276
277
  targetUrl,
277
278
  viewportWidth: typeof raw["viewportWidth"] === "number" ? raw["viewportWidth"] : void 0,
278
279
  viewportHeight: typeof raw["viewportHeight"] === "number" ? raw["viewportHeight"] : void 0,
280
+ deviceScaleFactor: typeof raw["deviceScaleFactor"] === "number" ? raw["deviceScaleFactor"] : void 0,
281
+ colorScheme: raw["colorScheme"] === "light" || raw["colorScheme"] === "dark" ? raw["colorScheme"] : void 0,
279
282
  uiBridgeBase: typeof raw["uiBridgeBase"] === "string" ? raw["uiBridgeBase"] : void 0,
280
283
  waitForUiBridgeMs: typeof raw["waitForUiBridgeMs"] === "number" ? raw["waitForUiBridgeMs"] : void 0,
281
284
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
@@ -310,6 +313,7 @@ Underlying import error: ${cause}`
310
313
  }
311
314
  const initScripts = await this.buildInitScripts();
312
315
  const relayAuth = this.relayAuth();
316
+ const pinnedTabId = this.pinnedTabId();
313
317
  let tab;
314
318
  try {
315
319
  tab = await launchHeadlessTab({
@@ -319,13 +323,16 @@ Underlying import error: ${cause}`
319
323
  waitForUiBridgeMs: this.options.waitForUiBridgeMs,
320
324
  viewportWidth: this.options.viewportWidth,
321
325
  viewportHeight: this.options.viewportHeight,
326
+ ...this.options.deviceScaleFactor !== void 0 ? { deviceScaleFactor: this.options.deviceScaleFactor } : {},
327
+ ...this.options.colorScheme !== void 0 ? { colorScheme: this.options.colorScheme } : {},
322
328
  userAgent: this.options.userAgent,
323
329
  forwardConsole: this.options.forwardConsole,
324
330
  initScripts: initScripts.length > 0 ? initScripts : void 0,
325
331
  launchArgs: this.options.launchArgs && this.options.launchArgs.length > 0 ? this.options.launchArgs : void 0,
326
332
  storageStatePath: this.options.storageStatePath,
327
333
  ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
328
- ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {}
334
+ ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
335
+ ...pinnedTabId ? { pinnedTabId } : {}
329
336
  });
330
337
  } catch (err) {
331
338
  const cause = err instanceof Error ? err.message : String(err);
@@ -347,8 +354,39 @@ Underlying launch error: ${cause}`
347
354
  tabId: tab.tabId,
348
355
  close: tab.close
349
356
  };
357
+ await this.verifyEmulation(tab.page);
350
358
  await this.afterLaunch(tab.page);
351
359
  }
360
+ /**
361
+ * Read back the requested device scale factor and colour scheme from the
362
+ * page itself, and refuse a launch whose page reports anything else.
363
+ */
364
+ async verifyEmulation(page) {
365
+ const wantDpr = this.options.deviceScaleFactor;
366
+ const wantScheme = this.options.colorScheme;
367
+ if (wantDpr === void 0 && wantScheme === void 0) return;
368
+ const seen = await page.evaluate(() => ({
369
+ dpr: window.devicePixelRatio,
370
+ dark: window.matchMedia("(prefers-color-scheme: dark)").matches
371
+ }));
372
+ const problems = [];
373
+ if (wantDpr !== void 0 && Math.abs(seen.dpr - wantDpr) > 1e-9) {
374
+ problems.push(`devicePixelRatio ${seen.dpr} (requested ${wantDpr})`);
375
+ }
376
+ if (wantScheme !== void 0 && seen.dark !== (wantScheme === "dark")) {
377
+ problems.push(
378
+ `prefers-color-scheme ${seen.dark ? "dark" : "light"} (requested ${wantScheme})`
379
+ );
380
+ }
381
+ if (problems.length === 0) return;
382
+ await this.onClose().catch(() => {
383
+ });
384
+ throw new WrapperTransportError(
385
+ "EMULATION_NOT_APPLIED",
386
+ `The launched page reports ${problems.join(" and ")}. The installed '@qontinui/ui-bridge-headless' peer most likely predates deviceScaleFactor/colorScheme support (added after 0.5.0) and ignored them; upgrade it. A page measured at an emulation it is not actually rendering at would be stamped with the wrong values.`,
387
+ { details: { requested: { deviceScaleFactor: wantDpr, colorScheme: wantScheme }, seen } }
388
+ );
389
+ }
352
390
  /**
353
391
  * Subclass hook: init-scripts to register on the browser context before the
354
392
  * first navigation (via `context.addInitScript`). Default: none. Injected
@@ -366,6 +404,13 @@ Underlying launch error: ${cause}`
366
404
  relayAuth() {
367
405
  return {};
368
406
  }
407
+ /**
408
+ * Subclass hook: the tab id this launch pinned, so the registration poll
409
+ * returns that tab only. Default: none. Injected mode returns `--tab-id`.
410
+ */
411
+ pinnedTabId() {
412
+ return void 0;
413
+ }
369
414
  /**
370
415
  * Subclass hook: run after launch + navigation, before `ready()` resolves.
371
416
  * Default: no-op. Injected mode overrides it to await the in-page runtime.
@@ -428,6 +473,14 @@ function loadInjectedBundle() {
428
473
  }
429
474
  var InjectedTransport = class extends HeadlessTransport {
430
475
  injected;
476
+ /**
477
+ * The pinned tab's key: 32 random bytes, base64url, generated once per
478
+ * transport (one launch) and kept in this process. The runner binds a tab
479
+ * that presents it to the key's digest, so the pin survives an origin hop
480
+ * while a page that merely learns the pinned id cannot attach as the tab.
481
+ * Lives only in the injected global — never in a storage artifact.
482
+ */
483
+ tabKey = crypto.randomBytes(32).toString("base64url");
431
484
  constructor(config, registry) {
432
485
  const raw = config.options ?? {};
433
486
  const headed = raw["headed"] === true;
@@ -462,9 +515,11 @@ var InjectedTransport = class extends HeadlessTransport {
462
515
  if (this.injected.appId) cfg.appId = this.injected.appId;
463
516
  if (this.injected.appName) cfg.appName = this.injected.appName;
464
517
  }
465
- if (this.injected.tabId) cfg.tabId = this.injected.tabId;
466
- if (this.injected.settleQuietMs !== void 0)
467
- cfg.settleQuietMs = this.injected.settleQuietMs;
518
+ if (this.injected.tabId) {
519
+ cfg.tabId = this.injected.tabId;
520
+ cfg.tabKey = this.tabKey;
521
+ }
522
+ if (this.injected.settleQuietMs !== void 0) cfg.settleQuietMs = this.injected.settleQuietMs;
468
523
  if (this.injected.settleTimeoutMs !== void 0)
469
524
  cfg.settleTimeoutMs = this.injected.settleTimeoutMs;
470
525
  if (this.injected.expectSelector !== void 0)
@@ -483,6 +538,9 @@ var InjectedTransport = class extends HeadlessTransport {
483
538
  ...this.injected.registrationMetadata?.userId ? { callerUserId: this.injected.registrationMetadata.userId } : {}
484
539
  };
485
540
  }
541
+ pinnedTabId() {
542
+ return this.injected.tabId;
543
+ }
486
544
  async buildInitScripts() {
487
545
  const scripts = [];
488
546
  const cfg = this.injectedConfig();