@qontinui/ui-bridge-wrapper 0.7.2 → 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.
@@ -10,7 +10,7 @@
10
10
  * only generic argument plumbing, a one-shot exec path (Variant A), and a
11
11
  * stay-alive relay loop (Variant B).
12
12
  *
13
- * Two modes:
13
+ * Three modes:
14
14
  * - Variant A (one-shot exec): `--exec '<action> <json>'` (repeatable) or
15
15
  * `--exec-stdin` (NDJSON on stdin). Each action runs against the in-page
16
16
  * runtime; one JSON result line per action is written to stdout, then exit.
@@ -18,14 +18,22 @@
18
18
  * `{ success: false }` — puts a `{ code, message, source, details }` object
19
19
  * on that line's `error` key and makes the process exit 1. See
20
20
  * `./action-outcome.js` for why the returned case needs saying out loud.
21
+ * With `--screenshot <path>`, every `getControlSnapshot` action is captured
22
+ * in lockstep with a PNG frame (`./frame-capture.js`).
21
23
  * - Variant B (relay, DEFAULT): no exec actions → register as a relay tab
22
24
  * (requires `--relay`) and stay alive until SIGINT/SIGTERM.
25
+ * - Capture matrix (`--capture-matrix <dir>`): the Variant-A plan, run once
26
+ * per viewport × DPR × colour-scheme combination, storing every
27
+ * frame-and-snapshot pair with its provenance (`./capture-matrix.js`).
23
28
  *
24
29
  * The arg parsing, validation, option building, and mode selection are exported
25
30
  * pure functions so they can be unit-tested without spawning a browser or
26
31
  * calling `main()`.
27
32
  */
28
- export declare const USAGE = "ui-bridge-inject \u2014 drive UI Bridge's injected transport against a UI-Bridge-free page\n\nRequired:\n --url <pageUrl> Page to open. Must start with http:// or https://\n (maps to the transport's options.targetUrl)\n\nRelay (Variant B \u2014 the default mode; --relay is REQUIRED in this mode):\n --relay <uiBridgeBase> UI Bridge relay base; the injected runtime registers\n as a relay tab. Example: http://localhost:3001/api/ui-bridge\n --auth-token <T> Bearer token for an auth-gated relay\n --registration-metadata <json>\n JSON {\"userId\":\"...\",\"sessionId\":\"...\"} for per-user\n tab-scoping on relay heartbeats\n --app-id <id> App id reported to the relay registry\n --app-name <name> Display name reported to the relay registry\n --tab-id <id> Stable per-tab id override\n\nExec (Variant A \u2014 one-shot; presence of any --exec/--exec-stdin selects this mode):\n --exec '<action> <json>' Run one action (repeatable). The value is an action\n id, a space, then a JSON payload (payload optional \u2192\n defaults {}). Example: --exec 'find {\"text\":\"Sign in\"}'\n --exec-stdin Read NDJSON lines from stdin; each line is\n {\"action\":\"...\",\"payload\":{...}}\n\n Exec output & exit code:\n One JSON line per action, in order, on stdout \u2014 ALWAYS one line per action,\n including failures. An action that succeeded prints {\"action\":..,\"result\":..}.\n An action that FAILED additionally carries an \"error\" key:\n {\"action\":..,\"result\":..,\"error\":{\"code\":..,\"message\":..,\"source\":\"returned\",\n \"details\":{..}}}\n A failure is EITHER thrown by the transport (source \"thrown\") OR returned by\n the in-page handler as {\"success\":false,...} (source \"returned\") \u2014 a missing,\n invisible or disabled element is the RETURNED kind, so \"result\" alone never\n tells you whether the action did anything. Branch on \"error\"; \"error.code\" is\n the handler's own errorCode (ELEMENT_NOT_FOUND / ELEMENT_NOT_VISIBLE /\n ELEMENT_NOT_ENABLED / ...) and \"error.details\" is its full failureDetails,\n unflattened.\n\n A failed action does NOT abort the actions after it. Every action runs, each\n gets its line, and the process exits 1 at the end if ANY action failed (0 if\n all succeeded). This is the pre-existing behaviour of a thrown failure, kept\n for a returned one so there is one convention rather than two \u2014 and it is\n what keeps the one-line-per-action contract intact for a caller that pairs\n N actions with N lines. A caller that wants stop-on-first-failure gets it by\n running one action per invocation and checking the exit code.\n\nOptional:\n --storage-state <path> Seed the browser context from a Playwright storageState\n JSON file (cookies + localStorage) produced by\n 'ui-bridge-login-web --storage-state-out <path>'. This\n carries a saved authenticated session past a login wall,\n so you can drive a login-walled page (e.g. an /admin\n wizard) WITHOUT re-driving the hosted-UI login each run.\n --headed Launch with a visible window (default: headless)\n --ready-timeout <ms> Max wait for the injected runtime ready/settle gate (default 30000)\n --no-settle Gate ready on the runtime being live only, NOT on the DOM\n settling. By default the launcher waits for the page to paint\n + go quiet (so a client-rendered SPA is drivable immediately),\n which is almost always what you want.\n --settle-quiet <ms> Quiet window with no DOM re-seed before settled (default 500)\n --settle-timeout <ms> Hard cap before settling regardless of mutations (default 10000)\n --expect-selector <css> Don't settle until an element matching this CSS selector\n exists \u2014 use when the target control (e.g. a login form)\n mounts lazily after unrelated chrome. If it never appears\n before --settle-timeout, ready() fails with a BLOCKED error\n instead of returning a control-less page.\n --viewport <WxH> Viewport size, e.g. 1280x720\n --launch-arg <arg> Extra Chromium command-line argument (repeatable),\n passed through to chromium.launch({ args }).\n NOTE: when --url is https and --relay resolves to a\n loopback host, the LNA-disable flags\n (--disable-features=LocalNetworkAccessChecks,...) are\n auto-appended \u2014 Chromium otherwise blocks the\n https-page \u2192 loopback-relay fetch (Local Network Access).\n --quiet Suppress human-readable logs (JSON results still print)\n --help, -h Print this help and exit\n\nExamples:\n # Variant B: register an injected tab against a relay and stay alive\n ui-bridge-inject --url https://example.com/login \\\n --relay http://localhost:3001/api/ui-bridge --app-name \"example login\"\n\n # Variant A: snapshot the controls on a page, then exit\n ui-bridge-inject --url https://example.com/login \\\n --exec 'getControlSnapshot {}'\n\n # Variant A: find a control and act on it\n ui-bridge-inject --url https://example.com/login \\\n --exec 'find {\"text\":\"Sign in\"}'\n\n # Reuse a saved login: drive a login-walled page with a captured auth artifact\n ui-bridge-login-web --url \"https://qontinui.io/login?next=%2Fadmin\" \\\n --success /admin --storage-state-out auth.json\n ui-bridge-inject --url https://qontinui.io/admin \\\n --storage-state auth.json --exec 'getControlSnapshot {}'\n";
33
+ import { type CliActionError } from './action-outcome.js';
34
+ import { type FrameColorScheme, type FrameError, type FrameRecord } from './frame-capture.js';
35
+ import { type MatrixCell, type MatrixCellReport, type MatrixManifest, type MatrixViewport } from './capture-matrix.js';
36
+ export declare const USAGE = "ui-bridge-inject \u2014 drive UI Bridge's injected transport against a UI-Bridge-free page\n\nRequired:\n --url <pageUrl> Page to open. Must start with http:// or https://\n (maps to the transport's options.targetUrl)\n\nRelay (Variant B \u2014 the default mode; --relay is REQUIRED in this mode):\n --relay <uiBridgeBase> UI Bridge relay base; the injected runtime registers\n as a relay tab. Example: http://localhost:3001/api/ui-bridge\n --auth-token <T> Bearer token for an auth-gated relay. Puts the token on THIS\n process's command line, which any local process/user can read\n (Task Manager, /proc, WMI) for the process's whole lifetime \u2014\n prefer --auth-token-file or $UI_BRIDGE_AUTH_TOKEN instead.\n --auth-token-file <path> Read the bearer token from a file (trimmed) instead of argv.\n Takes priority over $UI_BRIDGE_AUTH_TOKEN, loses to --auth-token.\n --registration-metadata <json>\n JSON {\"userId\":\"...\",\"sessionId\":\"...\"} for per-user\n tab-scoping on relay heartbeats\n --app-id <id> App id reported to the relay registry\n --app-name <name> Display name reported to the relay registry\n --tab-id <id> Stable per-tab id override\n\nExec (Variant A \u2014 one-shot; presence of any --exec/--exec-stdin selects this mode):\n --exec '<action> <json>' Run one action (repeatable). The value is an action\n id, a space, then a JSON payload (payload optional \u2192\n defaults {}). Example: --exec 'find {\"text\":\"Sign in\"}'\n --exec-stdin Read NDJSON lines from stdin; each line is\n {\"action\":\"...\",\"payload\":{...}}\n\n Waiting BETWEEN exec steps (CLI-side actions, not in-page ones):\n Exec steps run back to back with nothing between them, so state that\n arrives AFTER ready()/settle \u2014 a row fetched by a request the previous\n step kicked off, a panel that mounts a tick later \u2014 cannot be awaited.\n Two action ids are handled by the CLI itself for exactly that:\n\n waitForSelector {\"selector\":\"<css>\",\"timeoutMs\":10000,\"state\":\"attached\"}\n Wait until the selector reaches 'state' in the page. 'state' is one of\n attached (DEFAULT \u2014 the same \"exists in the DOM\" test --expect-selector\n applies) | visible | hidden | detached. 'timeoutMs' defaults to 10000.\n On timeout the step FAILS like any other: an \"error\" line on stdout and\n exit 1 at the end.\n Result: {\"waited\":true,\"selector\":..,\"state\":..,\"elapsedMs\":..}\n\n sleep {\"ms\":250}\n Unconditional pause. 'ms' is required, 0..600000. Prefer\n waitForSelector \u2014 a sleep encodes a guess, not a condition.\n Result: {\"slept\":250}\n\n Both go through the same one-line-per-action channel as an in-page action,\n so an N-step run still prints N lines in order. Neither shadows an in-page\n action id \u2014 the injected dispatcher defines neither.\n\n Exec output & exit code:\n One JSON line per action, in order, on stdout \u2014 ALWAYS one line per action,\n including failures. An action that succeeded prints {\"action\":..,\"result\":..}.\n An action that FAILED additionally carries an \"error\" key:\n {\"action\":..,\"result\":..,\"error\":{\"code\":..,\"message\":..,\"source\":\"returned\",\n \"details\":{..}}}\n A failure is EITHER thrown by the transport (source \"thrown\") OR returned by\n the in-page handler as {\"success\":false,...} (source \"returned\") \u2014 a missing,\n invisible or disabled element is the RETURNED kind, so \"result\" alone never\n tells you whether the action did anything. Branch on \"error\"; \"error.code\" is\n the handler's own errorCode (ELEMENT_NOT_FOUND / ELEMENT_NOT_VISIBLE /\n ELEMENT_NOT_ENABLED / ...) and \"error.details\" is its full failureDetails,\n unflattened.\n\n A failed action does NOT abort the actions after it. Every action runs, each\n gets its line, and the process exits 1 at the end if ANY action failed (0 if\n all succeeded). This is the pre-existing behaviour of a thrown failure, kept\n for a returned one so there is one convention rather than two \u2014 and it is\n what keeps the one-line-per-action contract intact for a caller that pairs\n N actions with N lines. A caller that wants stop-on-first-failure gets it by\n running one action per invocation and checking the exit code.\n\nFrames (Variant A):\n --screenshot <path> Capture a PNG frame IN LOCKSTEP with every\n getControlSnapshot action: snapshot, frame, snapshot\n again, retried until both snapshots agree on every\n element's box. That action's line gains a \"frame\":\n {\"path\",\"format\":\"png\",\"width\",\"height\",\n \"devicePixelRatio\",\"cssViewport\":{\"width\",\"height\"},\n \"colorScheme\",\"capturedAt\",\n \"lockstep\":{\"verified\",\"attempts\",\"changedElements\"}}\n every field read off the page or the PNG at capture\n time, never copied from the flags. {n} in the FILE\n NAME of <path> is replaced by the action's 1-based\n position (= its output line) and is REQUIRED when the\n run takes more than one snapshot; {n} in a directory\n name is refused. A frame that cannot be produced leaves\n \"frame\":null plus \"frameError\":{\"code\",\"message\"} on the\n line \u2014 the snapshot still stands \u2014 and exit 1.\n A frame is RAW PIXELS of the page: data-bridge-redact\n masks elements in snapshots and over the relay, never\n in a screenshot, so a frame shows whatever the page\n showed. Directories created for frames are 0700 and\n the files 0600.\n --dpr <n> Device pixel ratio of the browser context, e.g. 2 or\n 2.625 (Chromium's --force-device-scale-factor does NOT\n reach the page; this does). Default 1.\n --color-scheme <dark|light> prefers-color-scheme of the browser context.\n Default: no override (light).\n Both are read back from the page after launch; a page\n that reports anything else fails the run\n (EMULATION_NOT_APPLIED) instead of being measured as if.\n\nCapture matrix (its own mode):\n --capture-matrix <dir> Run the plan once per --viewport \u00D7 --dpr \u00D7 --color-scheme\n combination, each a fresh browser context, and store\n every frame-and-snapshot pair with its provenance:\n <dir>/<cell>/frame-<n>.png, snapshot-<n>.json,\n results.ndjson, and <dir>/matrix.json for all cells.\n In this mode those three flags take comma-separated\n lists (or repeat): --viewport 390x844,1280x720\n --dpr 1,2 --color-scheme light,dark. An axis left out\n stays at the browser default and is named so in the\n cell id (e.g. 390x844_dpr-default_dark). --exec /\n --exec-stdin give the per-cell plan (default: one\n 'getControlSnapshot {}'); a frame is captured beside\n every getControlSnapshot in it. Prints one JSON line\n per cell; exits 1 if any cell is not \"captured\".\n Takes no --relay and no --screenshot. <dir> must be\n empty or not exist yet: a non-empty one is refused,\n never cleared. Directories it creates are 0700 and\n every frame, snapshot and manifest 0600 \u2014 frames are\n raw pixels that data-bridge-redact does not scrub.\n\nOptional:\n --storage-state <path> Seed the browser context from a Playwright storageState\n JSON file (cookies + localStorage) produced by\n 'ui-bridge-login-web --storage-state-out <path>'. This\n carries a saved authenticated session past a login wall,\n so you can drive a login-walled page (e.g. an /admin\n wizard) WITHOUT re-driving the hosted-UI login each run.\n --headed Launch with a visible window (default: headless)\n --ready-timeout <ms> Max wait for the injected runtime ready/settle gate (default 30000)\n --no-settle Gate ready on the runtime being live only, NOT on the DOM\n settling. By default the launcher waits for the page to paint\n + go quiet (so a client-rendered SPA is drivable immediately),\n which is almost always what you want.\n --settle-quiet <ms> Quiet window with no DOM re-seed before settled (default 500)\n --settle-timeout <ms> Hard cap before settling regardless of mutations (default 10000)\n --expect-selector <css> Don't settle until an element matching this CSS selector\n exists \u2014 use when the target control (e.g. a login form)\n mounts lazily after unrelated chrome. If it never appears\n before --settle-timeout, ready() fails with a BLOCKED error\n instead of returning a control-less page.\n --viewport <WxH> Viewport size in CSS pixels, e.g. 1280x720 (default 1280x720).\n Each side 1..8192 CSS pixels.\n --launch-arg <arg> Extra Chromium command-line argument (repeatable),\n passed through to chromium.launch({ args }).\n NOTE: when --url is https and --relay resolves to a\n loopback host, the LNA-disable flags\n (--disable-features=LocalNetworkAccessChecks,...) are\n auto-appended \u2014 Chromium otherwise blocks the\n https-page \u2192 loopback-relay fetch (Local Network Access).\n --quiet Suppress human-readable logs (JSON results still print)\n --help, -h Print this help and exit\n\nExamples:\n # Variant B: register an injected tab against a relay and stay alive\n ui-bridge-inject --url https://example.com/login \\\n --relay http://localhost:3001/api/ui-bridge --app-name \"example login\"\n\n # Variant B against an auth-gated relay, without putting the token on argv\n ui-bridge-inject --url https://qontinui.io/admin/coord/fleet \\\n --relay https://qontinui.io/api/ui-bridge --auth-token-file \"$HOME/.idtok\"\n\n # Variant A: snapshot the controls on a page, then exit\n ui-bridge-inject --url https://example.com/login \\\n --exec 'getControlSnapshot {}'\n\n # Variant A: find a control and act on it\n ui-bridge-inject --url https://example.com/login \\\n --exec 'find {\"text\":\"Sign in\"}'\n\n # Variant A: wait for a late-arriving row, THEN read it (no --expect-selector)\n ui-bridge-inject --url https://example.com/account --exec 'waitForSelector {\"selector\":\"[data-row=account]\",\"timeoutMs\":15000}' --exec 'discover {}'\n\n # A frame in lockstep with the snapshot, at a Retina DPR in dark mode\n ui-bridge-inject --url http://127.0.0.1:3000/ --viewport 1280x720 --dpr 2 \\\n --color-scheme dark --screenshot ./frame.png --exec 'getControlSnapshot {}'\n\n # Before/after a click: {n} names each frame by its action's position\n ui-bridge-inject --url http://127.0.0.1:3000/ --screenshot './frame-{n}.png' \\\n --exec 'getControlSnapshot {}' \\\n --exec 'executeElementAction {\"id\":\"open\",\"request\":{\"action\":\"click\"}}' \\\n --exec 'getControlSnapshot {}'\n\n # Capture matrix: 2 breakpoints x 2 schemes x 2 DPRs = 8 frame-and-snapshot pairs\n ui-bridge-inject --url http://127.0.0.1:3000/ --capture-matrix ./matrix \\\n --viewport 390x844,1280x720 --color-scheme light,dark --dpr 1,2\n\n # Reuse a saved login: drive a login-walled page with a captured auth artifact\n ui-bridge-login-web --url \"https://qontinui.io/login?next=%2Fadmin\" \\\n --success /admin --storage-state-out auth.json\n ui-bridge-inject --url https://qontinui.io/admin \\\n --storage-state auth.json --exec 'getControlSnapshot {}'\n";
29
37
  /** A single Variant-A action to execute. */
30
38
  export interface ExecAction {
31
39
  action: string;
@@ -36,6 +44,8 @@ export interface InjectCliArgs {
36
44
  url: string;
37
45
  relay: string | null;
38
46
  authToken: string | null;
47
+ /** Path to a file holding the bearer token (trimmed on read); see --auth-token-file. */
48
+ authTokenFile: string | null;
39
49
  registrationMetadata: {
40
50
  userId: string;
41
51
  sessionId: string;
@@ -50,8 +60,19 @@ export interface InjectCliArgs {
50
60
  appId: string | null;
51
61
  appName: string | null;
52
62
  tabId: string | null;
53
- viewportWidth: number | null;
54
- viewportHeight: number | null;
63
+ /**
64
+ * `--viewport` values in the order given. At most one outside
65
+ * `--capture-matrix`, where it is the one viewport; inside, it is an axis.
66
+ */
67
+ viewports: MatrixViewport[];
68
+ /** `--dpr` values (device scale factors). Same one-vs-axis rule as `viewports`. */
69
+ dprs: number[];
70
+ /** `--color-scheme` values. Same one-vs-axis rule as `viewports`. */
71
+ colorSchemes: FrameColorScheme[];
72
+ /** `--screenshot` path template (may carry `{n}`), or null. Variant A only. */
73
+ screenshot: string | null;
74
+ /** `--capture-matrix` output directory, or null. Selects matrix mode. */
75
+ captureMatrix: string | null;
55
76
  /** Path to a Playwright storageState JSON file to seed the context (from --storage-state). */
56
77
  storageState: string | null;
57
78
  /** Extra Chromium launch args collected from --launch-arg flags (in order). */
@@ -70,6 +91,27 @@ export interface InjectCliArgs {
70
91
  export declare class InjectCliArgError extends Error {
71
92
  constructor(message: string);
72
93
  }
94
+ /**
95
+ * Upper bound on `--dpr`. A typo such as `--dpr 20` would otherwise ask
96
+ * Chromium for a 25600-pixel-wide frame; the densest shipping displays are
97
+ * well under this.
98
+ */
99
+ export declare const MAX_DPR = 8;
100
+ /**
101
+ * Upper bound on each `--viewport` side, in CSS pixels. Above it a typo (one
102
+ * zero too many) would ask Chromium for a page wider than any display, and at
103
+ * a DPR of 2 or more a frame past Chromium's 16384-pixel screenshot limit.
104
+ */
105
+ export declare const MAX_VIEWPORT_SIDE = 8192;
106
+ /** Parse one `WxH` viewport in CSS pixels: each side an integer in 1..{@link MAX_VIEWPORT_SIDE}. */
107
+ export declare function parseViewport(raw: string): MatrixViewport;
108
+ /**
109
+ * Parse one `--dpr` value: a plain decimal in (0, {@link MAX_DPR}]. A decimal
110
+ * pattern rather than `Number()` alone, which would also accept `0x2` and `1e1`.
111
+ */
112
+ export declare function parseDpr(raw: string): number;
113
+ /** Parse one `--color-scheme` value. */
114
+ export declare function parseColorScheme(raw: string): FrameColorScheme;
73
115
  /**
74
116
  * Parse `argv` (already sliced past `node script`) into validated args.
75
117
  * Throws {@link InjectCliArgError} on bad input (no `process.exit` — testable).
@@ -81,10 +123,22 @@ export declare function parseArgs(argv: string[]): InjectCliArgs;
81
123
  */
82
124
  export declare function validateArgs(args: InjectCliArgs): void;
83
125
  /**
84
- * Mode selection: any `--exec`/`--exec-stdin` → one-shot exec (Variant A);
85
- * otherwise relay registration (Variant B, the default).
126
+ * Mode selection: `--capture-matrix` → the capture matrix; else any
127
+ * `--exec`/`--exec-stdin` → one-shot exec (Variant A); otherwise relay
128
+ * registration (Variant B, the default).
86
129
  */
87
- export declare function selectMode(args: InjectCliArgs): 'exec' | 'relay';
130
+ export declare function selectMode(args: InjectCliArgs): 'exec' | 'relay' | 'matrix';
131
+ /** The actions `--screenshot` / the capture matrix pair a frame with. */
132
+ export declare const SNAPSHOT_ACTIONS: ReadonlySet<string>;
133
+ /**
134
+ * Validate `--screenshot` against the full action list, which with
135
+ * `--exec-stdin` is known only after stdin is read — so this runs then, before
136
+ * the browser launches, rather than inside `parseArgs`.
137
+ *
138
+ * Refuses a run with no snapshot action (the flag would do nothing, silently)
139
+ * and a fixed path over several snapshots (each frame would overwrite the last).
140
+ */
141
+ export declare function validateFramePlan(actions: readonly ExecAction[], screenshot: string | null): void;
88
142
  /**
89
143
  * Chromium feature flags that must be DISABLED for an https page to fetch a
90
144
  * loopback (local-network) relay. Chromium's Local Network Access checks
@@ -109,9 +163,151 @@ export declare function buildLaunchArgs(args: Pick<InjectCliArgs, 'url' | 'relay
109
163
  launchArgs: string[];
110
164
  lnaAutoAppended: boolean;
111
165
  };
166
+ /**
167
+ * Resolve the effective bearer token from, in priority order: an explicit
168
+ * `--auth-token` (unchanged for backward compat), `--auth-token-file` (read via
169
+ * `readFile`, trimmed), then the `UI_BRIDGE_AUTH_TOKEN` env var. Returns `null`
170
+ * when none apply. `readFile` and `env` are injected so this stays testable
171
+ * without touching the real filesystem/environment.
172
+ */
173
+ export declare function resolveAuthToken(args: Pick<InjectCliArgs, 'authToken' | 'authTokenFile'>, env: Readonly<Record<string, string | undefined>>, readFile: (path: string) => string): string | null;
112
174
  /**
113
175
  * Build the `options` object for `createTransport({ kind: 'injected', options })`.
114
176
  * Only includes keys the user provided; `targetUrl` is always present.
115
177
  */
116
178
  export declare function buildTransportOptions(args: InjectCliArgs): Record<string, unknown>;
179
+ /**
180
+ * Transport options for one capture-matrix cell: every non-axis flag exactly as
181
+ * {@link buildTransportOptions} sets it, and the cell's own three axis values.
182
+ */
183
+ export declare function buildCellTransportOptions(args: InjectCliArgs, cell: MatrixCell): Record<string, unknown>;
184
+ /**
185
+ * ---------------------------------------------------------------------------
186
+ * CLI-side wait actions
187
+ * ---------------------------------------------------------------------------
188
+ *
189
+ * Variant A runs its `--exec` steps back to back with nothing in between, and
190
+ * the only wait the CLI had was the one-shot `--expect-selector` gate applied
191
+ * ONCE, before the first step. So a driver could not await anything that
192
+ * arrives after settle — a row fetched by a request an earlier step kicked
193
+ * off, a panel that mounts a tick later. The workaround was to re-invoke the
194
+ * whole CLI (a fresh browser, a fresh page load) per wait, which discards the
195
+ * page state the earlier steps produced.
196
+ *
197
+ * `waitForSelector` and `sleep` close that. They are dispatched through the
198
+ * SAME `transport.dispatch` channel as an in-page action so the
199
+ * one-line-per-action contract and the failure/exit-code convention hold
200
+ * unchanged, but they execute in the CLI process against the Playwright
201
+ * `page` on the transport context rather than in the page realm — no `eval`,
202
+ * no in-page runtime dependency, and a timeout surfaces as a real thrown
203
+ * failure rather than a returned envelope.
204
+ */
205
+ /** Action ids the CLI handles itself instead of forwarding to the page. */
206
+ export declare const CLI_WAIT_ACTIONS: readonly ["waitForSelector", "sleep"];
207
+ /** Playwright selector states `waitForSelector` accepts. */
208
+ export declare const WAIT_SELECTOR_STATES: readonly ["attached", "detached", "visible", "hidden"];
209
+ export type WaitSelectorState = (typeof WAIT_SELECTOR_STATES)[number];
210
+ /** Default bound on `waitForSelector` when the payload omits `timeoutMs`. */
211
+ export declare const DEFAULT_WAIT_SELECTOR_TIMEOUT_MS = 10000;
212
+ /** Upper bound on `sleep`'s `ms` — a longer pause is a wedged run, not a wait. */
213
+ export declare const MAX_SLEEP_MS = 600000;
214
+ /** Validated `waitForSelector` payload. */
215
+ export interface WaitForSelectorPayload {
216
+ selector: string;
217
+ timeoutMs: number;
218
+ state: WaitSelectorState;
219
+ }
220
+ /**
221
+ * Validate a `waitForSelector` payload. Exported so the grammar is unit-tested
222
+ * without launching a browser.
223
+ */
224
+ export declare function parseWaitForSelectorPayload(payload: unknown): WaitForSelectorPayload;
225
+ /** Validate a `sleep` payload. Exported for the same reason. */
226
+ export declare function parseSleepPayload(payload: unknown): {
227
+ ms: number;
228
+ };
229
+ /**
230
+ * Validate the payload of every CLI-side wait action in `actions`, throwing
231
+ * {@link InjectCliArgError} on the first bad one.
232
+ *
233
+ * Runs BEFORE the browser launches: a typo in a `waitForSelector` payload
234
+ * should cost an argument error, not a Chromium launch followed by a failed
235
+ * step several actions into the run.
236
+ */
237
+ export declare function validateWaitActions(actions: readonly ExecAction[]): void;
238
+ /**
239
+ * Register `waitForSelector` + `sleep` on `registrar`.
240
+ *
241
+ * Called BEFORE the exec loop's forward-anything-else fallback, so these ids
242
+ * resolve to the CLI implementations rather than being forwarded into the page
243
+ * (where they are not actions at all and would fail with an unknown-action
244
+ * error). Exported so a test can register against a stub registry.
245
+ */
246
+ export declare function registerWaitActions(registrar: {
247
+ register(action: string, fn: (params: unknown, ctx: unknown) => unknown): void;
248
+ }): void;
249
+ /**
250
+ * ---------------------------------------------------------------------------
251
+ * Frame-paired snapshots
252
+ * ---------------------------------------------------------------------------
253
+ */
254
+ /**
255
+ * The private action id a frame-paired snapshot is dispatched under. A
256
+ * double-underscore id like `__inject_cli_info`: no in-page action is named
257
+ * this, so it can never shadow one.
258
+ */
259
+ export declare const CAPTURE_FRAME_ACTION = "__inject_cli_capture_frame";
260
+ /** The slice of the transport the action loop drives. */
261
+ export interface ExecTransport {
262
+ readonly handlerRegistry: {
263
+ has(actionId: string): boolean;
264
+ };
265
+ register(actionId: string, fn: (params: unknown, ctx: unknown) => unknown): void;
266
+ dispatch(actionId: string, params?: unknown): Promise<unknown>;
267
+ }
268
+ /**
269
+ * Register the lockstep frame capture under {@link CAPTURE_FRAME_ACTION}. It
270
+ * runs in the CLI process against the transport context's `page` (the
271
+ * screenshot) and `execute` (the in-page snapshot) — see `./frame-capture.js`.
272
+ */
273
+ export declare function registerFrameCapture(registrar: Pick<ExecTransport, 'register'>): void;
274
+ /**
275
+ * One action's output line: the shape exec mode prints and the capture matrix
276
+ * stores. `action` is always the FIRST key — consumers find result lines by
277
+ * their `{"action":` prefix among forwarded browser output.
278
+ */
279
+ export interface ExecLine {
280
+ action: string;
281
+ result?: unknown;
282
+ error?: CliActionError;
283
+ /** Present only on a frame-paired snapshot; `null` when the frame failed. */
284
+ frame?: FrameRecord | null;
285
+ frameError?: FrameError;
286
+ }
287
+ /**
288
+ * Run `actions` in order against a READY transport, handing one
289
+ * {@link ExecLine} per action to `onLine`. `framePathFor(position, action)`
290
+ * names the frame to pair with an action, or `null` for none.
291
+ *
292
+ * Every action runs whatever happened to the ones before it. Returns `true` if
293
+ * any action failed — thrown or returned — or any requested frame was not
294
+ * produced.
295
+ */
296
+ export declare function executeActions(transport: ExecTransport, actions: readonly ExecAction[], framePathFor: (position: number, action: string) => string | null, onLine: (line: ExecLine, position: number) => void): Promise<boolean>;
297
+ /**
298
+ * `--capture-matrix` writes into an EMPTY directory only. Frames from a
299
+ * previous run would otherwise sit beside this run's under the same cell ids,
300
+ * indistinguishable from them, and clearing the directory silently could
301
+ * delete files the caller meant to keep. So a non-empty directory (or a file
302
+ * at that path) is refused before any browser launches; one that does not
303
+ * exist yet is created owner-only.
304
+ */
305
+ export declare function assertEmptyMatrixDir(dir: string): void;
306
+ /**
307
+ * Run the capture matrix: every cell in turn into `args.captureMatrix`, then
308
+ * `<dir>/matrix.json`. Returns the manifest it wrote; `onCell` sees each cell's
309
+ * report as it completes. Never exits the process — that is `runMatrix`'s job —
310
+ * so it is callable from a test.
311
+ */
312
+ export declare function captureMatrix(args: InjectCliArgs, plan: readonly ExecAction[], onCell?: (report: MatrixCellReport, cellDir: string) => void): Promise<MatrixManifest>;
117
313
  //# sourceMappingURL=inject-cli.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"inject-cli.d.ts","sourceRoot":"","sources":["../src/inject-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,eAAO,MAAM,KAAK,mrMA+FjB,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oBAAoB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnE,MAAM,EAAE,OAAO,CAAC;IAChB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iFAAiF;IACjF,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8FAA8F;IAC9F,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gEAAgE;IAChE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AA2BD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA8LvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CActD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,OAAO,CAEhE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,4HAIvB,CAAC;AAEX,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CASxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,OAAO,GAAG,YAAY,CAAC,GACxD;IAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,OAAO,CAAA;CAAE,CA8BpD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBlF"}
1
+ {"version":3,"file":"inject-cli.d.ts","sourceRoot":"","sources":["../src/inject-cli.ts"],"names":[],"mappings":"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"}
@@ -3,6 +3,7 @@
3
3
 
4
4
  var fs = require('fs');
5
5
  var module$1 = require('module');
6
+ var crypto = require('crypto');
6
7
  var ui_bridge_cli_args_star = require('@qontinui/ui-bridge-cli-args');
7
8
 
8
9
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -271,6 +272,8 @@ var HeadlessTransport = class extends BaseTransport {
271
272
  targetUrl,
272
273
  viewportWidth: typeof raw["viewportWidth"] === "number" ? raw["viewportWidth"] : void 0,
273
274
  viewportHeight: typeof raw["viewportHeight"] === "number" ? raw["viewportHeight"] : void 0,
275
+ deviceScaleFactor: typeof raw["deviceScaleFactor"] === "number" ? raw["deviceScaleFactor"] : void 0,
276
+ colorScheme: raw["colorScheme"] === "light" || raw["colorScheme"] === "dark" ? raw["colorScheme"] : void 0,
274
277
  uiBridgeBase: typeof raw["uiBridgeBase"] === "string" ? raw["uiBridgeBase"] : void 0,
275
278
  waitForUiBridgeMs: typeof raw["waitForUiBridgeMs"] === "number" ? raw["waitForUiBridgeMs"] : void 0,
276
279
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
@@ -305,6 +308,7 @@ Underlying import error: ${cause}`
305
308
  }
306
309
  const initScripts = await this.buildInitScripts();
307
310
  const relayAuth = this.relayAuth();
311
+ const pinnedTabId = this.pinnedTabId();
308
312
  let tab;
309
313
  try {
310
314
  tab = await launchHeadlessTab({
@@ -314,13 +318,16 @@ Underlying import error: ${cause}`
314
318
  waitForUiBridgeMs: this.options.waitForUiBridgeMs,
315
319
  viewportWidth: this.options.viewportWidth,
316
320
  viewportHeight: this.options.viewportHeight,
321
+ ...this.options.deviceScaleFactor !== void 0 ? { deviceScaleFactor: this.options.deviceScaleFactor } : {},
322
+ ...this.options.colorScheme !== void 0 ? { colorScheme: this.options.colorScheme } : {},
317
323
  userAgent: this.options.userAgent,
318
324
  forwardConsole: this.options.forwardConsole,
319
325
  initScripts: initScripts.length > 0 ? initScripts : void 0,
320
326
  launchArgs: this.options.launchArgs && this.options.launchArgs.length > 0 ? this.options.launchArgs : void 0,
321
327
  storageStatePath: this.options.storageStatePath,
322
328
  ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
323
- ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {}
329
+ ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
330
+ ...pinnedTabId ? { pinnedTabId } : {}
324
331
  });
325
332
  } catch (err) {
326
333
  const cause = err instanceof Error ? err.message : String(err);
@@ -342,8 +349,39 @@ Underlying launch error: ${cause}`
342
349
  tabId: tab.tabId,
343
350
  close: tab.close
344
351
  };
352
+ await this.verifyEmulation(tab.page);
345
353
  await this.afterLaunch(tab.page);
346
354
  }
355
+ /**
356
+ * Read back the requested device scale factor and colour scheme from the
357
+ * page itself, and refuse a launch whose page reports anything else.
358
+ */
359
+ async verifyEmulation(page) {
360
+ const wantDpr = this.options.deviceScaleFactor;
361
+ const wantScheme = this.options.colorScheme;
362
+ if (wantDpr === void 0 && wantScheme === void 0) return;
363
+ const seen = await page.evaluate(() => ({
364
+ dpr: window.devicePixelRatio,
365
+ dark: window.matchMedia("(prefers-color-scheme: dark)").matches
366
+ }));
367
+ const problems = [];
368
+ if (wantDpr !== void 0 && Math.abs(seen.dpr - wantDpr) > 1e-9) {
369
+ problems.push(`devicePixelRatio ${seen.dpr} (requested ${wantDpr})`);
370
+ }
371
+ if (wantScheme !== void 0 && seen.dark !== (wantScheme === "dark")) {
372
+ problems.push(
373
+ `prefers-color-scheme ${seen.dark ? "dark" : "light"} (requested ${wantScheme})`
374
+ );
375
+ }
376
+ if (problems.length === 0) return;
377
+ await this.onClose().catch(() => {
378
+ });
379
+ throw new WrapperTransportError(
380
+ "EMULATION_NOT_APPLIED",
381
+ `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.`,
382
+ { details: { requested: { deviceScaleFactor: wantDpr, colorScheme: wantScheme }, seen } }
383
+ );
384
+ }
347
385
  /**
348
386
  * Subclass hook: init-scripts to register on the browser context before the
349
387
  * first navigation (via `context.addInitScript`). Default: none. Injected
@@ -361,6 +399,13 @@ Underlying launch error: ${cause}`
361
399
  relayAuth() {
362
400
  return {};
363
401
  }
402
+ /**
403
+ * Subclass hook: the tab id this launch pinned, so the registration poll
404
+ * returns that tab only. Default: none. Injected mode returns `--tab-id`.
405
+ */
406
+ pinnedTabId() {
407
+ return void 0;
408
+ }
364
409
  /**
365
410
  * Subclass hook: run after launch + navigation, before `ready()` resolves.
366
411
  * Default: no-op. Injected mode overrides it to await the in-page runtime.
@@ -423,6 +468,14 @@ function loadInjectedBundle() {
423
468
  }
424
469
  var InjectedTransport = class extends HeadlessTransport {
425
470
  injected;
471
+ /**
472
+ * The pinned tab's key: 32 random bytes, base64url, generated once per
473
+ * transport (one launch) and kept in this process. The runner binds a tab
474
+ * that presents it to the key's digest, so the pin survives an origin hop
475
+ * while a page that merely learns the pinned id cannot attach as the tab.
476
+ * Lives only in the injected global — never in a storage artifact.
477
+ */
478
+ tabKey = crypto.randomBytes(32).toString("base64url");
426
479
  constructor(config, registry) {
427
480
  const raw = config.options ?? {};
428
481
  const headed = raw["headed"] === true;
@@ -457,9 +510,11 @@ var InjectedTransport = class extends HeadlessTransport {
457
510
  if (this.injected.appId) cfg.appId = this.injected.appId;
458
511
  if (this.injected.appName) cfg.appName = this.injected.appName;
459
512
  }
460
- if (this.injected.tabId) cfg.tabId = this.injected.tabId;
461
- if (this.injected.settleQuietMs !== void 0)
462
- cfg.settleQuietMs = this.injected.settleQuietMs;
513
+ if (this.injected.tabId) {
514
+ cfg.tabId = this.injected.tabId;
515
+ cfg.tabKey = this.tabKey;
516
+ }
517
+ if (this.injected.settleQuietMs !== void 0) cfg.settleQuietMs = this.injected.settleQuietMs;
463
518
  if (this.injected.settleTimeoutMs !== void 0)
464
519
  cfg.settleTimeoutMs = this.injected.settleTimeoutMs;
465
520
  if (this.injected.expectSelector !== void 0)
@@ -478,6 +533,9 @@ var InjectedTransport = class extends HeadlessTransport {
478
533
  ...this.injected.registrationMetadata?.userId ? { callerUserId: this.injected.registrationMetadata.userId } : {}
479
534
  };
480
535
  }
536
+ pinnedTabId() {
537
+ return this.injected.tabId;
538
+ }
481
539
  async buildInitScripts() {
482
540
  const scripts = [];
483
541
  const cfg = this.injectedConfig();