@qontinui/ui-bridge-wrapper 0.7.1 → 0.8.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,72 @@
1
+ /**
2
+ * Classify the outcome of a UI Bridge action for a CLI's error channel.
3
+ *
4
+ * WHY THIS EXISTS
5
+ *
6
+ * The in-page dispatcher reserves `throw` for a handful of cases (an unknown
7
+ * action id, mostly) and *returns* a structured failure for everything a
8
+ * caller actually hits — a missing element, an invisible one, a disabled one.
9
+ * `createActionFailure` (packages/ui-bridge/src/react/commandHandlers.ts)
10
+ * builds that envelope:
11
+ *
12
+ * { success: false, error: "Element x not found",
13
+ * failureDetails: { errorCode: "ELEMENT_NOT_FOUND", ... } }
14
+ *
15
+ * and `InjectedContext.execute` hands it back verbatim
16
+ * (src/transports/injected.ts). So a CLI that keys failure off `catch` alone
17
+ * prints that object as a *result* and exits 0: the caller reads the documented
18
+ * error channel, sees nothing, and reports a clean run for a page the action
19
+ * never changed. Measured on 0.7.1 — `ui-bridge-inject --exec
20
+ * 'executeElementAction {"id":"no-such-element",...}'` printed the
21
+ * ELEMENT_NOT_FOUND envelope under `result` and exited 0. A consumer that
22
+ * scripts a click and then snapshots gets a successful-looking run in which the
23
+ * click never happened.
24
+ *
25
+ * This module is the one place that answers "did that action actually do what
26
+ * it was asked?", so every bin gives the same answer. It invents no envelope:
27
+ * `{ success: false, error, failureDetails }` is already the repo-wide shape
28
+ * for a returned failure, and `{ code, message }` is already what the CLIs put
29
+ * on their `error` key for a thrown one.
30
+ */
31
+ /**
32
+ * The CLI-level error envelope written to an output line's `error` key.
33
+ *
34
+ * `details` carries the handler's own structured diagnostics UNFLATTENED — the
35
+ * whole `failureDetails` object for a returned failure, `WrapperTransportError.details`
36
+ * for a thrown one — so a caller can still branch on `ELEMENT_NOT_FOUND` vs
37
+ * `ELEMENT_NOT_VISIBLE` vs `ELEMENT_NOT_ENABLED`, read `retryRecommended`, or
38
+ * follow `suggestedActions` instead of parsing a message string.
39
+ */
40
+ export interface CliActionError {
41
+ /** Machine-readable code — `failureDetails.errorCode` where the handler set one. */
42
+ code: string;
43
+ message: string;
44
+ /** How the failure reached us: the handler returned it, or it was thrown. */
45
+ source: 'returned' | 'thrown';
46
+ /** The handler's structured diagnostics, verbatim. Omitted when there are none. */
47
+ details?: unknown;
48
+ }
49
+ /** Fallback code for a returned failure that named none of its own. */
50
+ export declare const RETURNED_FAILURE_CODE = "ACTION_FAILED";
51
+ /**
52
+ * True when `result` is a handler result that reports its own failure.
53
+ *
54
+ * The predicate is deliberately narrow — an explicit `success === false` — so
55
+ * it cannot misread a result that merely *lacks* a `success` field (a control
56
+ * snapshot, a find result, an element state) as a failure. That is the same
57
+ * signal every returned-failure site in the SDK sets; see the ~190 `success:
58
+ * false` returns across packages/ui-bridge/src.
59
+ */
60
+ export declare function isReturnedFailure(result: unknown): boolean;
61
+ /**
62
+ * Map a *returned* failure onto the CLI error envelope, or `null` when the
63
+ * result is not a failure at all (the overwhelmingly common case — this runs on
64
+ * every successful action too, so it stays cheap and total).
65
+ *
66
+ * `action` is used only to build a last-resort message for a handler that
67
+ * returned `{ success: false }` and nothing else.
68
+ */
69
+ export declare function returnedFailureError(action: string, result: unknown): CliActionError | null;
70
+ /** Map a *thrown* error onto the same envelope. */
71
+ export declare function thrownError(err: unknown): CliActionError;
72
+ //# sourceMappingURL=action-outcome.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"action-outcome.d.ts","sourceRoot":"","sources":["../src/action-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAUrD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAyB3F;AAED,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAcxD"}
@@ -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"}
@@ -3,8 +3,8 @@
3
3
 
4
4
  var fs = require('fs');
5
5
  var path = require('path');
6
- var url = require('url');
7
6
  var module$1 = require('module');
7
+ var crypto = require('crypto');
8
8
  var ui_bridge_cli_args_star = require('@qontinui/ui-bridge-cli-args');
9
9
 
10
10
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -36,6 +36,12 @@ var __defProp = Object.defineProperty;
36
36
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
37
37
  var __getOwnPropNames = Object.getOwnPropertyNames;
38
38
  var __hasOwnProp = Object.prototype.hasOwnProperty;
39
+ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
40
+ get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
41
+ }) : x)(function(x) {
42
+ if (typeof require !== "undefined") return require.apply(this, arguments);
43
+ throw Error('Dynamic require of "' + x + '" is not supported');
44
+ });
39
45
  var __copyProps = (to, from, except, desc) => {
40
46
  if (from && typeof from === "object" || typeof from === "function") {
41
47
  for (let key of __getOwnPropNames(from))
@@ -271,6 +277,8 @@ var HeadlessTransport = class extends BaseTransport {
271
277
  targetUrl,
272
278
  viewportWidth: typeof raw["viewportWidth"] === "number" ? raw["viewportWidth"] : void 0,
273
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,
274
282
  uiBridgeBase: typeof raw["uiBridgeBase"] === "string" ? raw["uiBridgeBase"] : void 0,
275
283
  waitForUiBridgeMs: typeof raw["waitForUiBridgeMs"] === "number" ? raw["waitForUiBridgeMs"] : void 0,
276
284
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
@@ -305,6 +313,7 @@ Underlying import error: ${cause}`
305
313
  }
306
314
  const initScripts = await this.buildInitScripts();
307
315
  const relayAuth = this.relayAuth();
316
+ const pinnedTabId = this.pinnedTabId();
308
317
  let tab;
309
318
  try {
310
319
  tab = await launchHeadlessTab({
@@ -314,13 +323,16 @@ Underlying import error: ${cause}`
314
323
  waitForUiBridgeMs: this.options.waitForUiBridgeMs,
315
324
  viewportWidth: this.options.viewportWidth,
316
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 } : {},
317
328
  userAgent: this.options.userAgent,
318
329
  forwardConsole: this.options.forwardConsole,
319
330
  initScripts: initScripts.length > 0 ? initScripts : void 0,
320
331
  launchArgs: this.options.launchArgs && this.options.launchArgs.length > 0 ? this.options.launchArgs : void 0,
321
332
  storageStatePath: this.options.storageStatePath,
322
333
  ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
323
- ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {}
334
+ ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
335
+ ...pinnedTabId ? { pinnedTabId } : {}
324
336
  });
325
337
  } catch (err) {
326
338
  const cause = err instanceof Error ? err.message : String(err);
@@ -342,8 +354,39 @@ Underlying launch error: ${cause}`
342
354
  tabId: tab.tabId,
343
355
  close: tab.close
344
356
  };
357
+ await this.verifyEmulation(tab.page);
345
358
  await this.afterLaunch(tab.page);
346
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
+ }
347
390
  /**
348
391
  * Subclass hook: init-scripts to register on the browser context before the
349
392
  * first navigation (via `context.addInitScript`). Default: none. Injected
@@ -361,6 +404,13 @@ Underlying launch error: ${cause}`
361
404
  relayAuth() {
362
405
  return {};
363
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
+ }
364
414
  /**
365
415
  * Subclass hook: run after launch + navigation, before `ready()` resolves.
366
416
  * Default: no-op. Injected mode overrides it to await the in-page runtime.
@@ -423,6 +473,14 @@ function loadInjectedBundle() {
423
473
  }
424
474
  var InjectedTransport = class extends HeadlessTransport {
425
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");
426
484
  constructor(config, registry) {
427
485
  const raw = config.options ?? {};
428
486
  const headed = raw["headed"] === true;
@@ -457,9 +515,11 @@ var InjectedTransport = class extends HeadlessTransport {
457
515
  if (this.injected.appId) cfg.appId = this.injected.appId;
458
516
  if (this.injected.appName) cfg.appName = this.injected.appName;
459
517
  }
460
- if (this.injected.tabId) cfg.tabId = this.injected.tabId;
461
- if (this.injected.settleQuietMs !== void 0)
462
- 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;
463
523
  if (this.injected.settleTimeoutMs !== void 0)
464
524
  cfg.settleTimeoutMs = this.injected.settleTimeoutMs;
465
525
  if (this.injected.expectSelector !== void 0)
@@ -478,6 +538,9 @@ var InjectedTransport = class extends HeadlessTransport {
478
538
  ...this.injected.registrationMetadata?.userId ? { callerUserId: this.injected.registrationMetadata.userId } : {}
479
539
  };
480
540
  }
541
+ pinnedTabId() {
542
+ return this.injected.tabId;
543
+ }
481
544
  async buildInitScripts() {
482
545
  const scripts = [];
483
546
  const cfg = this.injectedConfig();
@@ -984,6 +1047,30 @@ async function loginDrive(page, { email, password, timeoutMs, log = () => {
984
1047
  return { ok, finalUrl, landingPath, errorText };
985
1048
  }
986
1049
 
1050
+ // src/action-outcome.ts
1051
+ var RETURNED_FAILURE_CODE = "ACTION_FAILED";
1052
+ function isRecord(v) {
1053
+ return typeof v === "object" && v !== null && !Array.isArray(v);
1054
+ }
1055
+ function nonEmptyString(v) {
1056
+ return typeof v === "string" && v.length > 0 ? v : null;
1057
+ }
1058
+ function isReturnedFailure(result) {
1059
+ return isRecord(result) && result.success === false;
1060
+ }
1061
+ function returnedFailureError(action, result) {
1062
+ if (!isReturnedFailure(result)) return null;
1063
+ const r = result;
1064
+ const failureDetails = isRecord(r.failureDetails) ? r.failureDetails : null;
1065
+ const errorObj = isRecord(r.error) ? r.error : null;
1066
+ const code = nonEmptyString(failureDetails?.errorCode) ?? nonEmptyString(errorObj?.code) ?? RETURNED_FAILURE_CODE;
1067
+ const message = nonEmptyString(r.error) ?? nonEmptyString(errorObj?.message) ?? nonEmptyString(failureDetails?.message) ?? `action '${action}' reported success: false`;
1068
+ const details = failureDetails ?? errorObj ?? void 0;
1069
+ const out = { code, message, source: "returned" };
1070
+ if (details !== void 0) out.details = details;
1071
+ return out;
1072
+ }
1073
+
987
1074
  // src/capture-specs-cli.ts
988
1075
  var USAGE = `ui-bridge-capture-specs \u2014 log in and snapshot authed pages via the injected transport
989
1076
 
@@ -993,7 +1080,7 @@ Required (one of):
993
1080
 
994
1081
  Options:
995
1082
  --out <dir> Output dir for <slug>.snapshot.json files
996
- (default D:/qontinui-root/spec-capture).
1083
+ (default ./spec-capture, relative to cwd).
997
1084
  --origin <url> App origin (default https://qontinui.io).
998
1085
  --pages "slug=path,slug=path" Pages to capture (paths joined to --origin;
999
1086
  absolute http(s) URLs used verbatim). Default =
@@ -1010,7 +1097,7 @@ or set PLAYWRIGHT_BROWSERS_PATH).
1010
1097
 
1011
1098
  Exits non-zero if any capture bounced to login or errored.
1012
1099
  `;
1013
- var DEFAULT_OUT = "D:/qontinui-root/spec-capture";
1100
+ var DEFAULT_OUT = "spec-capture";
1014
1101
  var DEFAULT_ORIGIN = "https://qontinui.io";
1015
1102
  var DEFAULT_DEVICE = "c79a07d5-7e40-49b4-87fa-554c749f9644";
1016
1103
  var CaptureCliArgError = class extends Error {
@@ -1151,7 +1238,10 @@ ${USAGE}`);
1151
1238
  let snap = null;
1152
1239
  let err = null;
1153
1240
  try {
1154
- snap = await ctx.snapshot();
1241
+ const raw = await ctx.snapshot();
1242
+ const failure = returnedFailureError("getControlSnapshot", raw);
1243
+ if (failure) err = `${failure.code}: ${failure.message}`;
1244
+ else snap = raw;
1155
1245
  } catch (e) {
1156
1246
  err = e instanceof Error ? e.message : String(e);
1157
1247
  }
@@ -1205,13 +1295,7 @@ ${USAGE}`);
1205
1295
  }
1206
1296
  process.exit(code);
1207
1297
  }
1208
- var isMain = (() => {
1209
- try {
1210
- return process.argv[1] === url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('capture-specs-cli.cjs', document.baseURI).href)));
1211
- } catch {
1212
- return false;
1213
- }
1214
- })();
1298
+ var isMain = typeof __require !== "undefined" && typeof module !== "undefined" && __require.main === module;
1215
1299
  if (isMain) {
1216
1300
  void main().catch((err) => {
1217
1301
  const msg = err instanceof Error ? err.message : String(err);