@qontinui/ui-bridge-wrapper 0.7.1 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +51 -1
- package/dist/action-outcome.d.ts +72 -0
- package/dist/action-outcome.d.ts.map +1 -0
- package/dist/capture-matrix.d.ts +105 -0
- package/dist/capture-matrix.d.ts.map +1 -0
- package/dist/capture-specs-cli.cjs +99 -15
- package/dist/capture-specs-cli.cjs.map +1 -1
- package/dist/capture-specs-cli.d.ts +2 -2
- package/dist/capture-specs-cli.d.ts.map +1 -1
- package/dist/frame-capture.d.ts +209 -0
- package/dist/frame-capture.d.ts.map +1 -0
- package/dist/helpers/schema.d.ts +24 -4
- package/dist/helpers/schema.d.ts.map +1 -1
- package/dist/index.cjs +62 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +62 -4
- package/dist/index.js.map +1 -1
- package/dist/inject-cli.cjs +995 -58
- package/dist/inject-cli.cjs.map +1 -1
- package/dist/inject-cli.d.ts +207 -7
- package/dist/inject-cli.d.ts.map +1 -1
- package/dist/login-web-cli.cjs +79 -13
- package/dist/login-web-cli.cjs.map +1 -1
- package/dist/transports/headless.d.ts +19 -0
- package/dist/transports/headless.d.ts.map +1 -1
- package/dist/transports/injected.d.ts +9 -0
- package/dist/transports/injected.d.ts.map +1 -1
- package/dist/types.d.ts +5 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +5 -4
|
@@ -17,10 +17,10 @@
|
|
|
17
17
|
* does require the optional `@qontinui/ui-bridge-headless` peer plus a one-time
|
|
18
18
|
* `npx playwright install chromium` (or `PLAYWRIGHT_BROWSERS_PATH`). See README.
|
|
19
19
|
*
|
|
20
|
-
* ui-bridge-capture-specs --out
|
|
20
|
+
* ui-bridge-capture-specs --out ./spec-capture
|
|
21
21
|
* (creds via env UIB_LOGIN_EMAIL/PASSWORD or --email/--password)
|
|
22
22
|
*/
|
|
23
|
-
export declare const USAGE = "ui-bridge-capture-specs \u2014 log in and snapshot authed pages via the injected transport\n\nRequired (one of):\n --email <e> / --password <p> Credentials. Falls back to env\n UIB_LOGIN_EMAIL / UIB_LOGIN_PASSWORD.\n\nOptions:\n --out <dir> Output dir for <slug>.snapshot.json files\n (default
|
|
23
|
+
export declare const USAGE = "ui-bridge-capture-specs \u2014 log in and snapshot authed pages via the injected transport\n\nRequired (one of):\n --email <e> / --password <p> Credentials. Falls back to env\n UIB_LOGIN_EMAIL / UIB_LOGIN_PASSWORD.\n\nOptions:\n --out <dir> Output dir for <slug>.snapshot.json files\n (default ./spec-capture, relative to cwd).\n --origin <url> App origin (default https://qontinui.io).\n --pages \"slug=path,slug=path\" Pages to capture (paths joined to --origin;\n absolute http(s) URLs used verbatim). Default =\n the two admin coord pages.\n --device <id> device_id query for the default trees page.\n --timeout <ms> Per-hop wait budget (default 70000).\n --quiet Suppress human-readable stderr logs (the per-page\n JSON lines still print).\n --help, -h Print this help and exit.\n\nPrerequisites (packaged bin): the optional @qontinui/ui-bridge-headless peer must\nbe installed AND Chromium available (run `npx playwright install chromium` once,\nor set PLAYWRIGHT_BROWSERS_PATH).\n\nExits non-zero if any capture bounced to login or errored.\n";
|
|
24
24
|
/** A page to capture: a display slug + the absolute URL to navigate to. */
|
|
25
25
|
export interface PageTarget {
|
|
26
26
|
slug: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"capture-specs-cli.d.ts","sourceRoot":"","sources":["../src/capture-specs-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,eAAO,MAAM,KAAK,
|
|
1
|
+
{"version":3,"file":"capture-specs-cli.d.ts","sourceRoot":"","sources":["../src/capture-specs-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,eAAO,MAAM,KAAK,wzCAwBjB,CAAC;AAWF,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAC3B,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,6EAA6E;AAC7E,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAoBrE;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAK3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,MAAM,GACb;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAYhD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CA8CxD;AAaD,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAKvD"}
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Frame capture in lockstep with a control snapshot.
|
|
3
|
+
*
|
|
4
|
+
* WHY LOCKSTEP. The vision analyzers trust the snapshot they are handed: an
|
|
5
|
+
* element's bbox says WHERE on the frame its pixels are, and nothing re-checks
|
|
6
|
+
* it (`rust-vision-core/src/element_snapshot.rs`, `ElementSnapshot`: "Caller is
|
|
7
|
+
* responsible for capturing this in lockstep with the Frame that will be used
|
|
8
|
+
* in the same analyze/assert call"). A frame taken while the layout is still
|
|
9
|
+
* moving pairs every box with the wrong pixels, and the analyzer cannot tell.
|
|
10
|
+
*
|
|
11
|
+
* So the pairing is MEASURED, not assumed: snapshot, frame, snapshot again. If
|
|
12
|
+
* the two snapshots agree on every element's box and visibility, the frame sat
|
|
13
|
+
* between two identical layouts and the pair is `lockstep.verified: true`. If
|
|
14
|
+
* they disagree the round is retried, and after the last attempt the pair is
|
|
15
|
+
* still returned — with `verified: false` and how many elements moved — rather
|
|
16
|
+
* than passed off as a clean pairing.
|
|
17
|
+
*
|
|
18
|
+
* Geometry, not text, decides it: a ticking clock changes the pixels inside its
|
|
19
|
+
* own box but not where the box is, and where-is-each-box is what a bbox → pixel
|
|
20
|
+
* mapping depends on.
|
|
21
|
+
*
|
|
22
|
+
* WHAT THE FRAME SAYS ABOUT ITSELF. Every field of {@link FrameRecord} is read
|
|
23
|
+
* off the page or the PNG at capture time — the device pixel ratio the page
|
|
24
|
+
* reports, the CSS viewport it covers, the colour scheme it rendered in — never
|
|
25
|
+
* copied from the flags that asked for them. A flag that silently failed to
|
|
26
|
+
* apply (Phase 1 of plan 2026-10-13-image-generation-and-visual-judgment
|
|
27
|
+
* measured exactly that for a Chromium DPR launch flag) therefore cannot be
|
|
28
|
+
* stamped onto a frame as if it had.
|
|
29
|
+
*/
|
|
30
|
+
/** The `prefers-color-scheme` a page rendered in. */
|
|
31
|
+
export type FrameColorScheme = 'dark' | 'light';
|
|
32
|
+
/** Whether a snapshot describes the geometry its frame shows. */
|
|
33
|
+
export interface LockstepRecord {
|
|
34
|
+
/**
|
|
35
|
+
* True when the snapshots taken immediately before and after the frame agree
|
|
36
|
+
* on every element's box and visibility.
|
|
37
|
+
*/
|
|
38
|
+
verified: boolean;
|
|
39
|
+
/** Snapshot → frame → snapshot rounds taken; `1` is verified first time. */
|
|
40
|
+
attempts: number;
|
|
41
|
+
/**
|
|
42
|
+
* Elements whose box or visibility differed between the two snapshots of the
|
|
43
|
+
* LAST round, counting ones present in only one of them. `0` when verified.
|
|
44
|
+
* `null` when either snapshot carried no element list, so nothing could be
|
|
45
|
+
* compared — UNKNOWN, never a pass.
|
|
46
|
+
*/
|
|
47
|
+
changedElements: number | null;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* The frame-side half of a frame-and-snapshot pair, stamped into the CLI's JSON.
|
|
51
|
+
*
|
|
52
|
+
* CONSUMERS read these fields by name, so renaming one, or changing what it
|
|
53
|
+
* means, breaks them. qontinui-claude-config's `scripts/verify-page-verdict.sh`
|
|
54
|
+
* (the `/verify-web` verdict) copies the record into each capture, hands `path`
|
|
55
|
+
* to vision-audit as `--frame` with `--scale-factor <devicePixelRatio>`, and
|
|
56
|
+
* reads a record whose `devicePixelRatio` is not a positive finite number as no
|
|
57
|
+
* frame at all. The USAGE token test in `tests/inject-cli-frame.test.ts` pins
|
|
58
|
+
* the field names for that reason.
|
|
59
|
+
*
|
|
60
|
+
* The frame is RAW PIXELS of the page. `data-bridge-redact` masks elements in
|
|
61
|
+
* snapshots and over the relay, never in a screenshot, so a frame shows whatever
|
|
62
|
+
* the page showed — which is why it is written owner-only
|
|
63
|
+
* ({@link PRIVATE_FILE_MODE}, in directories created {@link PRIVATE_DIR_MODE}).
|
|
64
|
+
*/
|
|
65
|
+
export interface FrameRecord {
|
|
66
|
+
/** Absolute path of the PNG written. */
|
|
67
|
+
path: string;
|
|
68
|
+
format: 'png';
|
|
69
|
+
/** Frame pixel dimensions, read from the PNG header. */
|
|
70
|
+
width: number;
|
|
71
|
+
height: number;
|
|
72
|
+
/**
|
|
73
|
+
* `window.devicePixelRatio` when the frame was taken: frame pixels per CSS
|
|
74
|
+
* pixel, i.e. the scale an analyzer maps a CSS-pixel bbox through.
|
|
75
|
+
*/
|
|
76
|
+
devicePixelRatio: number;
|
|
77
|
+
/** The CSS-pixel viewport (`innerWidth` × `innerHeight`) the frame covers. */
|
|
78
|
+
cssViewport: {
|
|
79
|
+
width: number;
|
|
80
|
+
height: number;
|
|
81
|
+
};
|
|
82
|
+
/** The `prefers-color-scheme` the page reported. */
|
|
83
|
+
colorScheme: FrameColorScheme;
|
|
84
|
+
/** ISO-8601 UTC instant the screenshot was requested. */
|
|
85
|
+
capturedAt: string;
|
|
86
|
+
lockstep: LockstepRecord;
|
|
87
|
+
}
|
|
88
|
+
/** Why a requested frame was not produced. The snapshot beside it still stands. */
|
|
89
|
+
export interface FrameError {
|
|
90
|
+
code: 'FRAME_CAPTURE_FAILED' | 'FRAME_SCALE_MISMATCH';
|
|
91
|
+
message: string;
|
|
92
|
+
}
|
|
93
|
+
/** What the page says about how it is being rendered. */
|
|
94
|
+
export interface PageMetrics {
|
|
95
|
+
devicePixelRatio: number;
|
|
96
|
+
innerWidth: number;
|
|
97
|
+
innerHeight: number;
|
|
98
|
+
colorScheme: FrameColorScheme;
|
|
99
|
+
}
|
|
100
|
+
/** The slice of a Playwright `Page` frame capture needs. */
|
|
101
|
+
export interface FramePage {
|
|
102
|
+
evaluate<R>(fn: () => R | Promise<R>): Promise<R>;
|
|
103
|
+
screenshot(options: {
|
|
104
|
+
type: 'png';
|
|
105
|
+
scale: 'device';
|
|
106
|
+
fullPage: false;
|
|
107
|
+
}): Promise<Uint8Array>;
|
|
108
|
+
}
|
|
109
|
+
/** Default number of snapshot → frame → snapshot rounds before giving up on verification. */
|
|
110
|
+
export declare const DEFAULT_LOCKSTEP_ATTEMPTS = 3;
|
|
111
|
+
/**
|
|
112
|
+
* How far (in frame pixels, per axis) the PNG may differ from
|
|
113
|
+
* `cssViewport × devicePixelRatio`. Chromium rounds a fractional product
|
|
114
|
+
* (390 × 2.625 = 1023.75), so an exact match is not the contract; a frame off
|
|
115
|
+
* by more than this was not taken at the scale the page reports, and mapping a
|
|
116
|
+
* CSS box through that scale would land on the wrong pixels.
|
|
117
|
+
*/
|
|
118
|
+
export declare const FRAME_SCALE_TOLERANCE_PX = 2;
|
|
119
|
+
/**
|
|
120
|
+
* The placeholder a `--screenshot` path template replaces with the action's
|
|
121
|
+
* position. It is substituted in the FILE NAME only — see {@link expandFramePath}.
|
|
122
|
+
*/
|
|
123
|
+
export declare const FRAME_INDEX_TOKEN = "{n}";
|
|
124
|
+
/**
|
|
125
|
+
* Mode of every directory created to hold frames or snapshots: owner-only. They
|
|
126
|
+
* can hold pixels and element text from an authenticated session.
|
|
127
|
+
*/
|
|
128
|
+
export declare const PRIVATE_DIR_MODE = 448;
|
|
129
|
+
/** Mode of every frame and snapshot file written: owner read/write only. */
|
|
130
|
+
export declare const PRIVATE_FILE_MODE = 384;
|
|
131
|
+
/**
|
|
132
|
+
* Create `dir`, and any missing parent, owner-only ({@link PRIVATE_DIR_MODE}).
|
|
133
|
+
* A directory that already exists keeps its mode: it is the caller's.
|
|
134
|
+
*/
|
|
135
|
+
export declare function ensurePrivateDir(dir: string): void;
|
|
136
|
+
/**
|
|
137
|
+
* Write `data` to `path` owner-only ({@link PRIVATE_FILE_MODE}), private from
|
|
138
|
+
* the instant the bytes exist. They go into a fresh temp file created 0600
|
|
139
|
+
* beside `path`, which is then renamed over it. Writing in place and narrowing
|
|
140
|
+
* afterwards left a window in which an existing, wider-moded file already held
|
|
141
|
+
* the new pixels; renaming never puts the new bytes in the old file at all.
|
|
142
|
+
*/
|
|
143
|
+
export declare function writePrivateFile(path: string, data: string | Uint8Array): void;
|
|
144
|
+
/**
|
|
145
|
+
* Width and height from a PNG's IHDR chunk. Throws on anything that is not a
|
|
146
|
+
* PNG with an IHDR first — a frame whose size cannot be read cannot be mapped.
|
|
147
|
+
*/
|
|
148
|
+
export declare function pngDimensions(buf: Uint8Array): {
|
|
149
|
+
width: number;
|
|
150
|
+
height: number;
|
|
151
|
+
};
|
|
152
|
+
/**
|
|
153
|
+
* Substitute `{n}` in the FILE NAME of a `--screenshot` template with the
|
|
154
|
+
* action's 1-based position. A `{n}` in a directory name is left alone —
|
|
155
|
+
* {@link frameTokenInDirectory} is how `validateFramePlan` refuses one before
|
|
156
|
+
* anything runs, so a template never fans frames out across directories.
|
|
157
|
+
*/
|
|
158
|
+
export declare function expandFramePath(template: string, position: number): string;
|
|
159
|
+
/** True when `{n}` appears in a directory name of the template, where it is not substituted. */
|
|
160
|
+
export declare function frameTokenInDirectory(template: string): boolean;
|
|
161
|
+
/** True when the template's file name carries `{n}`, so each action gets its own file. */
|
|
162
|
+
export declare function frameTokenInFileName(template: string): boolean;
|
|
163
|
+
/** Read the page's own rendering metrics — never the flags that requested them. */
|
|
164
|
+
export declare function readPageMetrics(page: Pick<FramePage, 'evaluate'>): Promise<PageMetrics>;
|
|
165
|
+
/**
|
|
166
|
+
* Each element's box and visibility, keyed by id — the part of a control
|
|
167
|
+
* snapshot a bbox → pixel mapping depends on. `null` when the snapshot carries
|
|
168
|
+
* no element array (bare or `{data:{elements}}`-wrapped), so there is nothing
|
|
169
|
+
* to compare.
|
|
170
|
+
*/
|
|
171
|
+
export declare function snapshotGeometry(snapshot: unknown): Map<string, string> | null;
|
|
172
|
+
/**
|
|
173
|
+
* How many elements differ between two geometry maps — a changed box or
|
|
174
|
+
* visibility, or an id present in only one. `null` when either side could not
|
|
175
|
+
* be read.
|
|
176
|
+
*/
|
|
177
|
+
export declare function geometryDelta(before: Map<string, string> | null, after: Map<string, string> | null): number | null;
|
|
178
|
+
/** The frame-and-snapshot pair one capture produced. */
|
|
179
|
+
export interface LockstepCapture {
|
|
180
|
+
/** The control snapshot paired with the frame (the BEFORE snapshot of the last round). */
|
|
181
|
+
snapshot: unknown;
|
|
182
|
+
/** The frame, or `null` when it could not be produced — see `frameError`. */
|
|
183
|
+
frame: FrameRecord | null;
|
|
184
|
+
frameError?: FrameError;
|
|
185
|
+
}
|
|
186
|
+
export interface CaptureFrameOptions {
|
|
187
|
+
page: FramePage;
|
|
188
|
+
/** Take one control snapshot. Its failure is the ACTION's failure and propagates. */
|
|
189
|
+
takeSnapshot: () => Promise<unknown>;
|
|
190
|
+
/**
|
|
191
|
+
* Where to write the PNG. Resolved to an absolute path; missing parent dirs
|
|
192
|
+
* are created {@link PRIVATE_DIR_MODE} and the file {@link PRIVATE_FILE_MODE}.
|
|
193
|
+
*/
|
|
194
|
+
path: string;
|
|
195
|
+
maxAttempts?: number;
|
|
196
|
+
/** Injectable clock for tests. */
|
|
197
|
+
now?: () => Date;
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* Snapshot → frame → snapshot, retried until the two snapshots agree on
|
|
201
|
+
* geometry or `maxAttempts` rounds are spent. See the module doc.
|
|
202
|
+
*
|
|
203
|
+
* A snapshot failure propagates: no snapshot means no capture at all. A frame
|
|
204
|
+
* failure does NOT: the snapshot is still a valid observation, so it is
|
|
205
|
+
* returned with `frame: null` and a typed `frameError`, and the caller decides
|
|
206
|
+
* what a missing frame costs.
|
|
207
|
+
*/
|
|
208
|
+
export declare function captureFrameInLockstep(opts: CaptureFrameOptions): Promise<LockstepCapture>;
|
|
209
|
+
//# sourceMappingURL=frame-capture.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"frame-capture.d.ts","sourceRoot":"","sources":["../src/frame-capture.ts"],"names":[],"mappings":"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"}
|
package/dist/helpers/schema.d.ts
CHANGED
|
@@ -3,10 +3,30 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Tiny helper that produces a JSON-Schema-subset object from a plain
|
|
5
5
|
* descriptor, matching the shape `useUIComponent` already exposes on its
|
|
6
|
-
* `actions[].paramSchema` field.
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
6
|
+
* `actions[].paramSchema` field. It surfaces parameter names and types on the
|
|
7
|
+
* runner's `/control/component/:id` endpoint so callers can discover the
|
|
8
|
+
* action signature.
|
|
9
|
+
*
|
|
10
|
+
* ⚠️ **The output is ENFORCED, not merely advertised.** This doc used to say
|
|
11
|
+
* the SDK performs "no runtime validation"; that stopped being true in Phase 2
|
|
12
|
+
* of plan `2026-08-20-ui-bridge-action-declaration-shape`. The invocation seam
|
|
13
|
+
* now checks `params` against the schema before the handler runs, and the
|
|
14
|
+
* object form this helper emits is exactly form 1 of the supported subset
|
|
15
|
+
* (`@qontinui/ui-bridge` `core/param-schema.ts`, which documents the grammar).
|
|
16
|
+
* Enforcement defaults to `'warn'`, so a wrong schema logs rather than breaks —
|
|
17
|
+
* until a deployment arms `setDefaultParamValidationMode('enforce')`, at which
|
|
18
|
+
* point it rejects real calls with `UB-ACTION-REJECTED`.
|
|
19
|
+
*
|
|
20
|
+
* Two consequences worth knowing before you declare one:
|
|
21
|
+
*
|
|
22
|
+
* - **`additionalProperties: false` is always emitted**, so any param not in
|
|
23
|
+
* the descriptor is a violation. That is the point of the helper, but it
|
|
24
|
+
* means a handler that quietly accepts extras must declare them.
|
|
25
|
+
* - **An unrecognised type name is passed through verbatim** (see `normalize`
|
|
26
|
+
* below). The validator treats a `type` outside the seven JSON Schema
|
|
27
|
+
* primitive names as expressing no constraint, so a typo like `"sting"`
|
|
28
|
+
* silently validates everything rather than rejecting everything. It fails
|
|
29
|
+
* open, not closed — but it fails.
|
|
10
30
|
*
|
|
11
31
|
* Accepted descriptor values:
|
|
12
32
|
* - a JSON-Schema type name string (`"string"`, `"number"`, ...)
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/helpers/schema.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/helpers/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAYH,KAAK,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAkBvE,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACjE,KAAK,EAAE,CAAC,GACP,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBzB"}
|
package/dist/index.cjs
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
var module$1 = require('module');
|
|
4
4
|
var fs = require('fs');
|
|
5
|
+
var crypto = require('crypto');
|
|
5
6
|
|
|
6
7
|
var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
|
|
7
8
|
// src/types.ts
|
|
@@ -229,6 +230,8 @@ var HeadlessTransport = class extends BaseTransport {
|
|
|
229
230
|
targetUrl,
|
|
230
231
|
viewportWidth: typeof raw["viewportWidth"] === "number" ? raw["viewportWidth"] : void 0,
|
|
231
232
|
viewportHeight: typeof raw["viewportHeight"] === "number" ? raw["viewportHeight"] : void 0,
|
|
233
|
+
deviceScaleFactor: typeof raw["deviceScaleFactor"] === "number" ? raw["deviceScaleFactor"] : void 0,
|
|
234
|
+
colorScheme: raw["colorScheme"] === "light" || raw["colorScheme"] === "dark" ? raw["colorScheme"] : void 0,
|
|
232
235
|
uiBridgeBase: typeof raw["uiBridgeBase"] === "string" ? raw["uiBridgeBase"] : void 0,
|
|
233
236
|
waitForUiBridgeMs: typeof raw["waitForUiBridgeMs"] === "number" ? raw["waitForUiBridgeMs"] : void 0,
|
|
234
237
|
userAgent: typeof raw["userAgent"] === "string" ? raw["userAgent"] : void 0,
|
|
@@ -263,6 +266,7 @@ Underlying import error: ${cause}`
|
|
|
263
266
|
}
|
|
264
267
|
const initScripts = await this.buildInitScripts();
|
|
265
268
|
const relayAuth = this.relayAuth();
|
|
269
|
+
const pinnedTabId = this.pinnedTabId();
|
|
266
270
|
let tab;
|
|
267
271
|
try {
|
|
268
272
|
tab = await launchHeadlessTab({
|
|
@@ -272,13 +276,16 @@ Underlying import error: ${cause}`
|
|
|
272
276
|
waitForUiBridgeMs: this.options.waitForUiBridgeMs,
|
|
273
277
|
viewportWidth: this.options.viewportWidth,
|
|
274
278
|
viewportHeight: this.options.viewportHeight,
|
|
279
|
+
...this.options.deviceScaleFactor !== void 0 ? { deviceScaleFactor: this.options.deviceScaleFactor } : {},
|
|
280
|
+
...this.options.colorScheme !== void 0 ? { colorScheme: this.options.colorScheme } : {},
|
|
275
281
|
userAgent: this.options.userAgent,
|
|
276
282
|
forwardConsole: this.options.forwardConsole,
|
|
277
283
|
initScripts: initScripts.length > 0 ? initScripts : void 0,
|
|
278
284
|
launchArgs: this.options.launchArgs && this.options.launchArgs.length > 0 ? this.options.launchArgs : void 0,
|
|
279
285
|
storageStatePath: this.options.storageStatePath,
|
|
280
286
|
...relayAuth.authToken ? { authToken: relayAuth.authToken } : {},
|
|
281
|
-
...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {}
|
|
287
|
+
...relayAuth.callerUserId ? { callerUserId: relayAuth.callerUserId } : {},
|
|
288
|
+
...pinnedTabId ? { pinnedTabId } : {}
|
|
282
289
|
});
|
|
283
290
|
} catch (err) {
|
|
284
291
|
const cause = err instanceof Error ? err.message : String(err);
|
|
@@ -300,8 +307,39 @@ Underlying launch error: ${cause}`
|
|
|
300
307
|
tabId: tab.tabId,
|
|
301
308
|
close: tab.close
|
|
302
309
|
};
|
|
310
|
+
await this.verifyEmulation(tab.page);
|
|
303
311
|
await this.afterLaunch(tab.page);
|
|
304
312
|
}
|
|
313
|
+
/**
|
|
314
|
+
* Read back the requested device scale factor and colour scheme from the
|
|
315
|
+
* page itself, and refuse a launch whose page reports anything else.
|
|
316
|
+
*/
|
|
317
|
+
async verifyEmulation(page) {
|
|
318
|
+
const wantDpr = this.options.deviceScaleFactor;
|
|
319
|
+
const wantScheme = this.options.colorScheme;
|
|
320
|
+
if (wantDpr === void 0 && wantScheme === void 0) return;
|
|
321
|
+
const seen = await page.evaluate(() => ({
|
|
322
|
+
dpr: window.devicePixelRatio,
|
|
323
|
+
dark: window.matchMedia("(prefers-color-scheme: dark)").matches
|
|
324
|
+
}));
|
|
325
|
+
const problems = [];
|
|
326
|
+
if (wantDpr !== void 0 && Math.abs(seen.dpr - wantDpr) > 1e-9) {
|
|
327
|
+
problems.push(`devicePixelRatio ${seen.dpr} (requested ${wantDpr})`);
|
|
328
|
+
}
|
|
329
|
+
if (wantScheme !== void 0 && seen.dark !== (wantScheme === "dark")) {
|
|
330
|
+
problems.push(
|
|
331
|
+
`prefers-color-scheme ${seen.dark ? "dark" : "light"} (requested ${wantScheme})`
|
|
332
|
+
);
|
|
333
|
+
}
|
|
334
|
+
if (problems.length === 0) return;
|
|
335
|
+
await this.onClose().catch(() => {
|
|
336
|
+
});
|
|
337
|
+
throw new WrapperTransportError(
|
|
338
|
+
"EMULATION_NOT_APPLIED",
|
|
339
|
+
`The launched page reports ${problems.join(" and ")}. The installed '@qontinui/ui-bridge-headless' peer most likely predates deviceScaleFactor/colorScheme support (added after 0.5.0) and ignored them; upgrade it. A page measured at an emulation it is not actually rendering at would be stamped with the wrong values.`,
|
|
340
|
+
{ details: { requested: { deviceScaleFactor: wantDpr, colorScheme: wantScheme }, seen } }
|
|
341
|
+
);
|
|
342
|
+
}
|
|
305
343
|
/**
|
|
306
344
|
* Subclass hook: init-scripts to register on the browser context before the
|
|
307
345
|
* first navigation (via `context.addInitScript`). Default: none. Injected
|
|
@@ -319,6 +357,13 @@ Underlying launch error: ${cause}`
|
|
|
319
357
|
relayAuth() {
|
|
320
358
|
return {};
|
|
321
359
|
}
|
|
360
|
+
/**
|
|
361
|
+
* Subclass hook: the tab id this launch pinned, so the registration poll
|
|
362
|
+
* returns that tab only. Default: none. Injected mode returns `--tab-id`.
|
|
363
|
+
*/
|
|
364
|
+
pinnedTabId() {
|
|
365
|
+
return void 0;
|
|
366
|
+
}
|
|
322
367
|
/**
|
|
323
368
|
* Subclass hook: run after launch + navigation, before `ready()` resolves.
|
|
324
369
|
* Default: no-op. Injected mode overrides it to await the in-page runtime.
|
|
@@ -381,6 +426,14 @@ function loadInjectedBundle() {
|
|
|
381
426
|
}
|
|
382
427
|
var InjectedTransport = class extends HeadlessTransport {
|
|
383
428
|
injected;
|
|
429
|
+
/**
|
|
430
|
+
* The pinned tab's key: 32 random bytes, base64url, generated once per
|
|
431
|
+
* transport (one launch) and kept in this process. The runner binds a tab
|
|
432
|
+
* that presents it to the key's digest, so the pin survives an origin hop
|
|
433
|
+
* while a page that merely learns the pinned id cannot attach as the tab.
|
|
434
|
+
* Lives only in the injected global — never in a storage artifact.
|
|
435
|
+
*/
|
|
436
|
+
tabKey = crypto.randomBytes(32).toString("base64url");
|
|
384
437
|
constructor(config, registry) {
|
|
385
438
|
const raw = config.options ?? {};
|
|
386
439
|
const headed = raw["headed"] === true;
|
|
@@ -415,9 +468,11 @@ var InjectedTransport = class extends HeadlessTransport {
|
|
|
415
468
|
if (this.injected.appId) cfg.appId = this.injected.appId;
|
|
416
469
|
if (this.injected.appName) cfg.appName = this.injected.appName;
|
|
417
470
|
}
|
|
418
|
-
if (this.injected.tabId)
|
|
419
|
-
|
|
420
|
-
cfg.
|
|
471
|
+
if (this.injected.tabId) {
|
|
472
|
+
cfg.tabId = this.injected.tabId;
|
|
473
|
+
cfg.tabKey = this.tabKey;
|
|
474
|
+
}
|
|
475
|
+
if (this.injected.settleQuietMs !== void 0) cfg.settleQuietMs = this.injected.settleQuietMs;
|
|
421
476
|
if (this.injected.settleTimeoutMs !== void 0)
|
|
422
477
|
cfg.settleTimeoutMs = this.injected.settleTimeoutMs;
|
|
423
478
|
if (this.injected.expectSelector !== void 0)
|
|
@@ -436,6 +491,9 @@ var InjectedTransport = class extends HeadlessTransport {
|
|
|
436
491
|
...this.injected.registrationMetadata?.userId ? { callerUserId: this.injected.registrationMetadata.userId } : {}
|
|
437
492
|
};
|
|
438
493
|
}
|
|
494
|
+
pinnedTabId() {
|
|
495
|
+
return this.injected.tabId;
|
|
496
|
+
}
|
|
439
497
|
async buildInitScripts() {
|
|
440
498
|
const scripts = [];
|
|
441
499
|
const cfg = this.injectedConfig();
|