@qontinui/ui-bridge-wrapper 0.12.0 → 0.14.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.
@@ -35,7 +35,7 @@ import { type NetworkProfile } from './network-throttle.js';
35
35
  import { type CliActionError } from './action-outcome.js';
36
36
  import { type FrameColorScheme, type FrameError, type FrameRecord } from './frame-capture.js';
37
37
  import { type MatrixCell, type MatrixCellReport, type MatrixManifest, type MatrixViewport } from './capture-matrix.js';
38
- 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 A timed multi-frame capture (CLI-side too):\n\n captureTimeline {\"dir\":\"<dir>\",\"frames\":8,\"intervalMs\":250,\"reload\":false}\n Screenshot the page 'frames' times (1..120), one every 'intervalMs'\n (0..10000), into <dir>/frame-<k>.png \u2014 the loading-to-loaded timeline\n of a slot, NOT a lockstep pair (it records movement on purpose). <dir>\n must be empty or not exist. With \"reload\":true the clock starts at a\n fresh navigation commit, so frame 1 is the page before it painted; the\n reload drops any media override, and the action waits for the injected\n runtime to settle again ('readyTimeoutMs', default 30000) so the next\n step finds a drivable page. In --capture-matrix a relative <dir> lands\n inside each cell's directory.\n Result: {\"success\",\"dir\",\"reloaded\",\"intervalMs\",\"startedAt\",\n \"frames\":[{\"index\",\"path\",\"offsetMs\",\"capturedAt\",\"width\",\"height\"}],\n \"devicePixelRatio\",\"cssViewport\",\"colorScheme\",\"runtimeReady\",\"network\"}\n A frame that could not be taken carries \"error\" and fails the step.\n \"during\":{\"action\":\"mediaOverride\",\"payload\":{...}} runs that in-page\n action CONCURRENTLY with the frames, so the timeline shows the candidate\n ARRIVING (under --throttle, its slow-network load) while the override\n still confirms decode before it answers; its result rides on the line\n as \"during\" and a failed action fails the step. Not with \"reload\".\n\n Swapping an image in place (dev control, served by the injected runtime):\n\n mediaOverride {\"slotId\":\"hero\",\"src\":\"/candidate.png\"}\n mediaOverride {\"elementId\":\"img-logo\",\"srcset\":\"/c-1x.avif 1x, /c-2x.avif 2x\"}\n mediaOverride {\"slotId\":\"hero\",\"src\":\"/c.png\",\"sources\":[{\"type\":\"image/avif\",\"srcset\":\"/c.avif\"}]}\n mediaOverride {\"slotId\":\"banner\",\"backgroundImage\":\"/c.png\",\"ttlMs\":60000}\n Swap one slot's image, wait for decode() and confirm currentSrc before\n answering (an override that cannot be confirmed is rolled back and\n fails). Inside a <picture> every <source srcset> is replaced too.\n mediaOverrideRestore {\"overrideId\":\"mo-\u2026\"} (or {} for all)\n Put the originals back and verify each attribute reads back.\n mediaOverrideList {}\n What is still overridden \u2014 the proof the page ended restored.\n\n Hiding text for one frame (dev control, served by the injected runtime):\n\n textVisibility {\"hidden\":true,\"ttlMs\":30000}\n Make every glyph on the page transparent (colour, text fill, SVG text\n fill, text-shadow), with transitions off so the frame is not caught\n mid-fade; nothing moves, and currentColor borders and icons keep their\n colour. Capture frame A before and frame B after: inside a text\n element's box the two differ exactly where its glyphs paint. A TTL\n (default 30000 ms) restores the page if the run dies.\n textVisibility {\"hidden\":false}\n Restore exactly (the style attributes read back byte for byte);\n \"restore\":{\"verified\":true} is a clean restore.\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\nNetwork (every mode; applied to the page once it is ready, before any action):\n --throttle <profile> Emulate a slow network on the page (CDP\n Network.emulateNetworkConditions). <profile> is\n slow-3g (2000 ms, 400/400 kbit/s), fast-3g (563 ms,\n 1475/675 kbit/s), or latency=<ms>,down=<kbps>,up=<kbps>.\n It persists across reloads of the page, so a\n captureTimeline {\"reload\":true} loads throttled.\n --no-cache Disable the HTTP cache too (Network.setCacheDisabled):\n a warm cache would let a \"slow\" reload paint at once.\n What was applied is stamped as \"network\" on every\n captureTimeline result, each capture-matrix cell, and\n the relay info line; CDP has no getter, so the stamp\n says what Chromium ACCEPTED, and a refused command\n fails the run rather than measuring unthrottled.\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 # A candidate in its real slot, its slow-network load timeline, then restored\n ui-bridge-inject --url http://127.0.0.1:3000/ --throttle slow-3g --no-cache --exec 'mediaOverride {\"slotId\":\"hero\",\"src\":\"http://127.0.0.1:8080/cand.png\"}' --exec 'captureTimeline {\"dir\":\"./tl\",\"frames\":6,\"intervalMs\":200}' --exec 'mediaOverrideRestore {}' --exec 'mediaOverrideList {}'\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";
38
+ 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 Reading and acting on one element (in-page actions):\n\n getElement {\"id\":\"<id>\"}\n One element as a snapshot carries it: identity (id, type, tagName,\n label, role, accessibleName), \"state\", box (\"bbox\", \"visible\") and\n \"actions\" \u2014 the same object as the matching getControlSnapshot element,\n redaction included. {\"elementId\":\"<id>\"} is accepted too; given both,\n they must name the same element. Nothing settles first: run\n waitForSelector before it for a settled read. Beside the id it\n tolerates, and ignores, settleTimeout and skipSettle (it does not\n settle), targetTabId, and the WebSocket protocol's \"includeState\" (the\n state is always included); any other key is refused with\n INVALID_REQUEST. An unknown id, or one whose DOM node is gone, is a\n RETURNED ELEMENT_NOT_FOUND (an \"error\" line, exit 1), never a null\n result.\n\n getElementState {\"id\":\"<id>\"}\n The state alone (visible, enabled, focused, ariaPressed, value, ...).\n It reads \"id\" only, and an unknown id is a THROWN error (HANDLER_ERROR).\n\n executeElementAction {\"id\":\"<id>\",\"request\":{\"action\":\"click\"}}\n Act on one element. \"request\" holds the verb and the fields it reads\n (\"value\", \"text\", \"clear\", \"params\", \"fromSnapshotId\", ...). Two other\n spellings are accepted:\n {\"elementId\":\"<id>\",\"request\":{\"action\":\"focus\"}} \"elementId\" for \"id\"\n {\"id\":\"<id>\",\"action\":\"type\",\"text\":\"hi\"} flat: the payload,\n minus \"id\"/\"elementId\", IS the request\n No key BESIDE a \"request\" object is silently dropped: a top-level\n \"action\" or request field (\"value\", \"text\", ...) there must equal the\n same field inside \"request\" (an agreeing duplicate is accepted); one\n that is only at the top level, or at both levels with different\n values, is refused, and so are an \"id\" and an \"elementId\" that name\n different elements. settleTimeout, skipSettle and targetTabId stay\n allowed at the top level. The request fields themselves (the keys\n inside \"request\", or every key of a flat payload but the id) reach\n the action as sent, so a misspelt one there (\"txt\" for \"text\") is not\n caught. Every refused shape is a RETURNED INVALID_REQUEST (an \"error\"\n line, exit 1; never a thrown TypeError) whose message names the\n canonical shape\n {\"id\":\"<elementId>\",\"request\":{\"action\":\"<action>\", \u2026}}\n and both accepted spellings, and names keys and the kinds of values,\n never a value, with one exception: an \"id\" and an \"elementId\" that\n disagree are both named (they are the element ids the caller sent, and\n naming both is what makes the conflict diagnosable); \"error.details\"\n adds \"expectedPayload\" and \"receivedKeys\". A well-formed payload with\n an unknown verb is refused with UNSUPPORTED_ACTION, naming the\n accepted verbs.\n\n A timed multi-frame capture (CLI-side, like the waits):\n\n captureTimeline {\"dir\":\"<dir>\",\"frames\":8,\"intervalMs\":250,\"reload\":false}\n Screenshot the page 'frames' times (1..120), one every 'intervalMs'\n (0..10000), into <dir>/frame-<k>.png \u2014 the loading-to-loaded timeline\n of a slot, NOT a lockstep pair (it records movement on purpose). <dir>\n must be empty or not exist. With \"reload\":true the clock starts at a\n fresh navigation commit, and frame 1 is the first frame the page\n produced after that commit. Right after the commit the new document can\n have no compositor frame yet, and Chromium refuses the screenshot\n (\"Unable to capture screenshot\"); frame 1 retries that refusal every\n 16 ms until 'readyTimeoutMs' after the commit. A frame's \"offsetMs\" is\n when the screenshot that produced it was requested, so a frame 1 that\n had to wait reads the tens of ms its retries took, not 0. Under\n --throttle that first frame can still be the previous document's held\n frame; \"offsetMs\" dates it either way. Every other frame retries the\n same refusal only while the retry falls due before the next frame's\n due time (\"intervalMs\":0 is one attempt), so retries never take a\n later frame's slot; an attempt still under way when the next frame\n falls due delays it by what is left of that attempt, as any slow\n screenshot does. No other error is retried. A frame that took more\n than one attempt says how many in \"attempts\". The\n reload drops any media override, and the action waits for the injected\n runtime to settle again ('readyTimeoutMs', default 30000) so the next\n step finds a drivable page. In --capture-matrix a relative <dir> lands\n inside each cell's directory.\n Result: {\"success\",\"dir\",\"reloaded\",\"intervalMs\",\"startedAt\",\n \"frames\":[{\"index\",\"path\",\"offsetMs\",\"capturedAt\",\"width\",\"height\",\n \"attempts\" (only when > 1)}],\n \"devicePixelRatio\",\"cssViewport\",\"colorScheme\",\"runtimeReady\",\"network\"}\n A frame that could not be taken, or was still refused at its deadline,\n carries \"error\" and fails the step.\n \"during\":{\"action\":\"mediaOverride\",\"payload\":{...}} runs that in-page\n action CONCURRENTLY with the frames, so the timeline shows the candidate\n ARRIVING (under --throttle, its slow-network load) while the override\n still confirms decode before it answers; its result rides on the line\n as \"during\" and a failed action fails the step. Not with \"reload\".\n An image URL this document already decoded is NOT observed arriving:\n Chromium 158 serves it again with no request, even under --no-cache\n (Chromium 147 refetched it); only a new URL or a reload reaches the\n network. So give the candidate a URL the document has not decoded,\n such as a per-candidate query string (\"cand.png?2\").\n\n Swapping an image in place (dev control, served by the injected runtime):\n\n mediaOverride {\"slotId\":\"hero\",\"src\":\"/candidate.png\"}\n mediaOverride {\"elementId\":\"img-logo\",\"srcset\":\"/c-1x.avif 1x, /c-2x.avif 2x\"}\n mediaOverride {\"slotId\":\"hero\",\"src\":\"/c.png\",\"sources\":[{\"type\":\"image/avif\",\"srcset\":\"/c.avif\"}]}\n mediaOverride {\"slotId\":\"banner\",\"backgroundImage\":\"/c.png\",\"ttlMs\":60000}\n Swap one slot's image, wait for decode() and confirm currentSrc before\n answering (an override that cannot be confirmed is rolled back and\n fails). Inside a <picture> every <source srcset> is replaced too.\n On Chromium 158 a candidate URL this document already decoded is\n served with no request, even under --no-cache: only a new URL or a\n reload reaches the network, so a slow-network candidate needs its own\n URL (a per-candidate query string).\n mediaOverrideRestore {\"overrideId\":\"mo-\u2026\"} (or {} for all)\n Put the originals back and verify each attribute reads back.\n mediaOverrideList {}\n What is still overridden \u2014 the proof the page ended restored.\n\n Hiding text for one frame (dev control, served by the injected runtime):\n\n textVisibility {\"hidden\":true,\"ttlMs\":30000}\n Make every glyph on the page transparent (colour, text fill, SVG text\n fill, text-shadow), with transitions off so the frame is not caught\n mid-fade; nothing moves, and currentColor borders and icons keep their\n colour. Capture frame A before and frame B after: inside a text\n element's box the two differ exactly where its glyphs paint. A TTL\n (default 30000 ms) restores the page if the run dies.\n textVisibility {\"hidden\":false}\n Restore exactly (the style attributes read back byte for byte);\n \"restore\":{\"verified\":true} is a clean restore.\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\nNetwork (every mode; applied to the page once it is ready, before any action):\n --throttle <profile> Emulate a slow network on the page (CDP\n Network.emulateNetworkConditions). <profile> is\n slow-3g (2000 ms, 400/400 kbit/s), fast-3g (563 ms,\n 1475/675 kbit/s), or latency=<ms>,down=<kbps>,up=<kbps>.\n It persists across reloads of the page, so a\n captureTimeline {\"reload\":true} loads throttled.\n --no-cache Disable the HTTP cache too (Network.setCacheDisabled):\n a warm cache would let a \"slow\" reload paint at once.\n It does NOT reach the document's in-memory image\n cache: on Chromium 158 a URL this page already\n decoded is answered at once, throttle or not -- give\n a repeated mediaOverride candidate its own URL\n (e.g. ?2).\n What was applied is stamped as \"network\" on every\n captureTimeline result, each capture-matrix cell, and\n the relay info line; CDP has no getter, so the stamp\n says what Chromium ACCEPTED, and a refused command\n fails the run rather than measuring unthrottled.\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 # A candidate in its real slot, its slow-network load timeline, then restored\n ui-bridge-inject --url http://127.0.0.1:3000/ --throttle slow-3g --no-cache --exec 'mediaOverride {\"slotId\":\"hero\",\"src\":\"http://127.0.0.1:8080/cand.png\"}' --exec 'captureTimeline {\"dir\":\"./tl\",\"frames\":6,\"intervalMs\":200}' --exec 'mediaOverrideRestore {}' --exec 'mediaOverrideList {}'\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";
39
39
  /** A single Variant-A action to execute. */
40
40
  export interface ExecAction {
41
41
  action: string;
@@ -1 +1 @@
1
- {"version":3,"file":"inject-cli.d.ts","sourceRoot":"","sources":["../src/inject-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAIL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAQL,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEf,KAAK,WAAW,EAEjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAEnB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,KAAK,kgkBA6QjB,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,wFAAwF;IACxF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,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;;;OAGG;IACH,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,mFAAmF;IACnF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qEAAqE;IACrE,YAAY,EAAE,gBAAgB,EAAE,CAAC;IACjC,+EAA+E;IAC/E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yEAAyE;IACzE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8FAA8F;IAC9F,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,6CAA6C;IAC7C,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,+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,OAAO,EAAE,iBAAiB,EAAE,CAAC;AA2B7B;;;;GAIG;AACH,eAAO,MAAM,OAAO,IAAI,CAAC;AAazB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAazD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ5C;AAED,wCAAwC;AACxC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAG9D;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CA0PvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA4DtD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAG3E;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAmC,CAAC;AAErF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAsBjG;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,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,OAAO,GAAG,YAAY,CAAC,GAAG;IAC1F,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;CAC1B,CA8BA;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,GAAG,eAAe,CAAC,EACxD,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACjD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GACjC,MAAM,GAAG,IAAI,CAgBf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBlF;AAgBD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,UAAU,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,uCAAwC,CAAC;AAEtE,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,wDAAyD,CAAC;AAC3F,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD,kFAAkF;AAClF,eAAO,MAAM,YAAY,SAAU,CAAC;AAEpC,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAUD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,sBAAsB,CA4BpF;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CASlE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI,CAMxE;AAUD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,CAAC;CAChF,GAAG,IAAI,CAmBP;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,CAAA;CAAE,EAC7F,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,SAAS,CAAC,GAChD,IAAI,CAUN;AA2ID;;;;GAIG;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,+BAA+B,CAAC;AAEjE,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,eAAe,EAAE;QAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,CAAC;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,IAAI,CAoBrF;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,SAAS,UAAU,EAAE,EAC9B,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,EACjE,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GACjD,OAAO,CAAC,OAAO,CAAC,CA4ClB;AA0KD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAoBtD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,MAAM,GAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,KAAK,IAAe,GACrE,OAAO,CAAC,cAAc,CAAC,CAwCzB"}
1
+ {"version":3,"file":"inject-cli.d.ts","sourceRoot":"","sources":["../src/inject-cli.ts"],"names":[],"mappings":"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"}
@@ -4,48 +4,14 @@
4
4
  var fs = require('fs');
5
5
  var module$1 = require('module');
6
6
  var crypto = require('crypto');
7
- var ui_bridge_cli_args_star = require('@qontinui/ui-bridge-cli-args');
8
7
 
9
8
  var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
10
- function _interopNamespace(e) {
11
- if (e && e.__esModule) return e;
12
- var n = Object.create(null);
13
- if (e) {
14
- Object.keys(e).forEach(function (k) {
15
- if (k !== 'default') {
16
- var d = Object.getOwnPropertyDescriptor(e, k);
17
- Object.defineProperty(n, k, d.get ? d : {
18
- enumerable: true,
19
- get: function () { return e[k]; }
20
- });
21
- }
22
- });
23
- }
24
- n.default = e;
25
- return Object.freeze(n);
26
- }
27
-
28
- var ui_bridge_cli_args_star__namespace = /*#__PURE__*/_interopNamespace(ui_bridge_cli_args_star);
29
-
30
- var __defProp = Object.defineProperty;
31
- var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
32
- var __getOwnPropNames = Object.getOwnPropertyNames;
33
- var __hasOwnProp = Object.prototype.hasOwnProperty;
34
9
  var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
35
10
  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
36
11
  }) : x)(function(x) {
37
12
  if (typeof require !== "undefined") return require.apply(this, arguments);
38
13
  throw Error('Dynamic require of "' + x + '" is not supported');
39
14
  });
40
- var __copyProps = (to, from, except, desc) => {
41
- if (from && typeof from === "object" || typeof from === "function") {
42
- for (let key of __getOwnPropNames(from))
43
- if (!__hasOwnProp.call(to, key) && key !== except)
44
- __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
45
- }
46
- return to;
47
- };
48
- var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget);
49
15
 
50
16
  // src/types.ts
51
17
  var WrapperTransportError = class extends Error {
@@ -279,9 +245,60 @@ var HeadlessTransport = class extends BaseTransport {
279
245
  userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
280
246
  forwardConsole: typeof raw["forwardConsole"] === "boolean" ? raw["forwardConsole"] : void 0,
281
247
  launchArgs: Array.isArray(raw["launchArgs"]) && raw["launchArgs"].every((a) => typeof a === "string") ? raw["launchArgs"] : void 0,
282
- storageStatePath: typeof raw["storageStatePath"] === "string" ? raw["storageStatePath"] : void 0
248
+ storageStatePath: typeof raw["storageStatePath"] === "string" ? raw["storageStatePath"] : void 0,
249
+ ...this.parseContextOptions(raw)
283
250
  };
284
251
  }
252
+ /**
253
+ * `recordHar`, `recordVideo`, `serviceWorkers` and `initRouter`. Unlike the display
254
+ * options above, a malformed value is REFUSED rather than dropped: dropping
255
+ * `recordHar` would leave a caller waiting for an archive that is never
256
+ * written, and dropping `initRouter` would let requests it meant to answer
257
+ * reach the network.
258
+ */
259
+ parseContextOptions(raw) {
260
+ const out = {};
261
+ const invalid = (what) => new WrapperTransportError("INVALID_CONFIG", `Transport kind '${this.kind}': ${what}`);
262
+ const har = raw["recordHar"];
263
+ if (har !== void 0) {
264
+ if (typeof har !== "object" || har === null || typeof har.path !== "string" || har.path.length === 0) {
265
+ throw invalid("options.recordHar must be an object with a non-empty string `path`");
266
+ }
267
+ out.recordHar = har;
268
+ }
269
+ const video = raw["recordVideo"];
270
+ if (video !== void 0) {
271
+ if (typeof video !== "object" || video === null || typeof video.dir !== "string" || video.dir.length === 0) {
272
+ throw invalid("options.recordVideo must be an object with a non-empty string `dir`");
273
+ }
274
+ const size = video.size;
275
+ if (size !== void 0) {
276
+ const positiveInt = (n) => typeof n === "number" && Number.isInteger(n) && n > 0;
277
+ const s = size;
278
+ if (typeof size !== "object" || s === null || !positiveInt(s.width) || !positiveInt(s.height)) {
279
+ throw invalid(
280
+ "options.recordVideo.size must be { width, height } with positive integer sides"
281
+ );
282
+ }
283
+ }
284
+ out.recordVideo = video;
285
+ }
286
+ const sw = raw["serviceWorkers"];
287
+ if (sw !== void 0) {
288
+ if (sw !== "allow" && sw !== "block") {
289
+ throw invalid(`options.serviceWorkers must be 'allow' or 'block' (got ${String(sw)})`);
290
+ }
291
+ out.serviceWorkers = sw;
292
+ }
293
+ const router = raw["initRouter"];
294
+ if (router !== void 0) {
295
+ if (typeof router !== "function") {
296
+ throw invalid("options.initRouter must be a function (context) => void | Promise<void>");
297
+ }
298
+ out.initRouter = router;
299
+ }
300
+ return out;
301
+ }
285
302
  async onReady() {
286
303
  let launchHeadlessTab;
287
304
  const headlessSpecifier = "@qontinui/ui-bridge-headless";
@@ -309,6 +326,13 @@ Underlying import error: ${cause}`
309
326
  const initScripts = await this.buildInitScripts();
310
327
  const relayAuth = this.relayAuth();
311
328
  const pinnedTabId = this.pinnedTabId();
329
+ const { recordHar, recordVideo, serviceWorkers, initRouter: callerRouter } = this.options;
330
+ const contextOptionsRequested = recordHar !== void 0 || recordVideo !== void 0 || serviceWorkers === "block" || callerRouter !== void 0;
331
+ let routerCalled = false;
332
+ const initRouter = contextOptionsRequested || serviceWorkers !== void 0 ? async (context) => {
333
+ routerCalled = true;
334
+ if (callerRouter) await callerRouter(context);
335
+ } : void 0;
312
336
  let tab;
313
337
  try {
314
338
  tab = await launchHeadlessTab({
@@ -327,7 +351,11 @@ Underlying import error: ${cause}`
327
351
  storageStatePath: this.options.storageStatePath,
328
352
  ...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
329
353
  ...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
330
- ...pinnedTabId ? { pinnedTabId } : {}
354
+ ...pinnedTabId ? { pinnedTabId } : {},
355
+ ...recordHar !== void 0 ? { recordHar } : {},
356
+ ...recordVideo !== void 0 ? { recordVideo } : {},
357
+ ...serviceWorkers !== void 0 ? { serviceWorkers } : {},
358
+ ...initRouter ? { initRouter } : {}
331
359
  });
332
360
  } catch (err) {
333
361
  const cause = err instanceof Error ? err.message : String(err);
@@ -349,6 +377,24 @@ Underlying launch error: ${cause}`
349
377
  tabId: tab.tabId,
350
378
  close: tab.close
351
379
  };
380
+ if (contextOptionsRequested && !routerCalled) {
381
+ await this.onClose().catch(() => {
382
+ });
383
+ throw new WrapperTransportError(
384
+ "CONTEXT_OPTIONS_NOT_APPLIED",
385
+ `The installed '@qontinui/ui-bridge-headless' peer launched the tab without calling initRouter, so it predates the recordHar / recordVideo / serviceWorkers / initRouter passthrough (0.8.0, ui-bridge#381) and ignored them: no HAR or video would be written and no route installed. Upgrade it to 0.8.0 or later.`,
386
+ {
387
+ details: {
388
+ requested: {
389
+ recordHar: recordHar !== void 0,
390
+ recordVideo: recordVideo !== void 0,
391
+ serviceWorkers: serviceWorkers ?? null,
392
+ initRouter: callerRouter !== void 0
393
+ }
394
+ }
395
+ }
396
+ );
397
+ }
352
398
  await this.verifyEmulation(tab.page);
353
399
  await this.afterLaunch(tab.page);
354
400
  }
@@ -695,6 +741,7 @@ var InjectedTransport = class extends HeadlessTransport {
695
741
  execute,
696
742
  find: (criteria) => execute("find", criteria ?? {}),
697
743
  act: (id, request) => execute("executeElementAction", { id, request }),
744
+ element: (id) => execute("getElement", { id }),
698
745
  snapshot: (options) => execute("getControlSnapshot", options ?? {}),
699
746
  assert: (spec) => execute("aiAssert", spec)
700
747
  };
@@ -958,9 +1005,88 @@ function mergeMultiOriginSessionStorageIntoArtifact(artifact, map) {
958
1005
  return artifact;
959
1006
  }
960
1007
 
961
- // src/cli-args.ts
962
- var cli_args_exports = {};
963
- __reExport(cli_args_exports, ui_bridge_cli_args_star__namespace);
1008
+ // ../ui-bridge-cli-args/dist/index.js
1009
+ var COMMON_FLAGS = /* @__PURE__ */ new Set(["--help", "-h", "--quiet"]);
1010
+ function isFlagShaped(value) {
1011
+ return value.startsWith("--");
1012
+ }
1013
+ function consumeValue(flag, raw, error) {
1014
+ if (raw === void 0) return null;
1015
+ if (isFlagShaped(raw)) {
1016
+ throw error(
1017
+ `${flag} expects a value but got the flag '${raw}' \u2014 did you omit ${flag}'s argument?`
1018
+ );
1019
+ }
1020
+ return raw;
1021
+ }
1022
+ function rejectEmptyValue(flag, value, error) {
1023
+ if (value !== null && value.trim() === "") {
1024
+ throw error(
1025
+ `${flag} was given an empty value \u2014 omit the flag to use its default, or pass a non-empty value`
1026
+ );
1027
+ }
1028
+ return value;
1029
+ }
1030
+ function parsePositiveInt(flag, raw, error) {
1031
+ const n = raw !== null && /^\d+$/.test(raw) ? Number(raw) : NaN;
1032
+ if (!Number.isSafeInteger(n) || n <= 0) {
1033
+ throw error(`${flag} expects a positive integer (got ${raw ?? "<missing>"})`);
1034
+ }
1035
+ return n;
1036
+ }
1037
+ var ArgReader = class {
1038
+ argv;
1039
+ error;
1040
+ valueFlags;
1041
+ /**
1042
+ * @param argv Already sliced past `node script`.
1043
+ * @param known All flags the bin recognizes (union the bin's set with {@link COMMON_FLAGS}).
1044
+ * @param error Factory producing the bin's domain error type.
1045
+ * @param valueFlags The flags that take a value. The token after one is that
1046
+ * flag's value, never a flag of its own, so `--success -h`
1047
+ * does not also ask for help. Without it, {@link has} cannot
1048
+ * tell a value from a flag.
1049
+ */
1050
+ constructor(argv, known, error, valueFlags = /* @__PURE__ */ new Set()) {
1051
+ this.argv = argv;
1052
+ this.error = error;
1053
+ this.valueFlags = valueFlags;
1054
+ for (const arg of argv) {
1055
+ if (isFlagShaped(arg) && !known.has(arg)) {
1056
+ throw error(`Unknown flag: ${arg}`);
1057
+ }
1058
+ }
1059
+ }
1060
+ /** True if `name` appears as a bare boolean flag, not as a value-flag's value. */
1061
+ has(name) {
1062
+ for (let i = 0; i < this.argv.length; i++) {
1063
+ if (this.valueFlags.has(this.argv[i])) {
1064
+ i++;
1065
+ continue;
1066
+ }
1067
+ if (this.argv[i] === name) return true;
1068
+ }
1069
+ return false;
1070
+ }
1071
+ /**
1072
+ * Value following the value-flag `name`, or `null` when the flag is absent OR
1073
+ * has no following token (the caller defaults it). Throws when the following
1074
+ * token is flag-shaped — the swallow this kit exists to kill. Delegates to
1075
+ * {@link consumeValue} so the guard (and its message) live in exactly one
1076
+ * place for both the indexOf-style and switch-style parsers.
1077
+ */
1078
+ value(name) {
1079
+ const i = this.argv.indexOf(name);
1080
+ if (i < 0 || i + 1 >= this.argv.length) return null;
1081
+ return consumeValue(name, this.argv[i + 1], this.error);
1082
+ }
1083
+ };
1084
+ function makeLogger(prefix, quiet) {
1085
+ if (quiet) return () => {
1086
+ };
1087
+ return (m) => process.stderr.write(`${prefix} ${m}
1088
+ `) ;
1089
+ }
964
1090
 
965
1091
  // src/action-outcome.ts
966
1092
  function isRecord(v) {
@@ -1166,22 +1292,19 @@ var LoginCliArgError = class extends Error {
1166
1292
  };
1167
1293
  function parseArgs(argv) {
1168
1294
  const mkError = (m) => new LoginCliArgError(m);
1169
- const reader = new cli_args_exports.ArgReader(argv, KNOWN_FLAGS, mkError);
1295
+ const reader = new ArgReader(argv, KNOWN_FLAGS, mkError, VALUE_FLAGS);
1170
1296
  const valueOf = (name) => reader.value(name);
1171
1297
  const has = (name) => reader.has(name);
1172
1298
  const help = has("--help") || has("-h");
1173
1299
  const timeoutRaw = valueOf("--timeout");
1174
- const timeoutMs = timeoutRaw === null ? 6e4 : Number.parseInt(timeoutRaw, 10);
1175
- if (!help && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
1176
- throw new LoginCliArgError(`--timeout expects a positive integer (got ${timeoutRaw})`);
1177
- }
1300
+ const timeoutMs = timeoutRaw === null || help ? 6e4 : parsePositiveInt("--timeout", timeoutRaw, mkError);
1178
1301
  const args = {
1179
- url: (0, cli_args_exports.rejectEmptyValue)("--url", valueOf("--url"), mkError) ?? "https://qontinui.io/login",
1302
+ url: rejectEmptyValue("--url", valueOf("--url"), mkError) ?? "https://qontinui.io/login",
1180
1303
  email: valueOf("--email") ?? process.env.UIB_LOGIN_EMAIL ?? "",
1181
1304
  password: valueOf("--password") ?? process.env.UIB_LOGIN_PASSWORD ?? "",
1182
1305
  // An EMPTY --success would make `landingPath.includes('')` true on any
1183
1306
  // landing — ok:true while parked on the login page. Reject it.
1184
- success: (0, cli_args_exports.rejectEmptyValue)("--success", valueOf("--success"), mkError) ?? "/dashboard",
1307
+ success: rejectEmptyValue("--success", valueOf("--success"), mkError) ?? "/dashboard",
1185
1308
  timeoutMs,
1186
1309
  headed: has("--headed"),
1187
1310
  postClick: valueOf("--post-login-click"),
@@ -1196,21 +1319,19 @@ function parseArgs(argv) {
1196
1319
  validateArgs(args);
1197
1320
  return args;
1198
1321
  }
1199
- var KNOWN_FLAGS = /* @__PURE__ */ new Set([
1322
+ var VALUE_FLAGS = /* @__PURE__ */ new Set([
1200
1323
  "--url",
1201
1324
  "--email",
1202
1325
  "--password",
1203
1326
  "--success",
1204
1327
  "--timeout",
1205
- "--headed",
1206
1328
  "--post-login-click",
1207
1329
  "--expect-text",
1208
1330
  "--scroll-to",
1209
1331
  "--screenshot",
1210
- "--storage-state-out",
1211
- "--keep-open",
1212
- ...cli_args_exports.COMMON_FLAGS
1332
+ "--storage-state-out"
1213
1333
  ]);
1334
+ var KNOWN_FLAGS = /* @__PURE__ */ new Set([...VALUE_FLAGS, "--headed", "--keep-open", ...COMMON_FLAGS]);
1214
1335
  function validateArgs(args) {
1215
1336
  if (args.help) return;
1216
1337
  if (!/^https?:\/\//i.test(args.url)) {
@@ -1252,7 +1373,7 @@ ${USAGE}`);
1252
1373
  screenshotPath,
1253
1374
  storageStateOut
1254
1375
  } = args;
1255
- const log = (0, cli_args_exports.makeLogger)("[login-web]", args.quiet);
1376
+ const log = makeLogger("[login-web]", args.quiet);
1256
1377
  const transport = createTransport({
1257
1378
  kind: "injected",
1258
1379
  options: { targetUrl: url, waitForSettle: false, readyTimeoutMs: 45e3, headed }