@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.
@@ -10,18 +10,30 @@
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.
17
+ * An action that FAILS — whether it threw or merely returned
18
+ * `{ success: false }` — puts a `{ code, message, source, details }` object
19
+ * on that line's `error` key and makes the process exit 1. See
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`).
17
23
  * - Variant B (relay, DEFAULT): no exec actions → register as a relay tab
18
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`).
19
28
  *
20
29
  * The arg parsing, validation, option building, and mode selection are exported
21
30
  * pure functions so they can be unit-tested without spawning a browser or
22
31
  * calling `main()`.
23
32
  */
24
- 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\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";
25
37
  /** A single Variant-A action to execute. */
26
38
  export interface ExecAction {
27
39
  action: string;
@@ -32,6 +44,8 @@ export interface InjectCliArgs {
32
44
  url: string;
33
45
  relay: string | null;
34
46
  authToken: string | null;
47
+ /** Path to a file holding the bearer token (trimmed on read); see --auth-token-file. */
48
+ authTokenFile: string | null;
35
49
  registrationMetadata: {
36
50
  userId: string;
37
51
  sessionId: string;
@@ -46,8 +60,19 @@ export interface InjectCliArgs {
46
60
  appId: string | null;
47
61
  appName: string | null;
48
62
  tabId: string | null;
49
- viewportWidth: number | null;
50
- 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;
51
76
  /** Path to a Playwright storageState JSON file to seed the context (from --storage-state). */
52
77
  storageState: string | null;
53
78
  /** Extra Chromium launch args collected from --launch-arg flags (in order). */
@@ -66,6 +91,27 @@ export interface InjectCliArgs {
66
91
  export declare class InjectCliArgError extends Error {
67
92
  constructor(message: string);
68
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;
69
115
  /**
70
116
  * Parse `argv` (already sliced past `node script`) into validated args.
71
117
  * Throws {@link InjectCliArgError} on bad input (no `process.exit` — testable).
@@ -77,10 +123,22 @@ export declare function parseArgs(argv: string[]): InjectCliArgs;
77
123
  */
78
124
  export declare function validateArgs(args: InjectCliArgs): void;
79
125
  /**
80
- * Mode selection: any `--exec`/`--exec-stdin` → one-shot exec (Variant A);
81
- * 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).
82
129
  */
83
- 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;
84
142
  /**
85
143
  * Chromium feature flags that must be DISABLED for an https page to fetch a
86
144
  * loopback (local-network) relay. Chromium's Local Network Access checks
@@ -105,9 +163,151 @@ export declare function buildLaunchArgs(args: Pick<InjectCliArgs, 'url' | 'relay
105
163
  launchArgs: string[];
106
164
  lnaAutoAppended: boolean;
107
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;
108
174
  /**
109
175
  * Build the `options` object for `createTransport({ kind: 'injected', options })`.
110
176
  * Only includes keys the user provided; `targetUrl` is always present.
111
177
  */
112
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>;
113
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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,eAAO,MAAM,KAAK,2sJAyEjB,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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"}
@@ -1,9 +1,9 @@
1
1
  #!/usr/bin/env node
2
2
  'use strict';
3
3
 
4
- var url = require('url');
5
4
  var fs = require('fs');
6
5
  var module$1 = require('module');
6
+ var crypto = require('crypto');
7
7
  var ui_bridge_cli_args_star = require('@qontinui/ui-bridge-cli-args');
8
8
 
9
9
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -31,6 +31,12 @@ var __defProp = Object.defineProperty;
31
31
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
32
32
  var __getOwnPropNames = Object.getOwnPropertyNames;
33
33
  var __hasOwnProp = Object.prototype.hasOwnProperty;
34
+ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
35
+ get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
36
+ }) : x)(function(x) {
37
+ if (typeof require !== "undefined") return require.apply(this, arguments);
38
+ throw Error('Dynamic require of "' + x + '" is not supported');
39
+ });
34
40
  var __copyProps = (to, from, except, desc) => {
35
41
  if (from && typeof from === "object" || typeof from === "function") {
36
42
  for (let key of __getOwnPropNames(from))
@@ -266,6 +272,8 @@ var HeadlessTransport = class extends BaseTransport {
266
272
  targetUrl,
267
273
  viewportWidth: typeof raw["viewportWidth"] === "number" ? raw["viewportWidth"] : void 0,
268
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,
269
277
  uiBridgeBase: typeof raw["uiBridgeBase"] === "string" ? raw["uiBridgeBase"] : void 0,
270
278
  waitForUiBridgeMs: typeof raw["waitForUiBridgeMs"] === "number" ? raw["waitForUiBridgeMs"] : void 0,
271
279
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
@@ -300,6 +308,7 @@ Underlying import error: ${cause}`
300
308
  }
301
309
  const initScripts = await this.buildInitScripts();
302
310
  const relayAuth = this.relayAuth();
311
+ const pinnedTabId = this.pinnedTabId();
303
312
  let tab;
304
313
  try {
305
314
  tab = await launchHeadlessTab({
@@ -309,13 +318,16 @@ Underlying import error: ${cause}`
309
318
  waitForUiBridgeMs: this.options.waitForUiBridgeMs,
310
319
  viewportWidth: this.options.viewportWidth,
311
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 } : {},
312
323
  userAgent: this.options.userAgent,
313
324
  forwardConsole: this.options.forwardConsole,
314
325
  initScripts: initScripts.length > 0 ? initScripts : void 0,
315
326
  launchArgs: this.options.launchArgs && this.options.launchArgs.length > 0 ? this.options.launchArgs : void 0,
316
327
  storageStatePath: this.options.storageStatePath,
317
328
  ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
318
- ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {}
329
+ ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
330
+ ...pinnedTabId ? { pinnedTabId } : {}
319
331
  });
320
332
  } catch (err) {
321
333
  const cause = err instanceof Error ? err.message : String(err);
@@ -337,8 +349,39 @@ Underlying launch error: ${cause}`
337
349
  tabId: tab.tabId,
338
350
  close: tab.close
339
351
  };
352
+ await this.verifyEmulation(tab.page);
340
353
  await this.afterLaunch(tab.page);
341
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
+ }
342
385
  /**
343
386
  * Subclass hook: init-scripts to register on the browser context before the
344
387
  * first navigation (via `context.addInitScript`). Default: none. Injected
@@ -356,6 +399,13 @@ Underlying launch error: ${cause}`
356
399
  relayAuth() {
357
400
  return {};
358
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
+ }
359
409
  /**
360
410
  * Subclass hook: run after launch + navigation, before `ready()` resolves.
361
411
  * Default: no-op. Injected mode overrides it to await the in-page runtime.
@@ -418,6 +468,14 @@ function loadInjectedBundle() {
418
468
  }
419
469
  var InjectedTransport = class extends HeadlessTransport {
420
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");
421
479
  constructor(config, registry) {
422
480
  const raw = config.options ?? {};
423
481
  const headed = raw["headed"] === true;
@@ -452,9 +510,11 @@ var InjectedTransport = class extends HeadlessTransport {
452
510
  if (this.injected.appId) cfg.appId = this.injected.appId;
453
511
  if (this.injected.appName) cfg.appName = this.injected.appName;
454
512
  }
455
- if (this.injected.tabId) cfg.tabId = this.injected.tabId;
456
- if (this.injected.settleQuietMs !== void 0)
457
- 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;
458
518
  if (this.injected.settleTimeoutMs !== void 0)
459
519
  cfg.settleTimeoutMs = this.injected.settleTimeoutMs;
460
520
  if (this.injected.expectSelector !== void 0)
@@ -473,6 +533,9 @@ var InjectedTransport = class extends HeadlessTransport {
473
533
  ...this.injected.registrationMetadata?.userId ? { callerUserId: this.injected.registrationMetadata.userId } : {}
474
534
  };
475
535
  }
536
+ pinnedTabId() {
537
+ return this.injected.tabId;
538
+ }
476
539
  async buildInitScripts() {
477
540
  const scripts = [];
478
541
  const cfg = this.injectedConfig();
@@ -896,6 +959,14 @@ function mergeMultiOriginSessionStorageIntoArtifact(artifact, map) {
896
959
  var cli_args_exports = {};
897
960
  __reExport(cli_args_exports, ui_bridge_cli_args_star__namespace);
898
961
 
962
+ // src/action-outcome.ts
963
+ function isRecord(v) {
964
+ return typeof v === "object" && v !== null && !Array.isArray(v);
965
+ }
966
+ function isReturnedFailure(result) {
967
+ return isRecord(result) && result.success === false;
968
+ }
969
+
899
970
  // src/login-drive.ts
900
971
  var isCognito = (u) => /auth\.qontinui\.io|amazoncognito\.com|\/oauth2\//i.test(u);
901
972
  var pathOf = (u) => {
@@ -1201,7 +1272,8 @@ ${USAGE}`);
1201
1272
  });
1202
1273
  let snap = null;
1203
1274
  try {
1204
- snap = await ctx.snapshot();
1275
+ const raw = await ctx.snapshot();
1276
+ if (!isReturnedFailure(raw)) snap = raw;
1205
1277
  } catch {
1206
1278
  }
1207
1279
  const uiBridgeRoute = snap?.route ?? null;
@@ -1339,13 +1411,7 @@ ${USAGE}`);
1339
1411
  });
1340
1412
  process.exit(code);
1341
1413
  }
1342
- var isMain = (() => {
1343
- try {
1344
- return process.argv[1] === url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('login-web-cli.cjs', document.baseURI).href)));
1345
- } catch {
1346
- return false;
1347
- }
1348
- })();
1414
+ var isMain = typeof __require !== "undefined" && typeof module !== "undefined" && __require.main === module;
1349
1415
  if (isMain) {
1350
1416
  void main().catch((err) => {
1351
1417
  const msg = err instanceof Error ? err.message : String(err);