@qontinui/ui-bridge-wrapper 0.9.0 → 0.11.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.
@@ -30,10 +30,12 @@
30
30
  * pure functions so they can be unit-tested without spawning a browser or
31
31
  * calling `main()`.
32
32
  */
33
+ import { InjectCliArgError } from './inject-cli-errors.js';
34
+ import { type NetworkProfile } from './network-throttle.js';
33
35
  import { type CliActionError } from './action-outcome.js';
34
36
  import { type FrameColorScheme, type FrameError, type FrameRecord } from './frame-capture.js';
35
37
  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";
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";
37
39
  /** A single Variant-A action to execute. */
38
40
  export interface ExecAction {
39
41
  action: string;
@@ -75,6 +77,10 @@ export interface InjectCliArgs {
75
77
  captureMatrix: string | null;
76
78
  /** Path to a Playwright storageState JSON file to seed the context (from --storage-state). */
77
79
  storageState: string | null;
80
+ /** `--throttle` network profile, or null. */
81
+ throttle: NetworkProfile | null;
82
+ /** `--no-cache`: also disable the HTTP cache. */
83
+ noCache: boolean;
78
84
  /** Extra Chromium launch args collected from --launch-arg flags (in order). */
79
85
  launchArgs: string[];
80
86
  /** Variant-A actions collected from --exec flags (in order). */
@@ -84,13 +90,7 @@ export interface InjectCliArgs {
84
90
  quiet: boolean;
85
91
  help: boolean;
86
92
  }
87
- /**
88
- * Error raised by `parseArgs`/validation. The thin CLI wrapper catches this and
89
- * calls `die()`; tests assert on it WITHOUT triggering `process.exit`.
90
- */
91
- export declare class InjectCliArgError extends Error {
92
- constructor(message: string);
93
- }
93
+ export { InjectCliArgError };
94
94
  /**
95
95
  * Upper bound on `--dpr`. A typo such as `--dpr 20` would otherwise ask
96
96
  * Chromium for a 25600-pixel-wide frame; the densest shipping displays are
@@ -246,6 +246,19 @@ export declare function validateWaitActions(actions: readonly ExecAction[]): voi
246
246
  export declare function registerWaitActions(registrar: {
247
247
  register(action: string, fn: (params: unknown, ctx: unknown) => unknown): void;
248
248
  }): void;
249
+ /**
250
+ * The private action id the network emulation is applied under, against the
251
+ * transport context's page. A double-underscore id: never an in-page action.
252
+ */
253
+ export declare const APPLY_NETWORK_ACTION = "__inject_cli_apply_network";
254
+ /**
255
+ * Register the network emulation (`--throttle` / `--no-cache`) under
256
+ * {@link APPLY_NETWORK_ACTION}. Dispatched once, right after `ready()`, so
257
+ * every exec step and every frame runs under it.
258
+ */
259
+ export declare function registerNetworkEmulation(registrar: {
260
+ register(action: string, fn: (params: unknown, ctx: unknown) => unknown): void;
261
+ }, args: Pick<InjectCliArgs, 'throttle' | 'noCache'>): void;
249
262
  /**
250
263
  * ---------------------------------------------------------------------------
251
264
  * Frame-paired snapshots
@@ -1 +1 @@
1
- {"version":3,"file":"inject-cli.d.ts","sourceRoot":"","sources":["../src/inject-cli.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"inject-cli.d.ts","sourceRoot":"","sources":["../src/inject-cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,63 @@
1
+ /**
2
+ * `--throttle` — emulate a slow network on the driven page.
3
+ *
4
+ * Plan 2026-10-13-image-generation-and-visual-judgment, Phase 18 step 3: the
5
+ * `/visual-audit` image arm OPERATES a candidate asset under a slow network
6
+ * (how long the slot sits empty, whether the placeholder holds the layout)
7
+ * rather than inspecting it once loaded. Chromium's network emulation is the
8
+ * CDP `Network.emulateNetworkConditions` command, issued on a CDP session
9
+ * attached to the page target; it persists across navigations of that target,
10
+ * so a `captureTimeline {"reload":true}` re-load runs throttled.
11
+ *
12
+ * WHAT IS STAMPED. CDP has no getter for the emulated conditions, so the only
13
+ * honest record is "Chromium accepted these numbers": {@link NetworkEmulation}
14
+ * carries the numbers sent and `applied: true` only after the command resolved.
15
+ * A command that failed is a thrown error, never a silently unthrottled run.
16
+ */
17
+ /** A named or custom network profile, in the units people quote. */
18
+ export interface NetworkProfile {
19
+ /** The preset name, or `custom`. */
20
+ name: string;
21
+ /** Added round-trip latency in ms. */
22
+ latencyMs: number;
23
+ /** Download throughput in kilobits per second. */
24
+ downloadKbps: number;
25
+ /** Upload throughput in kilobits per second. */
26
+ uploadKbps: number;
27
+ }
28
+ /**
29
+ * Presets, with Chrome DevTools' long-standing numbers (latency already
30
+ * including DevTools' adjustment factors, throughput in kbit/s).
31
+ */
32
+ export declare const NETWORK_PRESETS: Readonly<Record<string, NetworkProfile>>;
33
+ /** Upper bounds, so a typo cannot ask for a 3-hour round trip. */
34
+ export declare const MAX_LATENCY_MS = 60000;
35
+ export declare const MAX_THROUGHPUT_KBPS = 10000000;
36
+ /**
37
+ * Parse a `--throttle` value: a preset (`slow-3g`, `fast-3g`) or
38
+ * `latency=<ms>,down=<kbps>,up=<kbps>` (all three required).
39
+ */
40
+ export declare function parseThrottle(raw: string): NetworkProfile;
41
+ /** What was sent to Chromium, stamped wherever a frame or result depends on it. */
42
+ export interface NetworkEmulation extends NetworkProfile {
43
+ /** True once `Network.emulateNetworkConditions` resolved. */
44
+ applied: true;
45
+ /** True when `--no-cache` also disabled the HTTP cache (`Network.setCacheDisabled`). */
46
+ cacheDisabled: boolean;
47
+ }
48
+ /** The slice of a Playwright `Page` network emulation needs. */
49
+ export interface ThrottlePage {
50
+ context(): {
51
+ newCDPSession(page: unknown): Promise<{
52
+ send(method: string, params?: Record<string, unknown>): Promise<unknown>;
53
+ }>;
54
+ };
55
+ }
56
+ /** The CDP parameters for a profile: throughput in BYTES per second. */
57
+ export declare function cdpConditions(profile: NetworkProfile): Record<string, unknown>;
58
+ /**
59
+ * Apply `profile` (and, with `disableCache`, turn the HTTP cache off — a warm
60
+ * cache would let a "slow network" reload paint instantly) to `page`.
61
+ */
62
+ export declare function applyNetworkEmulation(page: ThrottlePage, profile: NetworkProfile | null, disableCache: boolean): Promise<NetworkEmulation | null>;
63
+ //# sourceMappingURL=network-throttle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"network-throttle.d.ts","sourceRoot":"","sources":["../src/network-throttle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAGpE,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,eAAO,MAAM,mBAAmB,WAAa,CAAC;AAY9C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAkCzD;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,6DAA6D;IAC7D,OAAO,EAAE,IAAI,CAAC;IACd,wFAAwF;IACxF,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,OAAO,IAAI;QACT,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;YACpC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;SAC1E,CAAC,CAAC;KACJ,CAAC;CACH;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO9E;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,cAAc,GAAG,IAAI,EAC9B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAalC"}
@@ -0,0 +1,111 @@
1
+ /**
2
+ * `captureTimeline` — a timed multi-frame capture of the page over time.
3
+ *
4
+ * Plan 2026-10-13-image-generation-and-visual-judgment, Phase 18 step 3: the
5
+ * `/visual-audit` image arm operates the loading-to-loaded timeline of a slot
6
+ * (what the user sees while a candidate arrives over a slow network, whether
7
+ * the placeholder holds its box) instead of looking only at the settled page.
8
+ * A lockstep frame (`./frame-capture.js`) refuses a moving layout by design; a
9
+ * timeline is the opposite instrument — it RECORDS the movement, one frame
10
+ * every `intervalMs`, each stamped with its offset from the start.
11
+ *
12
+ * `during: {action, payload}` runs one in-page action CONCURRENTLY with the
13
+ * frames — `mediaOverride` is the case it exists for: the override itself still
14
+ * waits for decode and confirms `currentSrc` before IT answers, while the
15
+ * frames record what the user saw as the candidate arrived (under `--throttle`,
16
+ * the slot's slow-network arrival). The action's own result rides on the
17
+ * timeline result, and a failed action fails the step.
18
+ *
19
+ * `reload: true` starts the clock at a fresh navigation commit, so frame 1 is
20
+ * the page before anything painted. A reload re-runs the injected runtime and
21
+ * drops any media override the page held (the DOM is new), so the action waits
22
+ * for the runtime to be ready again before it answers — the next exec step
23
+ * finds a drivable page.
24
+ *
25
+ * Every frame records what was MEASURED: the PNG's own dimensions and the
26
+ * instant the screenshot was requested. A frame that could not be taken is a
27
+ * per-frame `error` and makes the action answer `success: false` (exit 1),
28
+ * never a gap silently closed up.
29
+ */
30
+ import { type FrameColorScheme, type FramePage } from './frame-capture.js';
31
+ /** The CLI-side action id. No in-page action is named this. */
32
+ export declare const CAPTURE_TIMELINE_ACTION = "captureTimeline";
33
+ export declare const MAX_TIMELINE_FRAMES = 120;
34
+ export declare const MAX_TIMELINE_INTERVAL_MS = 10000;
35
+ export declare const DEFAULT_TIMELINE_READY_TIMEOUT_MS = 30000;
36
+ export interface CaptureTimelinePayload {
37
+ /** Directory the frames go into; must be empty or not exist yet. */
38
+ dir: string;
39
+ frames: number;
40
+ intervalMs: number;
41
+ reload: boolean;
42
+ readyTimeoutMs: number;
43
+ /** An in-page action run concurrently with the frames; absent or null for none. */
44
+ during?: {
45
+ action: string;
46
+ payload: unknown;
47
+ } | null;
48
+ }
49
+ /** Validate a `captureTimeline` payload. Exported so the grammar is unit-tested. */
50
+ export declare function parseCaptureTimelinePayload(payload: unknown): CaptureTimelinePayload;
51
+ /** One frame of the timeline. */
52
+ export interface TimelineFrame {
53
+ index: number;
54
+ /** Absolute path of the PNG, or null when the frame failed. */
55
+ path: string | null;
56
+ /** ms from the timeline's start (the reload commit, or the action start). */
57
+ offsetMs: number;
58
+ capturedAt: string;
59
+ width: number | null;
60
+ height: number | null;
61
+ error?: string;
62
+ }
63
+ export interface TimelineResult {
64
+ success: boolean;
65
+ dir: string;
66
+ reloaded: boolean;
67
+ intervalMs: number;
68
+ /** ISO instant the clock started. */
69
+ startedAt: string;
70
+ frames: TimelineFrame[];
71
+ /** The page's own rendering metrics at the end of the timeline. */
72
+ devicePixelRatio: number;
73
+ cssViewport: {
74
+ width: number;
75
+ height: number;
76
+ };
77
+ colorScheme: FrameColorScheme;
78
+ /** After a reload: the injected runtime came back ready. `null` without a reload. */
79
+ runtimeReady: boolean | null;
80
+ /** The concurrent action's own result (`during`), with ms from t0 to its answer. */
81
+ during?: {
82
+ action: string;
83
+ result: unknown;
84
+ answeredAtMs: number;
85
+ failed: boolean;
86
+ };
87
+ error?: string;
88
+ }
89
+ /** The slice of a Playwright `Page` the timeline needs. */
90
+ export interface TimelinePage extends FramePage {
91
+ reload(options: {
92
+ waitUntil: 'commit';
93
+ timeout: number;
94
+ }): Promise<unknown>;
95
+ waitForFunction(fn: () => unknown, arg: undefined, options: {
96
+ timeout: number;
97
+ }): Promise<unknown>;
98
+ }
99
+ /** Run one timeline against `page`. */
100
+ export declare function captureTimeline(page: TimelinePage, payload: CaptureTimelinePayload, now?: () => number, execute?: (action: string, payload: unknown) => Promise<unknown>): Promise<TimelineResult>;
101
+ /**
102
+ * Register `captureTimeline` on `registrar`, against the transport context's
103
+ * Playwright page. A relative `dir` resolves under `baseDir` when one is given
104
+ * (the capture matrix's cell directory), else under the working directory.
105
+ * `network` is stamped on every result, so a frame series is never read as
106
+ * unthrottled when it was throttled (or the reverse).
107
+ */
108
+ export declare function registerTimelineCapture(registrar: {
109
+ register(action: string, fn: (params: unknown, ctx: unknown) => unknown): void;
110
+ }, network: () => unknown, baseDir?: string): void;
111
+ //# sourceMappingURL=timeline-capture.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"timeline-capture.d.ts","sourceRoot":"","sources":["../src/timeline-capture.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@qontinui/ui-bridge-wrapper",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "description": "Runtime for building UI Bridge wrapper apps — transport-agnostic semantic actions.",
5
5
  "main": "./dist/index.cjs",
6
6
  "module": "./dist/index.js",
@@ -54,7 +54,7 @@
54
54
  "access": "public"
55
55
  },
56
56
  "peerDependencies": {
57
- "@qontinui/ui-bridge": ">=0.28.0 <1",
57
+ "@qontinui/ui-bridge": ">=0.36.0 <1",
58
58
  "@qontinui/ui-bridge-headless": ">=0.6.0 <1",
59
59
  "react": "^18.0.0 || ^19.0.0"
60
60
  },