@orkestrel/test 0.0.35 → 0.0.36

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.
@@ -351,6 +351,30 @@ var CAPTURE_STAGE_LIMIT = 4;
351
351
  * the marker stays four bits and release leaves touch emulation alone.
352
352
  */
353
353
  var MEDIA_STAGE = "data-media-stage";
354
+ /**
355
+ * Bounds the characters of the region locator a capture refusal names.
356
+ *
357
+ * @remarks
358
+ * `captureFrame` names each scroll region it leaves hiding rows by the path `renderSelector`
359
+ * renders. The path carries ids the page wrote, so it is cut to this many characters from its end,
360
+ * which keeps the steps nearest the region, and JSON-encoded, so a page-authored id can neither
361
+ * fake the message nor grow it without bound.
362
+ */
363
+ var CAPTURE_LABEL_LIMIT = 120;
364
+ /**
365
+ * Lists the form controls an unrolled frame leaves scrolled.
366
+ *
367
+ * @remarks
368
+ * A text area or a list box that overflows computes a scrolling overflow of its own, but its rows
369
+ * are the control's value rather than the page's layout, and no style the page could change would
370
+ * show them all. `collectUnrolledRegions` therefore leaves these elements out, so an unrolled frame
371
+ * neither grows for them nor refuses over them.
372
+ */
373
+ var CAPTURE_CONTROLS = Object.freeze([
374
+ "input",
375
+ "select",
376
+ "textarea"
377
+ ]);
354
378
  // src/browser/captures/helpers.ts
355
379
  /**
356
380
  * Reads one resolved CSS length as a number of pixels.
@@ -539,6 +563,270 @@ function clipsOverflow(element) {
539
563
  return readStyle(element, "overflow-y") !== "visible" || /\b(?:paint|content|strict)\b/u.test(readStyle(element, "contain"));
540
564
  }
541
565
  /**
566
+ * Collects the scroll containers in an element's subtree, the element included unless it is the
567
+ * body or the root element.
568
+ *
569
+ * @param element - The element whose subtree to walk. Default: the document's body.
570
+ * @returns Every element whose computed `overflow-x` or `overflow-y` value is the `auto` keyword,
571
+ * the `scroll` keyword, or the `hidden` keyword, in document order, and an empty list where the
572
+ * subtree holds none.
573
+ *
574
+ * @remarks
575
+ * Each of those keywords makes an element a scroll container, so script and `scrollIntoView` can
576
+ * move its scroll position whether or not it shows a scrollbar; the `clip` keyword and the `visible`
577
+ * keyword do not. The walk descends into each open shadow root after the host's own children. A
578
+ * closed shadow root is unreachable, so its containers stay out of the list. The body and the root
579
+ * element are left out, because their scroll is the window's.
580
+ *
581
+ * @example
582
+ * ```ts
583
+ * const placements = collectScrollContainers().map((container) => container.scrollTop)
584
+ * ```
585
+ */
586
+ function collectScrollContainers(element = document.body) {
587
+ const scrolls = element !== document.body && element !== document.documentElement && [readStyle(element, "overflow-x"), readStyle(element, "overflow-y")].some((overflow) => overflow === "auto" || overflow === "scroll" || overflow === "hidden");
588
+ const children = [...element.children, ...element.shadowRoot?.children ?? []];
589
+ return [...scrolls ? [element] : [], ...children.flatMap((child) => collectScrollContainers(child))];
590
+ }
591
+ /**
592
+ * Collects the vertical scroll regions an unrolled frame releases in an element's subtree, the
593
+ * element included unless it is the body or the root element.
594
+ *
595
+ * @param element - The element whose subtree to walk and whose box is the frame. Default: the
596
+ * document's body, whose frame is the page: the window's width, from the document's top down.
597
+ * @returns Every scroll container the {@link collectScrollContainers} helper finds whose computed
598
+ * `overflow-y` value is the `auto` keyword or the `scroll` keyword, whose `scrollHeight` exceeds its
599
+ * `clientHeight`, that the page shows, that is no form control, and whose box overlaps the frame,
600
+ * in document order.
601
+ *
602
+ * @remarks
603
+ * A region's hidden rows are its `scrollHeight` minus its `clientHeight`. A `hidden` overflow and a
604
+ * `clip` overflow are left out, because a page that hides rows there hides them by design. An
605
+ * `overflow-x: auto` wrapper computes an `overflow-y` value of `auto` too, so it is left out only
606
+ * where its rows fit. A text area, a list box, and an input, which {@link CAPTURE_CONTROLS} names,
607
+ * are left out, because their rows are the control's value. A region `checkVisibility` reports
608
+ * unshown, its `visibility` read included, is left out; the journey reader `isRendered` is not the
609
+ * test, because a region marked `aria-hidden` still paints. A region whose box lies wholly outside
610
+ * the frame, such as a navigation drawer a transform moves off the page, is left out. The walk
611
+ * reaches open shadow roots; a region inside a closed shadow root is unreachable and is left out.
612
+ * The `collectScrollRegions` journey reader answers a different question, which boxes a person can
613
+ * scroll on either axis, and reads no shadow root.
614
+ *
615
+ * @example
616
+ * ```ts
617
+ * const hidden = collectUnrolledRegions().reduce(
618
+ * (sum, region) => sum + region.scrollHeight - region.clientHeight,
619
+ * 0,
620
+ * )
621
+ * ```
622
+ */
623
+ function collectUnrolledRegions(element) {
624
+ const frame = element === void 0 || element === document.body || element === document.documentElement ? new DOMRectReadOnly(0, -window.scrollY, window.innerWidth, Number.POSITIVE_INFINITY) : element.getBoundingClientRect();
625
+ return collectScrollContainers(element).filter((region) => {
626
+ const overflow = readStyle(region, "overflow-y");
627
+ if (overflow !== "auto" && overflow !== "scroll") return false;
628
+ if (region.scrollHeight <= region.clientHeight) return false;
629
+ if (CAPTURE_CONTROLS.includes(region.localName)) return false;
630
+ if (!region.checkVisibility({ visibilityProperty: true })) return false;
631
+ const box = region.getBoundingClientRect();
632
+ return box.right > frame.left && box.left < frame.right && box.bottom > frame.top && box.top < frame.bottom;
633
+ });
634
+ }
635
+ /**
636
+ * Reports whether an element is the containing block of the fixed-position boxes inside it.
637
+ *
638
+ * @param element - The element to read.
639
+ * @returns True if the element's computed `transform`, `translate`, `rotate`, `scale`,
640
+ * `perspective`, `filter`, or `backdrop-filter` value is other than the `none` keyword, its
641
+ * computed `contain` value carries layout or paint containment, its computed `container-type`
642
+ * value is the `size` keyword or the `inline-size` keyword, its computed `content-visibility`
643
+ * value is the `auto` keyword, its computed `transform-style` value is the `preserve-3d` keyword,
644
+ * or its computed `will-change` value names one of those transforming or filtering properties;
645
+ * false otherwise.
646
+ *
647
+ * @remarks
648
+ * A fixed-position box is laid out against the viewport unless an ancestor takes that role, and
649
+ * each of the listed properties makes the element take it. Every element this reports true for
650
+ * also contains absolutely positioned boxes. A containing block another property establishes is not
651
+ * read here.
652
+ *
653
+ * @example
654
+ * ```ts
655
+ * containsFixed(build('div', { attributes: { style: 'transform: translateZ(0)' } })) // true
656
+ * ```
657
+ */
658
+ function containsFixed(element) {
659
+ return [
660
+ "transform",
661
+ "translate",
662
+ "rotate",
663
+ "scale",
664
+ "perspective",
665
+ "filter",
666
+ "backdrop-filter"
667
+ ].some((property) => readStyle(element, property) !== "none") || /\b(?:layout|paint|strict|content)\b/u.test(readStyle(element, "contain")) || /\bsize\b/u.test(readStyle(element, "container-type")) || readStyle(element, "content-visibility") === "auto" || readStyle(element, "transform-style") === "preserve-3d" || /\b(?:transform|translate|rotate|scale|perspective|filter|backdrop-filter)\b/u.test(readStyle(element, "will-change"));
668
+ }
669
+ /**
670
+ * Collects the elements under an element in the flat tree, in the order a browser paints them.
671
+ *
672
+ * @param element - The element whose content to walk.
673
+ * @returns Every element under it, each followed by its own content.
674
+ *
675
+ * @remarks
676
+ * The walk goes into a host's open shadow root in place of its light children, and from a slot to
677
+ * the elements assigned to it, or to its own children where none is assigned. A closed shadow root
678
+ * is unreachable, so a host carrying one is walked through its light children.
679
+ *
680
+ * @example
681
+ * ```ts
682
+ * collectFlatDescendants(host).length
683
+ * ```
684
+ */
685
+ function collectFlatDescendants(element) {
686
+ return (element.shadowRoot !== null ? [...element.shadowRoot.children] : element instanceof HTMLSlotElement && element.assignedElements().length > 0 ? element.assignedElements({ flatten: true }) : [...element.children]).flatMap((child) => [child, ...collectFlatDescendants(child)]);
687
+ }
688
+ /**
689
+ * Collects an element's ancestors in the flat tree, nearest first, up to and including a region.
690
+ *
691
+ * @param element - The element to climb from.
692
+ * @param region - The ancestor the climb stops at.
693
+ * @returns Every ancestor from the element's flat parent to the region, and every ancestor to the
694
+ * root element where the region is none of them.
695
+ *
696
+ * @remarks
697
+ * A step goes to the slot an element is assigned to, else to its parent element, else to the host
698
+ * of the shadow root it stands in, as {@link collectClippingAncestors} climbs.
699
+ *
700
+ * @example
701
+ * ```ts
702
+ * collectFlatAncestors(row, region).at(-1) === region // true for a row inside the region
703
+ * ```
704
+ */
705
+ function collectFlatAncestors(element, region) {
706
+ const scope = element.getRootNode();
707
+ const parent = element.assignedSlot ?? element.parentElement ?? (scope instanceof ShadowRoot ? scope.host : null);
708
+ if (parent === null) return [];
709
+ return parent === region ? [parent] : [parent, ...collectFlatAncestors(parent, region)];
710
+ }
711
+ /**
712
+ * Collects the elements under a scroll region whose boxes lay out in its scrollable area, walking
713
+ * the flat tree.
714
+ *
715
+ * @param region - The scroll region whose content to walk.
716
+ * @returns Every element {@link collectFlatDescendants} reaches under the region, in flat-tree
717
+ * order, less each fixed or absolute box whose containing block lies outside the region and
718
+ * everything inside that box.
719
+ *
720
+ * @remarks
721
+ * A box whose containing block lies outside the region adds nothing to the region's scroll height.
722
+ * For each fixed-position element, the climb from it to the region, which
723
+ * {@link collectFlatAncestors} takes, looks for an ancestor {@link containsFixed} reports true for;
724
+ * for each absolutely positioned element, it looks for such an ancestor or a positioned one. An
725
+ * element whose climb finds none is left out with its content. A `:modal` dialog and a
726
+ * `:popover-open` element are laid out in the top layer, which a transformed ancestor does not
727
+ * contain, so one under such an ancestor is counted as a row.
728
+ *
729
+ * @example
730
+ * ```ts
731
+ * const rows = collectRegionRows(region)
732
+ * ```
733
+ */
734
+ function collectRegionRows(region) {
735
+ const elements = collectFlatDescendants(region);
736
+ const loose = elements.filter((element) => {
737
+ const position = readStyle(element, "position");
738
+ if (position !== "fixed" && position !== "absolute") return false;
739
+ return !collectFlatAncestors(element, region).some((ancestor) => containsFixed(ancestor) || position === "absolute" && readStyle(ancestor, "position") !== "static");
740
+ });
741
+ const outside = new Set(loose.flatMap((element) => [element, ...collectFlatDescendants(element)]));
742
+ return elements.filter((element) => !outside.has(element));
743
+ }
744
+ /**
745
+ * Measures the rows a scroll region's content lays out, whether or not its box shows them all.
746
+ *
747
+ * @param region - The scroll container to read.
748
+ * @returns The height in CSS pixels from the top of the region's scrollable area to the bottom of
749
+ * its content plus its bottom padding, rounded up to a whole row.
750
+ *
751
+ * @remarks
752
+ * The `scrollHeight` property never reads less than the `clientHeight` property, so a region whose
753
+ * rows fit reads its box rather than its rows, and the slack under its last row cannot be read
754
+ * there. This reading can, because it is taken over the elements inside the region rather than
755
+ * over its box: each element contributes its bottom edge plus its own bottom margin, capped at the
756
+ * clip edge, as the {@link readClipEdge} helper measures it, of every clipping ancestor between it
757
+ * and the region, and the largest contribution wins. The region's scroll offset is added back, so
758
+ * a scrolled region reads the same rows as an unscrolled one. The elements are the ones
759
+ * {@link collectRegionRows} reaches through the flat tree, so a host's shadow rows and a slot's
760
+ * assigned rows count, and a fixed or absolute box laid out against a block outside the region
761
+ * does not, because it adds nothing to the region's scroll height.
762
+ *
763
+ * @example
764
+ * ```ts
765
+ * const slack = region.clientHeight - measureRegion(region)
766
+ * ```
767
+ */
768
+ function measureRegion(region) {
769
+ const origin = region.getBoundingClientRect().top + region.clientTop - region.scrollTop;
770
+ const edge = collectRegionRows(region).reduce((greatest, element) => {
771
+ const frames = collectClippingAncestors(element);
772
+ const limits = frames.slice(0, Math.max(0, frames.indexOf(region))).flatMap((frame) => {
773
+ const limit = readClipEdge(frame);
774
+ return limit === void 0 ? [] : [limit - window.scrollY];
775
+ });
776
+ const bottom = Math.min(element.getBoundingClientRect().bottom + readPixels(element, "margin-bottom"), ...limits);
777
+ return bottom > greatest ? bottom : greatest;
778
+ }, origin + readPixels(region, "padding-top"));
779
+ return Math.ceil(edge - origin + readPixels(region, "padding-bottom"));
780
+ }
781
+ /**
782
+ * Renders a selector path that locates an element from its nearest ancestor carrying an id.
783
+ *
784
+ * @param element - The element to locate.
785
+ * @returns A path of `>`-joined steps, each the tag name with an escaped `#id` where the element
786
+ * carries one and an `:nth-of-type()` position where a sibling shares its tag.
787
+ *
788
+ * @remarks
789
+ * The path starts at the nearest ancestor carrying an id, else at the body or the root element, so
790
+ * it stays short where the page names its landmarks. A step out of a shadow tree to its host is
791
+ * written ` >>> `, which no selector engine reads: the path locates the element for a person or an
792
+ * agent reading a refusal, and a closed shadow root is crossed the same way. The id is escaped with
793
+ * `CSS.escape`, so a step names the attribute value the page wrote.
794
+ *
795
+ * @example
796
+ * ```ts
797
+ * renderSelector(requireValue(document.querySelector('#stage main'))) // 'div#stage > main'
798
+ * ```
799
+ */
800
+ function renderSelector(element) {
801
+ if (element.id !== "") return `${element.localName}#${CSS.escape(element.id)}`;
802
+ if (element === document.body || element === document.documentElement) return element.localName;
803
+ const peers = Array.from(element.parentNode?.children ?? []).filter((peer) => peer.localName === element.localName);
804
+ const step = peers.length > 1 ? `${element.localName}:nth-of-type(${String(peers.indexOf(element) + 1)})` : element.localName;
805
+ if (element.parentElement !== null) return `${renderSelector(element.parentElement)} > ${step}`;
806
+ const root = element.getRootNode();
807
+ return root instanceof ShadowRoot ? `${renderSelector(root.host)} >>> ${step}` : step;
808
+ }
809
+ /**
810
+ * Renders the locator a capture refusal names an element by.
811
+ *
812
+ * @param element - The element to name.
813
+ * @returns The path {@link renderSelector} renders, cut to its last {@link CAPTURE_LABEL_LIMIT}
814
+ * characters behind a leading ellipsis where it is longer, and JSON-encoded.
815
+ *
816
+ * @remarks
817
+ * The path carries ids the page wrote. Keeping its end keeps the steps nearest the element, and the
818
+ * encoding keeps a page-authored id from faking or growing the message it stands in.
819
+ *
820
+ * @example
821
+ * ```ts
822
+ * renderLabel(requireValue(document.querySelector('#log'))) // '"div#log"'
823
+ * ```
824
+ */
825
+ function renderLabel(element) {
826
+ const path = renderSelector(element);
827
+ return JSON.stringify(path.length > 120 ? `…${path.slice(-119)}` : path);
828
+ }
829
+ /**
542
830
  * Measures the row the document's own content ends on, in document coordinates.
543
831
  *
544
832
  * @returns The content edge, rounded up to a whole row.
@@ -973,8 +1261,9 @@ async function releaseMedia() {
973
1261
  * @param options - The path to write, the viewport to shoot at, and the element to shoot.
974
1262
  * @returns The absolute path of the written frame, after it has been read back and matched.
975
1263
  * @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
976
- * element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when the provider wrote
977
- * the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
1264
+ * element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when an unrolled frame
1265
+ * leaves rows hidden in a scroll region, when the provider wrote the frame somewhere else, and when
1266
+ * the bytes on disk are not the ones this shot produced.
978
1267
  *
979
1268
  * @remarks
980
1269
  * The path a screenshot call returns is the path it meant to write, so it is not evidence a file
@@ -1056,8 +1345,39 @@ async function releaseMedia() {
1056
1345
  *
1057
1346
  * The pane is staged for the frame and released before this returns, on the failing path as well as
1058
1347
  * the passing one, which hands the tester back the viewport it had before the first staging. The
1059
- * tester's scroll position is restored after that release, on every path, a rejected release
1060
- * included.
1348
+ * tester's scroll position, and that of every scroll container {@link collectScrollContainers}
1349
+ * finds, is recorded before the first staging and restored after that release, on every path, a
1350
+ * rejected release included.
1351
+ *
1352
+ * Set the `unrolled` option to cover the rows each vertical scroll region hides. Every staging then
1353
+ * adds the hidden rows of each region {@link collectUnrolledRegions} finds, overlapping the element
1354
+ * for an element frame, to the edge it stages at, and the page's own layout grows a region bound to
1355
+ * the viewport with the pane; nothing is written to the page's styles. Hidden rows add up, which is
1356
+ * right for nested regions and too much for panes side by side, so after none of the regions that
1357
+ * hid rows at the first reading hides rows, each staging moves down by the smallest slack among
1358
+ * them, which {@link measureRegion} reads: a sidebar beside a taller main pane settles where the
1359
+ * main pane's last row ends. A region whose height did not change across a staging keeps a fixed
1360
+ * height, so its hidden rows stop counting and the staging settles without it. A layout that needs
1361
+ * more restagings than {@link CAPTURE_STAGE_LIMIT} allows is refused with the never-settled
1362
+ * refusal, which on an unrolled frame appends
1363
+ * `; scroll regions still hiding rows: <region> hides <n> px, …` for every region still hiding rows.
1364
+ *
1365
+ * A region that still hides rows after the settling refuses the shot with
1366
+ * `Capture frame at <path> leaves rows hidden in scroll regions: <region> <cause> and hides <n> px, so <correction>. Shoot the frame without unrolled to keep them scrolled`,
1367
+ * naming every such region. The cause and correction come from what was measured: a region that
1368
+ * kept its height across a staging, or kept the height it had at the declared viewport, `keeps a
1369
+ * fixed height`, so bound its height to the viewport; a region whose height changed as the pane
1370
+ * grew `grows by less than the pane`, so let it take all the height the pane adds; a region that
1371
+ * hid no rows at the declared viewport hides them `at the final reading`, so let its height follow
1372
+ * the viewport; and a region at a pane that never grew past the declared height hides its rows
1373
+ * `though the declared viewport has room for them`, so let it fill the viewport's remaining height.
1374
+ * Each region is named by the locator {@link renderLabel} renders.
1375
+ *
1376
+ * Three cases stay outside what an unrolled frame reads. A containing block that
1377
+ * {@link containsFixed} does not read counts a fixed or absolute box as a row, which ends in the
1378
+ * never-settled refusal naming the regions. A `:modal` dialog or a `:popover-open` element under a
1379
+ * transformed ancestor is counted as a row, though the top layer lays it out. A region inside a
1380
+ * closed shadow root is unreachable, so its rows stay hidden without a refusal.
1061
1381
  *
1062
1382
  * @example
1063
1383
  * ```ts
@@ -1070,10 +1390,29 @@ async function captureFrame(options) {
1070
1390
  left: window.scrollX,
1071
1391
  top: window.scrollY
1072
1392
  };
1393
+ const placements = collectScrollContainers().map((container) => ({
1394
+ container,
1395
+ left: container.scrollLeft,
1396
+ top: container.scrollTop
1397
+ }));
1073
1398
  const prepared = window.innerWidth === options.width && window.innerHeight === options.height;
1074
1399
  try {
1075
1400
  if (!prepared) await stagePane(options.width, options.height);
1076
- await settleFrame(options, element, prepared);
1401
+ const declared = new Map((options.unrolled === true ? collectUnrolledRegions(element) : []).map((region) => [region, region.clientHeight]));
1402
+ const fixed = await settleFrame(options, element, prepared);
1403
+ const scrolled = options.unrolled === true ? collectUnrolledRegions(element) : [];
1404
+ if (scrolled.length > 0) {
1405
+ const grown = window.innerHeight > options.height;
1406
+ const regions = scrolled.map((region) => {
1407
+ const label = renderLabel(region);
1408
+ const hides = String(region.scrollHeight - region.clientHeight);
1409
+ const before = declared.get(region);
1410
+ if (fixed.includes(region) || grown && before === region.clientHeight) return `${label} keeps a fixed height and hides ${hides} px, so bound its height to the viewport`;
1411
+ if (!grown) return `${label} hides ${hides} px though the declared viewport has room for them, so let it fill the viewport's remaining height`;
1412
+ return before === void 0 ? `${label} hides ${hides} px at the final reading, so let its height follow the viewport` : `${label} grows by less than the pane and hides ${hides} px, so let it take all the height the pane adds`;
1413
+ });
1414
+ throw new Error(`Capture frame at ${options.path} leaves rows hidden in scroll regions: ${regions.join("; ")}. Shoot the frame without unrolled to keep them scrolled`);
1415
+ }
1077
1416
  const shot = await takeFrameShot(options, element);
1078
1417
  await verifyFrame(shot, options.path, readCaptureReader());
1079
1418
  return shot.path;
@@ -1086,6 +1425,11 @@ async function captureFrame(options) {
1086
1425
  top: scroll.top,
1087
1426
  behavior: "instant"
1088
1427
  });
1428
+ for (const { container, left, top } of placements) container.scrollTo({
1429
+ left,
1430
+ top,
1431
+ behavior: "instant"
1432
+ });
1089
1433
  }
1090
1434
  }
1091
1435
  }
@@ -1285,28 +1629,50 @@ function expandCaptures(states, variants) {
1285
1629
  /**
1286
1630
  * Restages a capture until its content extent equals the pane height.
1287
1631
  *
1288
- * @remarks The stage limit bounds the recursion; a prepared pane is staged before accepting it.
1632
+ * @returns The regions an unrolled frame left out of its extent because each kept its height across
1633
+ * a staging, and an empty list for a plain frame.
1634
+ *
1635
+ * @remarks The stage limit bounds the recursion; a prepared pane is staged before accepting it. An
1636
+ * unrolled frame adds the rows its regions hide to the extent. `regions` maps each region tracked
1637
+ * so far to its height at the previous reading; omit it at the first call. A region whose height
1638
+ * did not change across a staging keeps a fixed height, so its hidden rows are left out of the
1639
+ * extent and out of the slack. After no other tracked region hides rows, the smallest slack among
1640
+ * the tracked regions that grew comes off the extent. A region a re-render disconnected is
1641
+ * dropped. The prepared restaging at the declared height reads afresh, because the pane did not
1642
+ * change. A staging the carried growth would land back on the current pane stages at the extent
1643
+ * instead, because a repeated pane reads every height unchanged. Thrown when the stage limit is
1644
+ * reached, naming on an unrolled frame every region still hiding rows.
1289
1645
  * @example
1290
1646
  * ```ts
1291
1647
  * await settleFrame({ path: 'frame.png', width: 390, height: 844 }, undefined, false)
1292
1648
  * ```
1293
1649
  */
1294
- async function settleFrame(options, element, prepared, pane = options.height, covered, stage = 0) {
1650
+ async function settleFrame(options, element, prepared, pane = options.height, covered, stage = 0, regions) {
1295
1651
  const height = readFrameHeight(options, element, pane);
1296
1652
  const measured = height === void 0 ? measureContent() : Math.ceil(height);
1297
- const extent = Math.max(measured, options.height);
1653
+ const hiding = options.unrolled === true ? collectUnrolledRegions(element) : [];
1654
+ const tracked = regions === void 0 ? hiding : [...regions.keys()].filter((region) => region.isConnected);
1655
+ const fixed = hiding.filter((region) => regions?.get(region) === region.clientHeight);
1656
+ const hidden = hiding.filter((region) => !fixed.includes(region)).reduce((sum, region) => sum + region.scrollHeight - region.clientHeight, 0);
1657
+ const growing = tracked.filter((region) => regions?.get(region) !== region.clientHeight);
1658
+ const slack = hidden === 0 && growing.length > 0 ? Math.max(0, Math.min(...growing.map((region) => region.clientHeight - measureRegion(region)))) : 0;
1659
+ const extent = Math.max(measured + hidden - slack, options.height);
1298
1660
  const growth = covered === void 0 ? 0 : Math.max(0, extent - covered);
1661
+ const heights = new Map([...tracked, ...hiding].map((region) => [region, region.clientHeight]));
1299
1662
  if (pane === extent) {
1300
1663
  if (prepared && stage === 0) {
1301
1664
  await stagePane(options.width, pane);
1302
1665
  return settleFrame(options, element, prepared, pane, extent, stage + 1);
1303
1666
  }
1304
- return;
1667
+ return fixed;
1668
+ }
1669
+ if (stage === 4) {
1670
+ const still = hiding.length > 0 ? `; scroll regions still hiding rows: ${hiding.map((region) => `${renderLabel(region)} hides ${String(region.scrollHeight - region.clientHeight)} px`).join(", ")}` : "";
1671
+ throw new Error(`Capture frame at ${options.path} never settled after ${String(4)} restagings: ${String(extent)} over a ${String(pane)} pane${still}`);
1305
1672
  }
1306
- if (stage === 4) throw new Error(`Capture frame at ${options.path} never settled after ${String(4)} restagings: ${String(extent)} over a ${String(pane)} pane`);
1307
- const next = extent + growth;
1673
+ const next = extent + growth === pane ? extent : extent + growth;
1308
1674
  await stagePane(options.width, next);
1309
- return settleFrame(options, element, prepared, next, extent, stage + 1);
1675
+ return settleFrame(options, element, prepared, next, extent, stage + 1, heights);
1310
1676
  }
1311
1677
  /**
1312
1678
  * Reads a capture subject's height after applying its native scroll clearance.
@@ -3044,7 +3410,7 @@ function readStates(element) {
3044
3410
  const live = element.getAttribute("aria-live");
3045
3411
  if (live !== null) states.push(`live=${live}`);
3046
3412
  if (element.matches(":required")) states.push("required");
3047
- if (element instanceof HTMLInputElement && element.readOnly) states.push("readonly");
3413
+ if ((element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) && element.readOnly) states.push("readonly");
3048
3414
  if (element.hasAttribute("aria-describedby")) states.push("described");
3049
3415
  if (element.getAttribute("aria-busy") === "true") states.push("busy");
3050
3416
  return Object.freeze(states);
@@ -3998,7 +4364,7 @@ function createKeyboardEvent(name, options) {
3998
4364
  *
3999
4365
  * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
4000
4366
  * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
4001
- * this run's own frame.
4367
+ * this run's own frame. The portfolio's `unrolled` option reaches every frame `place` writes.
4002
4368
  *
4003
4369
  * @example
4004
4370
  * ```ts
@@ -4042,7 +4408,8 @@ function createPortfolio(options) {
4042
4408
  path: `${options.directory}/${file}`,
4043
4409
  width: selected.width,
4044
4410
  height: selected.height,
4045
- element
4411
+ element,
4412
+ unrolled: options.unrolled
4046
4413
  });
4047
4414
  placed.push(state);
4048
4415
  paths.push(written);
@@ -5282,6 +5649,6 @@ function buildCensus() {
5282
5649
  mark
5283
5650
  });
5284
5651
  }
5285
- export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGE_LIMIT, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, FOCUS_SEGMENT_LIMIT, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, SEGMENTED_INPUT_TYPES, adoptSheet, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, chooseAccessible, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, collectClippingAncestors, collectScrollRegions, collectShadowHosts, collectTabStops, commitInput, computeNamePattern, computeOffset, containsNode, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, countElements, createDragEvent, createHarness, createJournal, createKeyboardEvent, createPointerEvent, createPortfolio, createStorage, describeFocus, describeScrollRegions, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findStyleRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, matchesTraversalName, measureContent, measureContrast, measureLuminance, mount, paintImage, parkPointer, parseCSSColor, parseColor, pressKeys, readAccessibilityNode, readActiveElement, readAnimations, readBackdrop, readCaptureReader, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readClippedBlock, readColorContrast, readContrast, readControlValue, readFocus, readFrame, readFrameHeight, readHit, readLayerNames, readLayers, readName, readPage, readPerception, readPixels, readProtocolNode, readProtocolPoint, readProtocolSession, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readShotPixel, readStates, readStyle, readText, readToken, recordConsole, releaseMedia, releasePane, releasePointer, releaseTouch, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveFileInput, resolveRendered, sendFileDrag, sendProtocol, sendTouch, settleCapture, settleFrame, stageMedia, stagePane, stepFocus, supportsSegmentedFocus, takeFrameShot, tapTouch, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, verifyFrame, waitForAnimations, waitForFrame, waitForStability, waitForState, walkFocus };
5652
+ export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_CONTROLS, CAPTURE_LABEL_LIMIT, CAPTURE_PANE, CAPTURE_STAGE_LIMIT, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, FOCUS_SEGMENT_LIMIT, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, SEGMENTED_INPUT_TYPES, adoptSheet, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, chooseAccessible, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, collectClippingAncestors, collectFlatAncestors, collectFlatDescendants, collectRegionRows, collectScrollContainers, collectScrollRegions, collectShadowHosts, collectTabStops, collectUnrolledRegions, commitInput, computeNamePattern, computeOffset, containsFixed, containsNode, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, countElements, createDragEvent, createHarness, createJournal, createKeyboardEvent, createPointerEvent, createPortfolio, createStorage, describeFocus, describeScrollRegions, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findStyleRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, matchesTraversalName, measureContent, measureContrast, measureLuminance, measureRegion, mount, paintImage, parkPointer, parseCSSColor, parseColor, pressKeys, readAccessibilityNode, readActiveElement, readAnimations, readBackdrop, readCaptureReader, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readClippedBlock, readColorContrast, readContrast, readControlValue, readFocus, readFrame, readFrameHeight, readHit, readLayerNames, readLayers, readName, readPage, readPerception, readPixels, readProtocolNode, readProtocolPoint, readProtocolSession, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readShotPixel, readStates, readStyle, readText, readToken, recordConsole, releaseMedia, releasePane, releasePointer, releaseTouch, removeDatabase, render, renderLabel, renderSelector, resolveAccessible, resolveAccessibleWithin, resolveFileInput, resolveRendered, sendFileDrag, sendProtocol, sendTouch, settleCapture, settleFrame, stageMedia, stagePane, stepFocus, supportsSegmentedFocus, takeFrameShot, tapTouch, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, verifyFrame, waitForAnimations, waitForFrame, waitForStability, waitForState, walkFocus };
5286
5653
 
5287
5654
  //# sourceMappingURL=index.js.map