@orkestrel/test 0.0.40 → 0.0.41

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.
@@ -530,11 +530,67 @@ function readClippedBlock(element) {
530
530
  */
531
531
  function collectClippingAncestors(element) {
532
532
  if (!element.isConnected) throw new Error("The element is not connected to a document, so it has no clipping ancestors to read");
533
+ const parent = readFlatParent(element);
534
+ if (parent === void 0) return [];
535
+ return [...clipsOverflow(parent) ? [parent] : [], ...collectClippingAncestors(parent)];
536
+ }
537
+ /**
538
+ * Reads an element's parent in the flat tree, the tree a browser paints.
539
+ *
540
+ * @param element - The element to step up from.
541
+ * @returns The slot the element is assigned to, else its parent element, else the host of the
542
+ * shadow root it stands in, and `undefined` for an element with none of the three.
543
+ *
544
+ * @remarks
545
+ * The `assignedSlot` property reports no slot of a closed shadow root, so a child assigned into one
546
+ * steps to its light parent instead.
547
+ *
548
+ * @example
549
+ * ```ts
550
+ * readFlatParent(slotted) // the slot it is assigned to, inside its parent's open shadow root
551
+ * ```
552
+ */
553
+ function readFlatParent(element) {
533
554
  const realm = element.ownerDocument.defaultView;
534
555
  const scope = element.getRootNode();
535
- const parent = element.assignedSlot ?? element.parentElement ?? (realm !== null && scope instanceof realm.ShadowRoot ? scope.host : null);
536
- if (parent === null) return [];
537
- return [...clipsOverflow(parent) ? [parent] : [], ...collectClippingAncestors(parent)];
556
+ return element.assignedSlot ?? element.parentElement ?? (realm !== null && scope instanceof realm.ShadowRoot ? scope.host : void 0);
557
+ }
558
+ /**
559
+ * Reads the lowest clip edge the clipping ancestors between an element and a region put on it.
560
+ *
561
+ * @param element - The element to read.
562
+ * @param region - The flat-tree ancestor the climb stops at, itself not counted.
563
+ * @param bounds - The memo one measurement shares across its elements, keyed by ancestor. Default:
564
+ * a fresh memo.
565
+ * @returns The lowest edge, in document coordinates, that the {@link readClipEdge} helper measures
566
+ * on a clipping ancestor strictly between the element and the region; `Infinity` where none of them
567
+ * clips; and `undefined` where the region is no flat-tree ancestor of the element.
568
+ * @throws Thrown when the element is not connected to a document, as the
569
+ * {@link collectClippingAncestors} helper throws.
570
+ *
571
+ * @remarks
572
+ * The climb takes the steps the {@link readFlatParent} helper reads, as the
573
+ * {@link collectClippingAncestors} helper does. Each ancestor's entry in `bounds` holds the bound it
574
+ * hands down: its own clip edge and every bound above it, up to the region. A measurement that
575
+ * reads every element of a subtree through one memo therefore reads each ancestor's style once,
576
+ * rather than once for every element under it.
577
+ *
578
+ * @example
579
+ * ```ts
580
+ * const bounds = new Map<Element, number | undefined>()
581
+ * readClipBound(row, document.body, bounds) // the edge of the nearest hidden frame around the row
582
+ * ```
583
+ */
584
+ function readClipBound(element, region, bounds = /* @__PURE__ */ new Map()) {
585
+ if (!element.isConnected) throw new Error("The element is not connected to a document, so it has no clipping ancestors to read");
586
+ const parent = readFlatParent(element);
587
+ if (parent === void 0) return void 0;
588
+ if (parent === region) return Number.POSITIVE_INFINITY;
589
+ if (bounds.has(parent)) return bounds.get(parent);
590
+ const above = readClipBound(parent, region, bounds);
591
+ const bound = above === void 0 ? void 0 : Math.min(readClipEdge(parent) ?? Number.POSITIVE_INFINITY, above);
592
+ bounds.set(parent, bound);
593
+ return bound;
538
594
  }
539
595
  /**
540
596
  * Reports whether an element clips its descendants' overflow.
@@ -752,9 +808,11 @@ function collectRegionRows(region) {
752
808
  * The `scrollHeight` property never reads less than the `clientHeight` property, so a region whose
753
809
  * rows fit reads its box rather than its rows, and the slack under its last row cannot be read
754
810
  * 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
811
+ * over its box: each element contributes its bottom edge plus its own bottom margin, and the
812
+ * largest contribution wins. Where the region itself clips its overflow, as the {@link clipsOverflow}
813
+ * helper reports it, each contribution is capped at the clip edge, as the {@link readClipEdge}
814
+ * helper measures it, of every clipping ancestor between the element and the region; where the
815
+ * region clips nothing, no contribution is capped. The region's scroll offset is added back, so
758
816
  * a scrolled region reads the same rows as an unscrolled one. The elements are the ones
759
817
  * {@link collectRegionRows} reaches through the flat tree, so a host's shadow rows and a slot's
760
818
  * assigned rows count, and a fixed or absolute box laid out against a block outside the region
@@ -767,13 +825,11 @@ function collectRegionRows(region) {
767
825
  */
768
826
  function measureRegion(region) {
769
827
  const origin = region.getBoundingClientRect().top + region.clientTop - region.scrollTop;
828
+ const bounds = /* @__PURE__ */ new Map();
829
+ const bounded = clipsOverflow(region);
770
830
  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);
831
+ const limit = bounded ? readClipBound(element, region, bounds) : void 0;
832
+ const bottom = Math.min(element.getBoundingClientRect().bottom + readPixels(element, "margin-bottom"), (limit ?? Number.POSITIVE_INFINITY) - window.scrollY);
777
833
  return bottom > greatest ? bottom : greatest;
778
834
  }, origin + readPixels(region, "padding-top"));
779
835
  return Math.ceil(edge - origin + readPixels(region, "padding-bottom"));
@@ -843,7 +899,7 @@ function renderLabel(element) {
843
899
  *
844
900
  * Each element contributes its client rectangle's bottom edge in document coordinates plus its own
845
901
  * bottom margin, which sits outside that rectangle, and the largest contribution wins. An ancestor
846
- * that clips its overflow, which the {@link collectClippingAncestors} helper finds through the flat
902
+ * that clips its overflow, which the {@link readClipBound} helper finds through the flat
847
903
  * tree and so reaches a shadow wrapper around a slot, caps the contribution at that ancestor's clip
848
904
  * edge, which the {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
849
905
  * frame are cut, scrolled, or discarded rather than added to the document: a viewport-height
@@ -868,12 +924,9 @@ function renderLabel(element) {
868
924
  * ```
869
925
  */
870
926
  function measureContent() {
927
+ const bounds = /* @__PURE__ */ new Map();
871
928
  const edge = Array.from(document.body.querySelectorAll("*")).reduce((greatest, element) => {
872
- const limits = collectClippingAncestors(element).filter((frame) => frame !== document.body && frame !== document.documentElement).flatMap((frame) => {
873
- const limit = readClipEdge(frame);
874
- return limit === void 0 ? [] : [limit];
875
- });
876
- const bottom = Math.min(element.getBoundingClientRect().bottom + window.scrollY + readPixels(element, "margin-bottom"), ...limits);
929
+ const bottom = Math.min(element.getBoundingClientRect().bottom + window.scrollY + readPixels(element, "margin-bottom"), readClipBound(element, document.body, bounds) ?? Number.POSITIVE_INFINITY);
877
930
  return bottom > greatest ? bottom : greatest;
878
931
  }, 0);
879
932
  return Math.ceil(edge + readPixels(document.body, "padding-bottom") + readPixels(document.body, "margin-bottom") + readPixels(document.documentElement, "padding-bottom") + readPixels(document.documentElement, "margin-bottom"));
@@ -889,17 +942,15 @@ function measureContent() {
889
942
  *
890
943
  * @remarks
891
944
  * This depends on the runner's own tester layout, and that dependency is contract rather than an
892
- * accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
893
- * the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
945
+ * accident: `vitest@5.1.0` lays its tester out inside a smaller page, fits it with a CSS scale, and
946
+ * clips whatever overflows the pane the tester sits in. Layout inside the tester is
894
947
  * unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
895
948
  * but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
896
949
  * a thumbnail of the surface and a frame shot after only unscaling it is a sliver. The tester is
897
950
  * therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
898
- * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
899
- * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
900
- * them reddens the size check that follows rather than writing a wrong frame.
901
- * The custom-property overrides serve Vitest 4; `transform: none !important` on the pane and
902
- * iframe also suppresses Vitest 5's direct CSS transform.
951
+ * selector and the `--viewport-width` and `--viewport-height` custom properties are the runner's, so
952
+ * a Vitest release that renames any of them reddens the size check that follows rather than writing
953
+ * a wrong frame. `transform: none !important` on the pane and iframe suppresses the fitting scale.
903
954
  *
904
955
  * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
905
956
  * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
@@ -910,9 +961,10 @@ function measureContent() {
910
961
  * there. Staging and releasing as a pair resizes and then undoes the resize, so the journey step
911
962
  * after it runs at the size the file started at.
912
963
  *
913
- * The rule is declared rather than written inline, because the runner writes its own scale onto the
914
- * pane as inline custom properties and rewrites them whenever the tester resizes. A declared rule
915
- * marked important outranks an inline value and survives every rewrite. It finds the pane by the
964
+ * The rule is declared rather than written inline, because the runner writes its scale as an inline
965
+ * `transform` on the tester's iframe and the viewport as inline custom properties on the body, and
966
+ * rewrites them whenever the tester resizes. A declared rule marked important outranks an inline
967
+ * value and survives every rewrite. It finds the pane by the
916
968
  * tester it contains as well as by {@link CAPTURE_PANE}, because a re-render between the staging and
917
969
  * the shot replaces the node and takes any attribute of ours with it.
918
970
  *
@@ -943,7 +995,7 @@ async function stagePane(width, height) {
943
995
  rule.setAttribute(CAPTURE_PANE, viewport);
944
996
  rule.textContent = [
945
997
  `[${CAPTURE_PANE}],:has(>iframe[data-vitest])`,
946
- "{--tester-transform:none !important;--tester-margin-left:0px !important;transform:none !important}",
998
+ "{transform:none !important}",
947
999
  "iframe[data-vitest]",
948
1000
  "{transform:none !important;position:fixed !important;left:0 !important;top:0 !important;right:auto !important;",
949
1001
  "bottom:auto !important;width:var(--viewport-width) !important;",
@@ -1379,6 +1431,9 @@ async function releaseMedia() {
1379
1431
  * transformed ancestor is counted as a row, though the top layer lays it out. A region inside a
1380
1432
  * closed shadow root is unreachable, so its rows stay hidden without a refusal.
1381
1433
  *
1434
+ * To shoot the declared viewport at the scroll the page holds rather than the document, call
1435
+ * {@link captureViewport}.
1436
+ *
1382
1437
  * @example
1383
1438
  * ```ts
1384
1439
  * await captureFrame({ path: '../../tmp/capture/start.png', width: 390, height: 844 })
@@ -1386,15 +1441,7 @@ async function releaseMedia() {
1386
1441
  */
1387
1442
  async function captureFrame(options) {
1388
1443
  const element = options.element;
1389
- const scroll = {
1390
- left: window.scrollX,
1391
- top: window.scrollY
1392
- };
1393
- const placements = collectScrollContainers().map((container) => ({
1394
- container,
1395
- left: container.scrollLeft,
1396
- top: container.scrollTop
1397
- }));
1444
+ const restore = recordScroll();
1398
1445
  const prepared = window.innerWidth === options.width && window.innerHeight === options.height;
1399
1446
  try {
1400
1447
  if (!prepared) await stagePane(options.width, options.height);
@@ -1420,20 +1467,132 @@ async function captureFrame(options) {
1420
1467
  try {
1421
1468
  await releasePane();
1422
1469
  } finally {
1423
- window.scrollTo({
1424
- left: scroll.left,
1425
- top: scroll.top,
1426
- behavior: "instant"
1427
- });
1428
- for (const { container, left, top } of placements) container.scrollTo({
1429
- left,
1430
- top,
1431
- behavior: "instant"
1432
- });
1470
+ restore();
1471
+ }
1472
+ }
1473
+ }
1474
+ /**
1475
+ * Shoots the declared viewport at the scroll the page holds and proves the file on disk holds this
1476
+ * run's bytes.
1477
+ *
1478
+ * @param options - The path to write and the viewport to shoot at.
1479
+ * @returns The absolute path of the written frame, after it has been read back and matched.
1480
+ * @throws Thrown when the pane cannot be staged, when the cover cannot lay out over the viewport,
1481
+ * when the provider wrote the frame somewhere else, and when the bytes on disk are not the ones this
1482
+ * shot produced.
1483
+ *
1484
+ * @remarks
1485
+ * The pane is staged at the declared viewport alone, no height is measured, and no taller pane is
1486
+ * staged, so a mark the scroll drives keeps naming what the viewport shows. A tester that is not at
1487
+ * the declared viewport is resized to it first, and the frame then holds the scroll the page keeps
1488
+ * at that size. The shot is taken of a transparent fixed box, the cover, appended to the root
1489
+ * element and removed on every path; the cover sends no pointer input and receives none. Its
1490
+ * `position`, `inset`, `opacity`, and `pointer-events` declarations are set inline as important, so
1491
+ * a page rule marked important does not paint it over the shot.
1492
+ *
1493
+ * The cover's box is read after it is appended, and a box that does not start at the viewport's
1494
+ * origin at the viewport's size refuses the shot with
1495
+ * `Capture frame at <path> cannot cover the viewport: a fixed box on the root element lays out at <w>x<h> from (<x>, <y>) in a <w>x<h> viewport`.
1496
+ * The check reads the box, not its cause: a root element that becomes the cover's containing block,
1497
+ * through a transform or a paint containment, lays the cover out over its own box, so the shot is
1498
+ * refused wherever that box differs from the viewport, as a scrolled or a taller document's does,
1499
+ * and taken where the two coincide.
1500
+ *
1501
+ * The pane is released and the scroll of the window and of every scroll container
1502
+ * {@link collectScrollContainers} finds is restored before this returns, on every path, as
1503
+ * {@link captureFrame} does. The file is verified as {@link verifyFrame} verifies it.
1504
+ *
1505
+ * @example
1506
+ * ```ts
1507
+ * await captureViewport({ path: '../../tmp/capture/contents.png', width: 390, height: 844 })
1508
+ * ```
1509
+ */
1510
+ async function captureViewport(options) {
1511
+ const restore = recordScroll();
1512
+ const cover = document.createElement("div");
1513
+ try {
1514
+ await stagePane(options.width, options.height);
1515
+ cover.setAttribute("aria-hidden", "true");
1516
+ cover.style.setProperty("position", "fixed", "important");
1517
+ cover.style.setProperty("inset", "0", "important");
1518
+ cover.style.setProperty("opacity", "0", "important");
1519
+ cover.style.setProperty("pointer-events", "none", "important");
1520
+ document.documentElement.append(cover);
1521
+ const box = cover.getBoundingClientRect();
1522
+ const { clientWidth, clientHeight } = document.documentElement;
1523
+ if (box.x !== 0 || box.y !== 0 || box.width !== clientWidth || box.height !== clientHeight) throw new Error(`Capture frame at ${options.path} cannot cover the viewport: a fixed box on the root element lays out at ${String(box.width)}x${String(box.height)} from (${String(box.x)}, ${String(box.y)}) in a ${String(clientWidth)}x${String(clientHeight)} viewport`);
1524
+ const shot = await takeFrameShot(options, cover);
1525
+ await verifyFrame(shot, options.path, readCaptureReader());
1526
+ return shot.path;
1527
+ } finally {
1528
+ cover.remove();
1529
+ try {
1530
+ await releasePane();
1531
+ } finally {
1532
+ restore();
1433
1533
  }
1434
1534
  }
1435
1535
  }
1436
1536
  /**
1537
+ * Records the scroll position of the tester's window and of every scroll container in its body, and
1538
+ * returns the callback that scrolls each of them back.
1539
+ *
1540
+ * @returns A callback that scrolls the window and each recorded container back to the position this
1541
+ * call read, instantly.
1542
+ *
1543
+ * @remarks
1544
+ * The containers are the ones {@link collectScrollContainers} finds when this is called. A capture
1545
+ * records them before its first staging, because growing a region clamps its scroll position and an
1546
+ * element frame's alignment scrolls a container too, and restores them after the pane is released.
1547
+ *
1548
+ * @example
1549
+ * ```ts
1550
+ * const restore = recordScroll()
1551
+ * window.scrollTo({ top: 600, behavior: 'instant' })
1552
+ * restore() // the window is back at the scroll it held
1553
+ * ```
1554
+ */
1555
+ function recordScroll() {
1556
+ const left = window.scrollX;
1557
+ const top = window.scrollY;
1558
+ const placements = collectScrollContainers().map((container) => ({
1559
+ container,
1560
+ left: container.scrollLeft,
1561
+ top: container.scrollTop
1562
+ }));
1563
+ return () => {
1564
+ window.scrollTo({
1565
+ left,
1566
+ top,
1567
+ behavior: "instant"
1568
+ });
1569
+ for (const placement of placements) placement.container.scrollTo({
1570
+ left: placement.left,
1571
+ top: placement.top,
1572
+ behavior: "instant"
1573
+ });
1574
+ };
1575
+ }
1576
+ /**
1577
+ * Describes the refusal of a viewport placement in an unrolled portfolio.
1578
+ *
1579
+ * @param state - The state the placement named.
1580
+ * @returns The refusal, naming the state and the two placements that can shoot it.
1581
+ *
1582
+ * @remarks
1583
+ * An unrolled portfolio covers every row each scroll region hides, and a viewport frame covers the
1584
+ * rows the scroll shows, so a portfolio refuses the pairing in every run, written or not.
1585
+ *
1586
+ * @example
1587
+ * ```ts
1588
+ * describeUnrolledView('contents-scrolled')
1589
+ * // 'Capture state "contents-scrolled" cannot be viewed in an unrolled portfolio: place it to shoot every row, or view it from a portfolio created without unrolled'
1590
+ * ```
1591
+ */
1592
+ function describeUnrolledView(state) {
1593
+ return `Capture state "${state}" cannot be viewed in an unrolled portfolio: place it to shoot every row, or view it from a portfolio created without unrolled`;
1594
+ }
1595
+ /**
1437
1596
  * Reads the optional disk-digest command the tester page registered.
1438
1597
  *
1439
1598
  * @returns The registered `readCapture` command, or undefined where none is registered.
@@ -1472,7 +1631,9 @@ async function verifyFrame(shot, path, reader) {
1472
1631
  if (segment === "..") segments.pop();
1473
1632
  else segments.push(segment);
1474
1633
  }
1475
- if (!shot.path.replaceAll("\\", "/").endsWith(segments.join("/"))) throw new Error(`Capture frame was written to ${shot.path} where ${path} was asked for`);
1634
+ const destination = shot.path.replaceAll("\\", "/");
1635
+ const requested = segments.join("/");
1636
+ if (destination !== requested && !destination.endsWith(`/${requested}`)) throw new Error(`Capture frame was written to ${shot.path} where ${path} was asked for`);
1476
1637
  const expected = reader === void 0 ? shot.base64 : [...new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(atob(shot.base64), (character) => character.charCodeAt(0))))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
1477
1638
  if ((reader === void 0 ? await commands.readFile(shot.path, "base64") : await reader(shot.path)) !== expected) throw new Error(`Capture frame at ${path} is not the one this run shot`);
1478
1639
  }
@@ -1608,12 +1769,16 @@ async function readShotPixel(element, x, y) {
1608
1769
  *
1609
1770
  * @param states - The registered state names.
1610
1771
  * @param variants - The variants the portfolio is rendered in.
1611
- * @returns One `<state>--<variant>.png` name per pair, each state's variants together, in registry
1612
- * order.
1772
+ * @param scope - The handler naming each state's scope directory. Omit it to name no directory.
1773
+ * @returns One `<state>--<variant>.png` name per pair, each under `<scope>/` where `scope` is given,
1774
+ * each state's variants together, in registry order.
1775
+ * @throws Thrown when `scope` names a scope that is empty, `.`, `..`, or carries a slash or a
1776
+ * backslash, because a scope is one path segment.
1613
1777
  *
1614
1778
  * @remarks
1615
1779
  * The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry
1616
- * defect a proof reads directly rather than a collision discovered on disk.
1780
+ * defect a proof reads directly rather than a collision discovered on disk. The handler is called
1781
+ * once per state.
1617
1782
  *
1618
1783
  * @example
1619
1784
  * ```ts
@@ -1621,10 +1786,13 @@ async function readShotPixel(element, x, y) {
1621
1786
  * // ['start--dark-390.png']
1622
1787
  * ```
1623
1788
  */
1624
- function expandCaptures(states, variants) {
1625
- const files = [];
1626
- for (const state of states) for (const variant of variants) files.push(`${state}--${variant.name}.png`);
1627
- return files;
1789
+ function expandCaptures(states, variants, scope) {
1790
+ return states.flatMap((state) => {
1791
+ const directory = scope?.(state);
1792
+ if (directory !== void 0 && (directory === "" || directory === "." || directory === ".." || /[/\\]/u.test(directory))) throw new Error(`Capture scope ${JSON.stringify(directory)} of state "${state}" is not one path segment`);
1793
+ const prefix = directory === void 0 ? "" : `${directory}/`;
1794
+ return variants.map((variant) => `${prefix}${state}--${variant.name}.png`);
1795
+ });
1628
1796
  }
1629
1797
  /**
1630
1798
  * Restages a capture until its content extent equals the pane height.
@@ -3639,8 +3807,8 @@ function readAnimations(element) {
3639
3807
  * each endless animation at its first frame.
3640
3808
  *
3641
3809
  * @param options - The time bounds of the wait, its abort signal, and whether the pointer parks.
3642
- * @returns A promise resolving, after one more frame has painted, to the resume: a function that
3643
- * sets every held animation running again.
3810
+ * @returns A promise resolving, after the listeners a finished animation's end event reaches have
3811
+ * run, to the resume: a function that sets every held animation running again.
3644
3812
  * @throws Thrown when the pointer cannot park, as {@link parkPointer} raises it, and when a finite
3645
3813
  * animation is still running at the budget, as {@link waitForAnimations} raises it. An aborted wait
3646
3814
  * rejects with the signal's reason.
@@ -3652,6 +3820,12 @@ function readAnimations(element) {
3652
3820
  * the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
3653
3821
  * capture that throws still owes it, so call it from a `finally` block.
3654
3822
  *
3823
+ * The settle waits one frame before it reads the animations, so a transition the page starts from
3824
+ * an animation-frame callback after the act is running when the wait reads it. The browser
3825
+ * dispatches an animation's end event, such as `transitionend`, after its `finished` promise
3826
+ * settles, so the settle yields one task after the wait: a page listener that finalizes its layout
3827
+ * on that event has run when the settle resolves.
3828
+ *
3655
3829
  * The subject is the whole document, its root element included. The pointer parks through
3656
3830
  * {@link parkPointer}, which sends no button release, so a held press stays held either way. Pass
3657
3831
  * `pointer: false` only where the pointer is part of the state, such as a drag in flight: the
@@ -3671,12 +3845,12 @@ async function settleCapture(options) {
3671
3845
  if (options?.pointer ?? true) await parkPointer();
3672
3846
  await waitForFrame();
3673
3847
  await waitForAnimations(document.documentElement, options);
3848
+ await waitForDelay(0);
3674
3849
  const held = readAnimations(document.documentElement).endless;
3675
3850
  for (const animation of held) {
3676
3851
  animation.pause();
3677
3852
  animation.currentTime = 0;
3678
3853
  }
3679
- await waitForFrame();
3680
3854
  return () => {
3681
3855
  for (const animation of held) animation.play();
3682
3856
  };
@@ -4345,26 +4519,125 @@ function createKeyboardEvent(name, options) {
4345
4519
  ...options
4346
4520
  });
4347
4521
  }
4522
+ // src/browser/captures/Portfolio.ts
4523
+ /** Owns the registry, the placements in flight, and the written paths behind a portfolio projection. */
4524
+ var Portfolio = class {
4525
+ #variant;
4526
+ #selected;
4527
+ #states;
4528
+ #projection;
4529
+ #directory;
4530
+ #scope;
4531
+ #enabled;
4532
+ #unrolled;
4533
+ #files;
4534
+ #observed = [];
4535
+ #paths = [];
4536
+ #pending = /* @__PURE__ */ new Set();
4537
+ constructor(options) {
4538
+ const selected = options.variants.find((candidate) => candidate.name === options.variant);
4539
+ if (selected === void 0) throw new Error(`Capture variant "${options.variant}" is not registered`);
4540
+ const states = [...options.states];
4541
+ if (options.state !== void 0 && !states.includes(options.state)) throw new Error(`Capture state "${options.state}" is not registered`);
4542
+ this.#variant = options.variant;
4543
+ this.#selected = selected;
4544
+ this.#states = states;
4545
+ this.#projection = options.state;
4546
+ this.#directory = options.directory;
4547
+ this.#scope = options.scope;
4548
+ this.#enabled = options.enabled ?? false;
4549
+ this.#unrolled = options.unrolled ?? false;
4550
+ this.#files = expandCaptures(states, options.variants, options.scope);
4551
+ }
4552
+ get variant() {
4553
+ return this.#variant;
4554
+ }
4555
+ get files() {
4556
+ return this.#files;
4557
+ }
4558
+ get observed() {
4559
+ return [...this.#observed];
4560
+ }
4561
+ get placements() {
4562
+ return this.#observed.filter((state) => this.#writes(state));
4563
+ }
4564
+ get paths() {
4565
+ return [...this.#paths];
4566
+ }
4567
+ async place(state, element) {
4568
+ this.#admit(state);
4569
+ return this.#write(state, (frame) => captureFrame({
4570
+ ...frame,
4571
+ element,
4572
+ unrolled: this.#unrolled
4573
+ }));
4574
+ }
4575
+ async view(state) {
4576
+ this.#admit(state);
4577
+ if (this.#unrolled) throw new Error(describeUnrolledView(state));
4578
+ return this.#write(state, captureViewport);
4579
+ }
4580
+ #admit(state) {
4581
+ if (!this.#states.includes(state)) throw new Error(`Capture state "${state}" is not registered`);
4582
+ if (this.#observed.includes(state) || this.#pending.has(state)) throw new Error(`Capture state "${state}" is already placed`);
4583
+ }
4584
+ #writes(state) {
4585
+ return this.#enabled && (this.#projection === void 0 || state === this.#projection);
4586
+ }
4587
+ async #write(state, shoot) {
4588
+ if (!this.#writes(state)) {
4589
+ this.#observed.push(state);
4590
+ return;
4591
+ }
4592
+ const file = requireValue(expandCaptures([state], [this.#selected], this.#scope)[0]);
4593
+ this.#pending.add(state);
4594
+ try {
4595
+ this.#selected.apply?.();
4596
+ const written = await shoot({
4597
+ path: `${this.#directory}/${file}`,
4598
+ width: this.#selected.width,
4599
+ height: this.#selected.height
4600
+ });
4601
+ this.#observed.push(state);
4602
+ this.#paths.push(written);
4603
+ return written;
4604
+ } finally {
4605
+ this.#pending.delete(state);
4606
+ }
4607
+ }
4608
+ };
4348
4609
  // src/browser/captures/factories.ts
4349
4610
  /**
4350
4611
  * Creates the capture portfolio one run places its screenshots through; a disabled run still refuses.
4351
4612
  *
4352
- * @param options - The state registry, the variant matrix, the variant this run renders, the
4353
- * directory it writes into, and whether it writes at all.
4354
- * @returns The portfolio: its registry expansion, what it has placed, and `place`.
4355
- * @throws When no registered variant carries the name `variant` names.
4613
+ * @param options - The state registry, the one state it projects, the variant matrix, the variant
4614
+ * this run renders, the directory and scopes it writes into, and whether it writes at all.
4615
+ * @returns The portfolio: its registry expansion, what it has accepted and placed, `place`, and
4616
+ * `view`.
4617
+ * @throws When no registered variant carries the name `variant` names, when the registry does not
4618
+ * carry the `state` option, and when `scope` names a scope that is not one path segment.
4356
4619
  *
4357
4620
  * @remarks
4358
- * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
4359
- * records no placement, so a journey calls it unconditionally and a suite with the flag unset pays
4360
- * for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled or not,
4361
- * refuses an unregistered state name and a second placement of one state, so a wrong name fails the
4362
- * ordinary run. A disabled run keeps the names it has seen apart from `placements`, which stays
4363
- * empty.
4621
+ * A disabled portfolio is the ordinary run. `place` and `view` then resize nothing, write nothing,
4622
+ * and record no placement, so a journey calls them unconditionally and a suite with the flag unset
4623
+ * pays for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled
4624
+ * or not, refuses an unregistered state name and a second placement of one state, so a wrong name
4625
+ * fails the ordinary run, and an unrolled portfolio refuses every `view` in every run, with the text
4626
+ * {@link describeUnrolledView} renders. A placement holds its state from before its first await
4627
+ * until it settles, so a concurrent placement of that state is refused as already placed, and a
4628
+ * placement that throws leaves its state unplaced. `observed` lists every state `place` and `view`
4629
+ * accepted, written or not, and `placements` lists the ones they wrote, so a disabled run's
4630
+ * `placements` stays empty.
4631
+ *
4632
+ * A `state` option projects the run onto one state: `place` and `view` write that state and accept
4633
+ * every other registered state unwritten. A `scope` handler writes each state under
4634
+ * `<directory>/<scope>/`, and `files` carries the same scope, as {@link expandCaptures} expands it.
4364
4635
  *
4365
- * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
4366
- * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
4367
- * this run's own frame. The portfolio's `unrolled` option reaches every frame `place` writes.
4636
+ * An enabled `place` writes through `captureFrame`, and an enabled `view` through
4637
+ * `captureViewport`, so a placed state carries that helper's staged pane and its byte readback: a
4638
+ * path is recorded only after the file on disk has been proved to hold this run's own frame. The
4639
+ * portfolio's `unrolled` option reaches every frame `place` writes. `view` shoots the declared
4640
+ * viewport at the scroll the journey reached.
4368
4641
  *
4369
4642
  * @example
4370
4643
  * ```ts
@@ -4378,43 +4651,21 @@ function createKeyboardEvent(name, options) {
4378
4651
  * ```
4379
4652
  */
4380
4653
  function createPortfolio(options) {
4381
- const selected = options.variants.find((candidate) => candidate.name === options.variant);
4382
- if (selected === void 0) throw new Error(`Capture variant "${options.variant}" is not registered`);
4383
- const registry = [...options.states];
4384
- const files = expandCaptures(registry, options.variants);
4385
- const enabled = options.enabled ?? false;
4386
- const placed = [];
4387
- const paths = [];
4388
- const seen = [];
4654
+ const portfolio = new Portfolio(options);
4389
4655
  return {
4390
- variant: options.variant,
4391
- files,
4656
+ variant: portfolio.variant,
4657
+ files: portfolio.files,
4658
+ get observed() {
4659
+ return portfolio.observed;
4660
+ },
4392
4661
  get placements() {
4393
- return [...placed];
4662
+ return portfolio.placements;
4394
4663
  },
4395
4664
  get paths() {
4396
- return [...paths];
4665
+ return portfolio.paths;
4397
4666
  },
4398
- async place(state, element) {
4399
- if (!registry.includes(state)) throw new Error(`Capture state "${state}" is not registered`);
4400
- if (placed.includes(state) || seen.includes(state)) throw new Error(`Capture state "${state}" is already placed`);
4401
- if (!enabled) {
4402
- seen.push(state);
4403
- return;
4404
- }
4405
- const file = `${state}--${options.variant}.png`;
4406
- selected.apply?.();
4407
- const written = await captureFrame({
4408
- path: `${options.directory}/${file}`,
4409
- width: selected.width,
4410
- height: selected.height,
4411
- element,
4412
- unrolled: options.unrolled
4413
- });
4414
- placed.push(state);
4415
- paths.push(written);
4416
- return written;
4417
- }
4667
+ place: portfolio.place.bind(portfolio),
4668
+ view: portfolio.view.bind(portfolio)
4418
4669
  };
4419
4670
  }
4420
4671
  // src/browser/colors/constants.ts
@@ -5649,6 +5900,6 @@ function buildCensus() {
5649
5900
  mark
5650
5901
  });
5651
5902
  }
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 };
5903
+ 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, captureViewport, 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, describeUnrolledView, 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, readClipBound, readClipEdge, readClipMargin, readClippedBlock, readColorContrast, readContrast, readControlValue, readFlatParent, 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, recordScroll, 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 };
5653
5904
 
5654
5905
  //# sourceMappingURL=index.js.map