@orkestrel/test 0.0.24 → 0.0.26

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.
@@ -274,18 +274,22 @@ 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 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.
277
+ * Omit the `element` option to shoot the whole page. An element that fits with its native scroll
278
+ * clearance is shot in the declared pane, as is a short fixed panel that native alignment cannot
279
+ * move. A sticky subject with a vertical start inset also keeps that pane when native end alignment
280
+ * fits its box inside it; adding the start clearance would instead grow its viewport constraint.
281
+ * These subjects' viewport lengths resolve against the declared viewport. Otherwise native start
282
+ * alignment resolves the document's scroll clearance before the re-reading takes the element's
283
+ * height plus the space above its aligned top. This includes an element shorter than the declared
284
+ * pane whose height plus clearance exceeds it. The pane reserves room below authored scroll
285
+ * padding and target scroll margins without interpreting CSS lengths or hiding overlays.
286
+ * Clearance that changes with the viewport participates in the same bounded settling loop; a
287
+ * frame that has not settled within that bound is refused with the same text.
284
288
  *
285
289
  * Where the element's box lies outside the pane, the tester's document is scrolled by the nearest
286
290
  * 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.
291
+ * take a scroll that does not move it, and that scroll is handed back with the rest. Other short
292
+ * elements keep their nearest native alignment when they need no additional room.
289
293
  *
290
294
  * The provider paints an element that fits the runner's window only where that window shows it.
291
295
  * Where such an element lies past the window, the calling tester frame is offset up or left only as
@@ -934,7 +938,7 @@ export declare function createJournal(): JournalInterface;
934
938
  export declare function createPointerEvent(name: string, options?: PointerEventInit): PointerEvent;
935
939
 
936
940
  /**
937
- * Creates the capture portfolio one run places its screenshots through.
941
+ * Creates the capture portfolio one run places its screenshots through; a disabled run still refuses.
938
942
  *
939
943
  * @param options - The state registry, the variant matrix, the variant this run renders, the
940
944
  * directory it writes into, and whether it writes at all.
@@ -943,9 +947,11 @@ export declare function createPointerEvent(name: string, options?: PointerEventI
943
947
  *
944
948
  * @remarks
945
949
  * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
946
- * records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for
947
- * none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an
948
- * unregistered state name and a second placement of one state.
950
+ * records no placement, so a journey calls it unconditionally and a suite with the flag unset pays
951
+ * for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled or not,
952
+ * refuses an unregistered state name and a second placement of one state, so a wrong name fails the
953
+ * ordinary run. A disabled run keeps the names it has seen apart from `placements`, which stays
954
+ * empty.
949
955
  *
950
956
  * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
951
957
  * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
@@ -3032,18 +3032,22 @@ async function releaseMedia() {
3032
3032
  * `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
3033
3033
  * written at a height that is already wrong.
3034
3034
  *
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.
3035
+ * Omit the `element` option to shoot the whole page. An element that fits with its native scroll
3036
+ * clearance is shot in the declared pane, as is a short fixed panel that native alignment cannot
3037
+ * move. A sticky subject with a vertical start inset also keeps that pane when native end alignment
3038
+ * fits its box inside it; adding the start clearance would instead grow its viewport constraint.
3039
+ * These subjects' viewport lengths resolve against the declared viewport. Otherwise native start
3040
+ * alignment resolves the document's scroll clearance before the re-reading takes the element's
3041
+ * height plus the space above its aligned top. This includes an element shorter than the declared
3042
+ * pane whose height plus clearance exceeds it. The pane reserves room below authored scroll
3043
+ * padding and target scroll margins without interpreting CSS lengths or hiding overlays.
3044
+ * Clearance that changes with the viewport participates in the same bounded settling loop; a
3045
+ * frame that has not settled within that bound is refused with the same text.
3042
3046
  *
3043
3047
  * Where the element's box lies outside the pane, the tester's document is scrolled by the nearest
3044
3048
  * 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.
3049
+ * take a scroll that does not move it, and that scroll is handed back with the rest. Other short
3050
+ * elements keep their nearest native alignment when they need no additional room.
3047
3051
  *
3048
3052
  * The provider paints an element that fits the runner's window only where that window shows it.
3049
3053
  * Where such an element lies past the window, the calling tester frame is offset up or left only as
@@ -3083,7 +3087,64 @@ async function captureFrame(options) {
3083
3087
  let covered;
3084
3088
  let growth = 0;
3085
3089
  for (let staging = 0;; staging += 1) {
3086
- const reading = Math.max(element === void 0 ? measureContent() : Math.ceil(element.getBoundingClientRect().height), options.height);
3090
+ let height = element?.getBoundingClientRect().height;
3091
+ if (element !== void 0 && height !== void 0 && height > options.height) {
3092
+ element.scrollIntoView({
3093
+ block: "start",
3094
+ inline: "nearest",
3095
+ behavior: "instant"
3096
+ });
3097
+ const aligned = element.getBoundingClientRect();
3098
+ height = aligned.height + Math.max(0, aligned.top);
3099
+ } else if (element !== void 0 && height !== void 0) {
3100
+ const padding = readStyle(document.documentElement, "scroll-padding-top");
3101
+ const margin = readStyle(element, "scroll-margin-top");
3102
+ if (padding !== "auto" && padding !== "0px" || margin !== "0px") {
3103
+ element.scrollIntoView({
3104
+ block: "nearest",
3105
+ inline: "nearest",
3106
+ behavior: "instant"
3107
+ });
3108
+ if (element.getBoundingClientRect().bottom >= options.height) {
3109
+ let placement = {
3110
+ left: window.scrollX,
3111
+ top: window.scrollY
3112
+ };
3113
+ element.scrollIntoView({
3114
+ block: "start",
3115
+ inline: "nearest",
3116
+ behavior: "instant"
3117
+ });
3118
+ const aligned = element.getBoundingClientRect();
3119
+ if (aligned.bottom > options.height) {
3120
+ element.scrollIntoView({
3121
+ block: "end",
3122
+ inline: "nearest",
3123
+ behavior: "instant"
3124
+ });
3125
+ const end = element.getBoundingClientRect();
3126
+ const sticky = readStyle(element, "position") === "sticky" && readStyle(element, "top") !== "auto" && end.top >= 0 && end.bottom <= pane;
3127
+ if (sticky) placement = {
3128
+ left: window.scrollX,
3129
+ top: window.scrollY
3130
+ };
3131
+ if (!sticky && (pane > options.height || end.top !== aligned.top)) {
3132
+ height = aligned.height + Math.max(0, aligned.top);
3133
+ element.scrollIntoView({
3134
+ block: "start",
3135
+ inline: "nearest",
3136
+ behavior: "instant"
3137
+ });
3138
+ }
3139
+ }
3140
+ if (height <= options.height) window.scrollTo({
3141
+ ...placement,
3142
+ behavior: "instant"
3143
+ });
3144
+ }
3145
+ }
3146
+ }
3147
+ const reading = Math.max(height === void 0 ? measureContent() : Math.ceil(height), options.height);
3087
3148
  if (covered !== void 0) growth = Math.max(0, reading - covered);
3088
3149
  covered = reading;
3089
3150
  if (pane === covered) break;
@@ -3490,7 +3551,7 @@ function createDragEvent(name, options) {
3490
3551
  });
3491
3552
  }
3492
3553
  /**
3493
- * Creates the capture portfolio one run places its screenshots through.
3554
+ * Creates the capture portfolio one run places its screenshots through; a disabled run still refuses.
3494
3555
  *
3495
3556
  * @param options - The state registry, the variant matrix, the variant this run renders, the
3496
3557
  * directory it writes into, and whether it writes at all.
@@ -3499,9 +3560,11 @@ function createDragEvent(name, options) {
3499
3560
  *
3500
3561
  * @remarks
3501
3562
  * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
3502
- * records nothing, so a journey calls it unconditionally and a suite with the flag unset pays for
3503
- * none of it. The portfolio refuses an unregistered variant at creation. An enabled run refuses an
3504
- * unregistered state name and a second placement of one state.
3563
+ * records no placement, so a journey calls it unconditionally and a suite with the flag unset pays
3564
+ * for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled or not,
3565
+ * refuses an unregistered state name and a second placement of one state, so a wrong name fails the
3566
+ * ordinary run. A disabled run keeps the names it has seen apart from `placements`, which stays
3567
+ * empty.
3505
3568
  *
3506
3569
  * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
3507
3570
  * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
@@ -3526,6 +3589,7 @@ function createPortfolio(options) {
3526
3589
  const enabled = options.enabled ?? false;
3527
3590
  const placed = [];
3528
3591
  const paths = [];
3592
+ const seen = [];
3529
3593
  return {
3530
3594
  variant: options.variant,
3531
3595
  files,
@@ -3536,9 +3600,12 @@ function createPortfolio(options) {
3536
3600
  return [...paths];
3537
3601
  },
3538
3602
  async place(state, element) {
3539
- if (!enabled) return void 0;
3540
3603
  if (!registry.includes(state)) throw new Error(`Capture state "${state}" is not registered`);
3541
- if (placed.includes(state)) throw new Error(`Capture state "${state}" is already placed`);
3604
+ if (placed.includes(state) || seen.includes(state)) throw new Error(`Capture state "${state}" is already placed`);
3605
+ if (!enabled) {
3606
+ seen.push(state);
3607
+ return;
3608
+ }
3542
3609
  const file = `${state}--${options.variant}.png`;
3543
3610
  selected.apply?.();
3544
3611
  const written = await captureFrame({