@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.
@@ -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 D:/qontinui-root/spec-capture
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 D:/qontinui-root/spec-capture).\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";
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,szCAwBjB,CAAC;AAOF,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"}
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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEhD,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC;IACd,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,oDAAoD;IACpD,WAAW,EAAE,gBAAgB,CAAC;IAC9B,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,mFAAmF;AACnF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,sBAAsB,GAAG,sBAAsB,CAAC;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,gBAAgB,CAAC;CAC/B;AAED,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClD,UAAU,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7F;AAED,6FAA6F;AAC7F,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,MAAQ,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,MAAQ,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAY9E;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAUhF;AAOD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1E;AAED,gGAAgG;AAChG,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,mFAAmF;AACnF,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAS7F;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAkB9E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,EAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GAChC,MAAM,GAAG,IAAI,CAUf;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,0FAA0F;IAC1F,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,qFAAqF;IACrF,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC,CA4GhG"}
@@ -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. The existing SDK contract says "no
7
- * runtime validation is performed" — this helper's only job is to surface
8
- * parameter names and types on the runner's `/control/component/:id`
9
- * endpoint so callers can discover the action signature.
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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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"}
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) cfg.tabId = this.injected.tabId;
419
- if (this.injected.settleQuietMs !== void 0)
420
- cfg.settleQuietMs = this.injected.settleQuietMs;
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();