@orkestrel/test 0.0.22 → 0.0.24

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.
@@ -230,9 +230,9 @@ export declare const CAPTURE_STAGINGS = 4;
230
230
  *
231
231
  * @param options - The path to write, the viewport to shoot at, and the element to shoot.
232
232
  * @returns The absolute path of the written frame, after it has been read back and matched.
233
- * @throws Thrown when the pane cannot be staged, when the document's height never settles under
234
- * {@link CAPTURE_STAGINGS} restagings, when the provider wrote the frame somewhere else, and when
235
- * the bytes on disk are not the ones this shot produced.
233
+ * @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
234
+ * element height never settles under {@link CAPTURE_STAGINGS} restagings, when the provider wrote
235
+ * the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
236
236
  *
237
237
  * @remarks
238
238
  * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
@@ -242,7 +242,7 @@ export declare const CAPTURE_STAGINGS = 4;
242
242
  * path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
243
243
  * refusal is what a provider resolving that path against a different base would trip.
244
244
  *
245
- * The frame covers the whole document at `options.width`, whatever `options.height` is. The
245
+ * A page frame covers the whole document at the declared width, whatever the declared height is. The
246
246
  * provider shoots the tester's body in the top-level page's own coordinates, so a document taller
247
247
  * than the pane is painted for the pane's height and the rows below it are the runner's page rather
248
248
  * than the document — a frame that reads as the surface down to the fold and as bare canvas after
@@ -274,9 +274,39 @@ export declare const CAPTURE_STAGINGS = 4;
274
274
  * `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
275
275
  * written at a height that is already wrong.
276
276
  *
277
- * Omit `options.element` to shoot the whole page. The pane is staged for the frame and released
278
- * before this returns, on the failing path as well as the passing one, which hands the tester back
279
- * the viewport it had before the first staging.
277
+ * Omit the `element` option to shoot the whole page. An element frame no taller than the declared
278
+ * height is shot with the pane at the declared size, so every viewport length resolves against the
279
+ * declared viewport, whether the element sits in flow above the fold, in flow below it,
280
+ * or fixed. The re-reading takes the element's own height in place of the content edge, so the pane
281
+ * grows only for an element taller than the declared height, and then to that element's height,
282
+ * which is the geometry its viewport lengths resolve against. An element that outgrows every pane
283
+ * is refused with the same text.
284
+ *
285
+ * Where the element's box lies outside the pane, the tester's document is scrolled by the nearest
286
+ * distance that would bring it inside, and the box is read again. A fixed element past the pane can
287
+ * take a scroll that does not move it, and that scroll is handed back with the rest. The document is
288
+ * not scrolled for an element already inside the pane.
289
+ *
290
+ * The provider paints an element that fits the runner's window only where that window shows it.
291
+ * Where such an element lies past the window, the calling tester frame is offset up or left only as
292
+ * far as brings the element inside, and composited, which keeps a fixed element that starts past the
293
+ * window's height from being culled. The {@link computeOffset} function computes that move. The
294
+ * offset is written on that frame's own `style` attribute, where it outranks the placement the
295
+ * {@link stagePane} function makes, and it depends on that placement's fixed position. The attribute
296
+ * is restored as soon as the screenshot settles. An element inside the window, or too large for it,
297
+ * is not offset.
298
+ *
299
+ * The capture sends no pointer input. The staging lifts the tester to the window's origin, a scroll
300
+ * brings an element outside the pane into it, and an offset brings an element past the window
301
+ * inside; each moves content under a pointer resting on the page. A pointer the case placed on the
302
+ * element, with the pane already staged at the frame's size, keeps its hover in the frame where the
303
+ * element lies inside both the pane and the runner window, because the capture then moves nothing.
304
+ * No hover is promised after the pane is released.
305
+ *
306
+ * The pane is staged for the frame and released before this returns, on the failing path as well as
307
+ * the passing one, which hands the tester back the viewport it had before the first staging. The
308
+ * tester's scroll position is restored after that release, on every path, a rejected release
309
+ * included.
280
310
  *
281
311
  * @example
282
312
  * ```ts
@@ -504,6 +534,34 @@ export declare function commitInput(element: HTMLInputElement | HTMLTextAreaElem
504
534
  */
505
535
  export declare function computeNamePattern(name: string): RegExp;
506
536
 
537
+ /**
538
+ * Computes how far an element frame moves the tester frame so the element is shot inside the
539
+ * runner's window.
540
+ *
541
+ * @param box - The element's box in the runner window's coordinates, with the tester frame at the
542
+ * window's origin.
543
+ * @param width - The runner window's width in CSS pixels.
544
+ * @param height - The runner window's height in CSS pixels.
545
+ * @returns The frame's move: zero on both axes where the frame stays at the origin.
546
+ *
547
+ * @remarks
548
+ * The provider paints an element that fits the window only where the window shows it, so an element
549
+ * that fits and lies past the window's bottom or right edge moves up or left only as far as brings
550
+ * it inside. Each edge is rounded up to the next whole row or column first, because the shot is
551
+ * clipped to whole rows and columns, and the move is bounded so the element's opposite edge never
552
+ * passes the window's start: an element starting half a row down moves by no more than that half
553
+ * row. An axis whose far edge already lies inside the window, a fractional window edge included,
554
+ * does not move. An element too large for the window is shot beyond the viewport, so it is not
555
+ * moved either.
556
+ *
557
+ * @example
558
+ * ```ts
559
+ * computeOffset(new DOMRectReadOnly(0, 744, 390, 100), 800, 513)
560
+ * // { top: -331, left: 0 }
561
+ * ```
562
+ */
563
+ export declare function computeOffset(box: DOMRectReadOnly, width: number, height: number): FrameOffset;
564
+
507
565
  /**
508
566
  * Names the roles whose accessible name is the text a reader can see inside them.
509
567
  *
@@ -1007,16 +1065,16 @@ export declare function describeTree(element: Element): string;
1007
1065
  * @param name - The target's name, as the refusals voice it.
1008
1066
  * @returns A promise resolving after the control enters its pressed state.
1009
1067
  * @throws Thrown when a pointer is already held, the resolver refuses, the target stays outside
1010
- * the viewport after scrolling, or the press misses. A missed press that also fails to release
1011
- * carries the release rejection as its cause.
1068
+ * the viewport after scrolling, the frame wait fails, the pressed-state read fails, or the press
1069
+ * misses. A frame wait or pressed-state read that fails releases the pointer before the refusal,
1070
+ * and a failure whose release also fails carries the release rejection as its cause.
1012
1071
  *
1013
1072
  * @remarks
1014
1073
  * This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
1015
1074
  * brings a wholly off-viewport target into view and a refusal for one that stays outside, the
1016
1075
  * centre mapped through the tester iframe's painted scale into page coordinates, the trusted move
1017
- * and press, the marker, a frame wait, and the `:active` read-back that releases before refusing a
1018
- * missed press. The refusal precedes resolution, so a double hold is refused before an absent
1019
- * name is.
1076
+ * and press, the marker, and the frame wait and the `:active` read-back that both release before
1077
+ * refusing. The refusal precedes resolution, so a double hold is refused before an absent name is.
1020
1078
  *
1021
1079
  * @example
1022
1080
  * ```ts
@@ -1240,6 +1298,20 @@ export declare function findRule(selector: string): CSSStyleRule | undefined;
1240
1298
  */
1241
1299
  export declare const FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
1242
1300
 
1301
+ /**
1302
+ * Represents how far an element frame moves the tester frame from the runner window's origin for the
1303
+ * shot, in CSS pixels.
1304
+ *
1305
+ * @remarks
1306
+ * Both are zero where the frame stays at the origin.
1307
+ */
1308
+ export declare interface FrameOffset {
1309
+ /** Holds the frame's vertical move, zero or negative; a negative value moves the frame up. */
1310
+ readonly top: number;
1311
+ /** Holds the frame's horizontal move, zero or negative; a negative value moves the frame left. */
1312
+ readonly left: number;
1313
+ }
1314
+
1243
1315
  /** Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. */
1244
1316
  export declare interface FrameOptions {
1245
1317
  /** Holds the frame's path, relative to the calling test file. */
@@ -2135,6 +2207,11 @@ export declare function readFocus(): string | undefined;
2135
2207
  * against its own root rather than against the calling test file, so a relative path names a file
2136
2208
  * somewhere else.
2137
2209
  *
2210
+ * A file that opens with a PNG header and still does not decode is refused with the size that header
2211
+ * declares, in device pixels:
2212
+ * `Capture frame at <path> is not an image this browser decodes: <w>x<h> device pixels`.
2213
+ * A file with no PNG header is refused without a size.
2214
+ *
2138
2215
  * @example
2139
2216
  * ```ts
2140
2217
  * const reading = await readFrame(written)
@@ -2657,7 +2734,7 @@ export declare function releaseMedia(): Promise<void>;
2657
2734
  export declare function releasePane(): Promise<void>;
2658
2735
 
2659
2736
  /**
2660
- * Releases a held pointer and parks it at the page origin, clearing hover.
2737
+ * Releases a held pointer and parks it outside the page, clearing hover.
2661
2738
  *
2662
2739
  * @returns A promise resolving after the released pointer's frame paints.
2663
2740
  * @throws Thrown when the release or the park rejects. If both reject, the aggregate carries the
@@ -2666,9 +2743,14 @@ export declare function releasePane(): Promise<void>;
2666
2743
  * @remarks
2667
2744
  * An idle pointer sends no button release. Calling this after an explicit release is safe in an
2668
2745
  * `afterEach` hook. A rejected release keeps the marker for a later retry. The pointer still moves
2669
- * to the origin in cleanup, and a rejection there joins the aggregate described under `@throws`.
2746
+ * to its park point in cleanup, and a rejection there joins the aggregate described under `@throws`.
2670
2747
  * The provider must expose a DevTools session.
2671
2748
  *
2749
+ * The park point is (-1, -1) in the runner page's coordinates, one pixel above and to the left of
2750
+ * that page's viewport. The browser hit-tests nothing outside the viewport, so no element takes a
2751
+ * `mouseover` event or hover paint from the parked pointer until the next pointer verb. This holds
2752
+ * even where a staging, scroll, or offset lays content over the park point.
2753
+ *
2672
2754
  * @example
2673
2755
  * ```ts
2674
2756
  * await releasePointer()
@@ -630,16 +630,16 @@ async function holdAccessibleWithin(region, role, name) {
630
630
  * @param name - The target's name, as the refusals voice it.
631
631
  * @returns A promise resolving after the control enters its pressed state.
632
632
  * @throws Thrown when a pointer is already held, the resolver refuses, the target stays outside
633
- * the viewport after scrolling, or the press misses. A missed press that also fails to release
634
- * carries the release rejection as its cause.
633
+ * the viewport after scrolling, the frame wait fails, the pressed-state read fails, or the press
634
+ * misses. A frame wait or pressed-state read that fails releases the pointer before the refusal,
635
+ * and a failure whose release also fails carries the release rejection as its cause.
635
636
  *
636
637
  * @remarks
637
638
  * This is the one pointer drive every hold verb shares: the held-marker refusal, a scroll that
638
639
  * brings a wholly off-viewport target into view and a refusal for one that stays outside, the
639
640
  * centre mapped through the tester iframe's painted scale into page coordinates, the trusted move
640
- * and press, the marker, a frame wait, and the `:active` read-back that releases before refusing a
641
- * missed press. The refusal precedes resolution, so a double hold is refused before an absent
642
- * name is.
641
+ * and press, the marker, and the frame wait and the `:active` read-back that both release before
642
+ * refusing. The refusal precedes resolution, so a double hold is refused before an absent name is.
643
643
  *
644
644
  * @example
645
645
  * ```ts
@@ -675,18 +675,20 @@ async function driveHold(resolve, name) {
675
675
  clickCount: 1
676
676
  });
677
677
  document.documentElement.setAttribute(POINTER_HOLD, `${String(x)}x${String(y)}`);
678
- await waitForFrame();
679
- if (!target.matches(":active")) {
678
+ try {
679
+ await waitForFrame();
680
+ if (!target.matches(":active")) throw new Error(`Interactive target "${name}" did not enter the pressed state`);
681
+ } catch (error) {
680
682
  try {
681
683
  await releasePointer();
682
684
  } catch (cause) {
683
- throw new Error(`Interactive target "${name}" did not enter the pressed state`, { cause });
685
+ throw new Error(error instanceof Error ? error.message : String(error), { cause });
684
686
  }
685
- throw new Error(`Interactive target "${name}" did not enter the pressed state`);
687
+ throw error;
686
688
  }
687
689
  }
688
690
  /**
689
- * Releases a held pointer and parks it at the page origin, clearing hover.
691
+ * Releases a held pointer and parks it outside the page, clearing hover.
690
692
  *
691
693
  * @returns A promise resolving after the released pointer's frame paints.
692
694
  * @throws Thrown when the release or the park rejects. If both reject, the aggregate carries the
@@ -695,9 +697,14 @@ async function driveHold(resolve, name) {
695
697
  * @remarks
696
698
  * An idle pointer sends no button release. Calling this after an explicit release is safe in an
697
699
  * `afterEach` hook. A rejected release keeps the marker for a later retry. The pointer still moves
698
- * to the origin in cleanup, and a rejection there joins the aggregate described under `@throws`.
700
+ * to its park point in cleanup, and a rejection there joins the aggregate described under `@throws`.
699
701
  * The provider must expose a DevTools session.
700
702
  *
703
+ * The park point is (-1, -1) in the runner page's coordinates, one pixel above and to the left of
704
+ * that page's viewport. The browser hit-tests nothing outside the viewport, so no element takes a
705
+ * `mouseover` event or hover paint from the parked pointer until the next pointer verb. This holds
706
+ * even where a staging, scroll, or offset lays content over the park point.
707
+ *
701
708
  * @example
702
709
  * ```ts
703
710
  * await releasePointer()
@@ -727,8 +734,8 @@ async function releasePointer() {
727
734
  try {
728
735
  await sendProtocol("Input.dispatchMouseEvent", {
729
736
  type: "mouseMoved",
730
- x: 0,
731
- y: 0
737
+ x: -1,
738
+ y: -1
732
739
  });
733
740
  await waitForFrame();
734
741
  } catch (cause) {
@@ -2785,6 +2792,39 @@ async function releasePane() {
2785
2792
  if (Number.isFinite(width) && Number.isFinite(height)) await page.viewport(width, height);
2786
2793
  }
2787
2794
  /**
2795
+ * Computes how far an element frame moves the tester frame so the element is shot inside the
2796
+ * runner's window.
2797
+ *
2798
+ * @param box - The element's box in the runner window's coordinates, with the tester frame at the
2799
+ * window's origin.
2800
+ * @param width - The runner window's width in CSS pixels.
2801
+ * @param height - The runner window's height in CSS pixels.
2802
+ * @returns The frame's move: zero on both axes where the frame stays at the origin.
2803
+ *
2804
+ * @remarks
2805
+ * The provider paints an element that fits the window only where the window shows it, so an element
2806
+ * that fits and lies past the window's bottom or right edge moves up or left only as far as brings
2807
+ * it inside. Each edge is rounded up to the next whole row or column first, because the shot is
2808
+ * clipped to whole rows and columns, and the move is bounded so the element's opposite edge never
2809
+ * passes the window's start: an element starting half a row down moves by no more than that half
2810
+ * row. An axis whose far edge already lies inside the window, a fractional window edge included,
2811
+ * does not move. An element too large for the window is shot beyond the viewport, so it is not
2812
+ * moved either.
2813
+ *
2814
+ * @example
2815
+ * ```ts
2816
+ * computeOffset(new DOMRectReadOnly(0, 744, 390, 100), 800, 513)
2817
+ * // { top: -331, left: 0 }
2818
+ * ```
2819
+ */
2820
+ function computeOffset(box, width, height) {
2821
+ const fits = box.width <= width && box.height <= height;
2822
+ return {
2823
+ top: fits && box.bottom > height ? Math.max(height - Math.ceil(box.bottom), -box.top) : 0,
2824
+ left: fits && box.right > width ? Math.max(width - Math.ceil(box.right), -box.left) : 0
2825
+ };
2826
+ }
2827
+ /**
2788
2828
  * Stages the tester's print medium, motion preference, and forced colours through the browser
2789
2829
  * provider.
2790
2830
  *
@@ -2948,9 +2988,9 @@ async function releaseMedia() {
2948
2988
  *
2949
2989
  * @param options - The path to write, the viewport to shoot at, and the element to shoot.
2950
2990
  * @returns The absolute path of the written frame, after it has been read back and matched.
2951
- * @throws Thrown when the pane cannot be staged, when the document's height never settles under
2952
- * {@link CAPTURE_STAGINGS} restagings, when the provider wrote the frame somewhere else, and when
2953
- * the bytes on disk are not the ones this shot produced.
2991
+ * @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
2992
+ * element height never settles under {@link CAPTURE_STAGINGS} restagings, when the provider wrote
2993
+ * the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
2954
2994
  *
2955
2995
  * @remarks
2956
2996
  * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
@@ -2960,7 +3000,7 @@ async function releaseMedia() {
2960
3000
  * path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
2961
3001
  * refusal is what a provider resolving that path against a different base would trip.
2962
3002
  *
2963
- * The frame covers the whole document at `options.width`, whatever `options.height` is. The
3003
+ * A page frame covers the whole document at the declared width, whatever the declared height is. The
2964
3004
  * provider shoots the tester's body in the top-level page's own coordinates, so a document taller
2965
3005
  * than the pane is painted for the pane's height and the rows below it are the runner's page rather
2966
3006
  * than the document — a frame that reads as the surface down to the fold and as bare canvas after
@@ -2992,9 +3032,39 @@ async function releaseMedia() {
2992
3032
  * `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
2993
3033
  * written at a height that is already wrong.
2994
3034
  *
2995
- * Omit `options.element` to shoot the whole page. The pane is staged for the frame and released
2996
- * before this returns, on the failing path as well as the passing one, which hands the tester back
2997
- * the viewport it had before the first staging.
3035
+ * Omit the `element` option to shoot the whole page. An element frame no taller than the declared
3036
+ * height is shot with the pane at the declared size, so every viewport length resolves against the
3037
+ * declared viewport, whether the element sits in flow above the fold, in flow below it,
3038
+ * or fixed. The re-reading takes the element's own height in place of the content edge, so the pane
3039
+ * grows only for an element taller than the declared height, and then to that element's height,
3040
+ * which is the geometry its viewport lengths resolve against. An element that outgrows every pane
3041
+ * is refused with the same text.
3042
+ *
3043
+ * Where the element's box lies outside the pane, the tester's document is scrolled by the nearest
3044
+ * distance that would bring it inside, and the box is read again. A fixed element past the pane can
3045
+ * take a scroll that does not move it, and that scroll is handed back with the rest. The document is
3046
+ * not scrolled for an element already inside the pane.
3047
+ *
3048
+ * The provider paints an element that fits the runner's window only where that window shows it.
3049
+ * Where such an element lies past the window, the calling tester frame is offset up or left only as
3050
+ * far as brings the element inside, and composited, which keeps a fixed element that starts past the
3051
+ * window's height from being culled. The {@link computeOffset} function computes that move. The
3052
+ * offset is written on that frame's own `style` attribute, where it outranks the placement the
3053
+ * {@link stagePane} function makes, and it depends on that placement's fixed position. The attribute
3054
+ * is restored as soon as the screenshot settles. An element inside the window, or too large for it,
3055
+ * is not offset.
3056
+ *
3057
+ * The capture sends no pointer input. The staging lifts the tester to the window's origin, a scroll
3058
+ * brings an element outside the pane into it, and an offset brings an element past the window
3059
+ * inside; each moves content under a pointer resting on the page. A pointer the case placed on the
3060
+ * element, with the pane already staged at the frame's size, keeps its hover in the frame where the
3061
+ * element lies inside both the pane and the runner window, because the capture then moves nothing.
3062
+ * No hover is promised after the pane is released.
3063
+ *
3064
+ * The pane is staged for the frame and released before this returns, on the failing path as well as
3065
+ * the passing one, which hands the tester back the viewport it had before the first staging. The
3066
+ * tester's scroll position is restored after that release, on every path, a rejected release
3067
+ * included.
2998
3068
  *
2999
3069
  * @example
3000
3070
  * ```ts
@@ -3002,27 +3072,64 @@ async function releaseMedia() {
3002
3072
  * ```
3003
3073
  */
3004
3074
  async function captureFrame(options) {
3075
+ const element = options.element;
3076
+ const scroll = {
3077
+ left: window.scrollX,
3078
+ top: window.scrollY
3079
+ };
3005
3080
  try {
3006
3081
  await stagePane(options.width, options.height);
3007
3082
  let pane = options.height;
3008
- let covered = Math.max(measureContent(), options.height);
3083
+ let covered;
3009
3084
  let growth = 0;
3010
- for (let staging = 0; pane !== covered; staging += 1) {
3085
+ for (let staging = 0;; staging += 1) {
3086
+ const reading = Math.max(element === void 0 ? measureContent() : Math.ceil(element.getBoundingClientRect().height), options.height);
3087
+ if (covered !== void 0) growth = Math.max(0, reading - covered);
3088
+ covered = reading;
3089
+ if (pane === covered) break;
3011
3090
  if (staging === 4) throw new Error(`Capture frame at ${options.path} never settled after ${String(4)} restagings: ${String(covered)} over a ${String(pane)} pane`);
3012
3091
  pane = covered + growth;
3013
3092
  await stagePane(options.width, pane);
3014
- const reading = Math.max(measureContent(), options.height);
3015
- growth = Math.max(0, reading - covered);
3016
- covered = reading;
3017
3093
  }
3018
- const shot = options.element === void 0 ? await page.screenshot({
3019
- path: options.path,
3020
- base64: true
3021
- }) : await page.screenshot({
3022
- element: options.element,
3094
+ let shot;
3095
+ if (element === void 0) shot = await page.screenshot({
3023
3096
  path: options.path,
3024
3097
  base64: true
3025
3098
  });
3099
+ else {
3100
+ const box = element.getBoundingClientRect();
3101
+ const down = box.top < 0 ? box.top : Math.max(0, box.bottom - window.innerHeight);
3102
+ const across = box.left < 0 ? box.left : Math.max(0, box.right - window.innerWidth);
3103
+ if (down !== 0 || across !== 0) window.scrollBy({
3104
+ top: down,
3105
+ left: across,
3106
+ behavior: "instant"
3107
+ });
3108
+ const frame = window.frameElement;
3109
+ const view = window.top;
3110
+ const placed = element.getBoundingClientRect();
3111
+ const move = view === null ? {
3112
+ top: 0,
3113
+ left: 0
3114
+ } : computeOffset(placed, view.innerWidth, view.innerHeight);
3115
+ const style = frame?.getAttribute("style") ?? null;
3116
+ const offset = frame !== null && (move.top !== 0 || move.left !== 0);
3117
+ try {
3118
+ if (offset) {
3119
+ frame.setAttribute("style", `${style ?? ""};top:${String(move.top)}px !important;left:${String(move.left)}px !important;will-change:transform`);
3120
+ await waitForFrame();
3121
+ await waitForFrame();
3122
+ }
3123
+ shot = await page.screenshot({
3124
+ element,
3125
+ path: options.path,
3126
+ base64: true
3127
+ });
3128
+ } finally {
3129
+ if (offset && style === null) frame.removeAttribute("style");
3130
+ else if (offset && style !== null) frame.setAttribute("style", style);
3131
+ }
3132
+ }
3026
3133
  const segments = [];
3027
3134
  for (const segment of options.path.replaceAll("\\", "/").split("/")) {
3028
3135
  if (segment === "" || segment === ".") continue;
@@ -3033,7 +3140,15 @@ async function captureFrame(options) {
3033
3140
  if (await commands.readFile(shot.path, "base64") !== shot.base64) throw new Error(`Capture frame at ${options.path} is not the one this run shot`);
3034
3141
  return shot.path;
3035
3142
  } finally {
3036
- await releasePane();
3143
+ try {
3144
+ await releasePane();
3145
+ } finally {
3146
+ window.scrollTo({
3147
+ left: scroll.left,
3148
+ top: scroll.top,
3149
+ behavior: "instant"
3150
+ });
3151
+ }
3037
3152
  }
3038
3153
  }
3039
3154
  /**
@@ -3053,6 +3168,11 @@ async function captureFrame(options) {
3053
3168
  * against its own root rather than against the calling test file, so a relative path names a file
3054
3169
  * somewhere else.
3055
3170
  *
3171
+ * A file that opens with a PNG header and still does not decode is refused with the size that header
3172
+ * declares, in device pixels:
3173
+ * `Capture frame at <path> is not an image this browser decodes: <w>x<h> device pixels`.
3174
+ * A file with no PNG header is refused without a size.
3175
+ *
3056
3176
  * @example
3057
3177
  * ```ts
3058
3178
  * const reading = await readFrame(written)
@@ -3065,6 +3185,11 @@ async function readFrame(path) {
3065
3185
  const image = new Image();
3066
3186
  image.src = `data:image/png;base64,${encoded}`;
3067
3187
  await image.decode().catch((cause) => {
3188
+ const header = atob(encoded.slice(0, 32));
3189
+ if (header.startsWith("‰PNG\r\n\n") && header.slice(12, 16) === "IHDR") {
3190
+ const view = new DataView(Uint8Array.from(header, (byte) => byte.charCodeAt(0)).buffer);
3191
+ if (view.byteLength >= 24) throw new Error(`Capture frame at ${path} is not an image this browser decodes: ${String(view.getUint32(16))}x${String(view.getUint32(20))} device pixels`, { cause });
3192
+ }
3068
3193
  throw new Error(`Capture frame at ${path} is not an image this browser decodes`, { cause });
3069
3194
  });
3070
3195
  const context = new OffscreenCanvas(image.width, image.height).getContext("2d");
@@ -3772,6 +3897,6 @@ function createHarness(options) {
3772
3897
  };
3773
3898
  }
3774
3899
  //#endregion
3775
- export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, commitInput, computeNamePattern, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveRendered, sendProtocol, stageMedia, stagePane, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
3900
+ export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGINGS, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, commitInput, computeNamePattern, computeOffset, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, createChannel, createDragEvent, createHarness, createJournal, createPointerEvent, createPortfolio, createStorage, describeFocus, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, measureContent, measureContrast, measureLuminance, mount, parseCSSColor, parseColor, pressKeys, readBackdrop, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readContrast, readFocus, readFrame, readHit, readLayers, readName, readPage, readPerception, readPixels, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveRendered, sendProtocol, stageMedia, stagePane, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, waitForAnimations, waitForFrame, waitForState };
3776
3901
 
3777
3902
  //# sourceMappingURL=index.js.map