@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.
package/README.md CHANGED
@@ -111,7 +111,7 @@ const sources = readInventory(root, ['src/core', 'src/server'], { extensions: ['
111
111
  Object.keys(sources)
112
112
  // ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
113
113
  // 'src/core/types.ts', 'src/core/validators.ts', 'src/server/Loopback.ts', 'src/server/constants.ts',
114
- // 'src/server/factories.ts', 'src/server/helpers.ts', 'src/server/index.ts',
114
+ // 'src/server/factories.ts', 'src/server/helpers.ts', 'src/server/index.ts', 'src/server/plugins.ts',
115
115
  // 'src/server/reporters/ProgressReporter.ts',
116
116
  // 'src/server/types.ts', 'src/server/validators.ts']
117
117
 
@@ -136,7 +136,7 @@ Object.keys(
136
136
  Object.keys(
137
137
  readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
138
138
  )
139
- // ['src/bin/reporter.ts', 'src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts',
139
+ // ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts',
140
140
  // 'src/core/helpers.ts', 'src/core/index.ts', 'src/core/types.ts', 'src/core/validators.ts']
141
141
  ```
142
142
 
@@ -217,17 +217,24 @@ rule deciding what ships and what stays in the package that owns it — see
217
217
  ## Package
218
218
 
219
219
  Published as typed entry points per the `exports` field in `package.json`: `@orkestrel/test` for the
220
- host-independent core, `@orkestrel/test/browser` for the journey layer, `@orkestrel/test/server`
221
- for the Node helpers, and `@orkestrel/test/reporter` for the progress reporter Vitest loads by
222
- specifier. Core and server ship ESM and CommonJS. The browser face ships ESM only, because
223
- `vitest/browser` is an ES-only module, and the reporter entry ships ESM only. The reporter entry
224
- lives at `src/bin/reporter.ts` and builds to `dist/bin/reporter.js`; the specifier does not name
225
- that path.
220
+ host-independent core, `@orkestrel/test/browser` for the journey layer, and
221
+ `@orkestrel/test/server` for the Node helpers. Core and server ship ESM and CommonJS. The browser
222
+ face ships ESM only, because `vitest/browser` is an ES-only module.
226
223
 
227
- Run a suite with the progress reporter by naming the entry and the file it appends to:
224
+ To run a suite with the progress reporter under command-line `--reporter` flags, mount the
225
+ progress plugin in the configuration:
226
+
227
+ ```ts
228
+ import { defineConfig } from 'vitest/config'
229
+ import { createProgressPlugin } from '@orkestrel/test/server'
230
+
231
+ export default defineConfig({ plugins: [createProgressPlugin()] })
232
+ ```
233
+
234
+ Then name the file the reporter appends to:
228
235
 
229
236
  ```sh
230
- npx vitest run --reporter=@orkestrel/test/reporter --outputFile.progress=tmp/runs/progress.jsonl
237
+ npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
231
238
  ```
232
239
 
233
240
  ## License
@@ -418,6 +418,9 @@ export declare const CAPTURE_STAGE_LIMIT = 4;
418
418
  * transformed ancestor is counted as a row, though the top layer lays it out. A region inside a
419
419
  * closed shadow root is unreachable, so its rows stay hidden without a refusal.
420
420
  *
421
+ * To shoot the declared viewport at the scroll the page holds rather than the document, call
422
+ * {@link captureViewport}.
423
+ *
421
424
  * @example
422
425
  * ```ts
423
426
  * await captureFrame({ path: '../../tmp/capture/start.png', width: 390, height: 844 })
@@ -445,6 +448,44 @@ export declare interface CaptureVariant extends JourneyVariant {
445
448
  readonly apply?: () => void;
446
449
  }
447
450
 
451
+ /**
452
+ * Shoots the declared viewport at the scroll the page holds and proves the file on disk holds this
453
+ * run's bytes.
454
+ *
455
+ * @param options - The path to write and the viewport to shoot at.
456
+ * @returns The absolute path of the written frame, after it has been read back and matched.
457
+ * @throws Thrown when the pane cannot be staged, when the cover cannot lay out over the viewport,
458
+ * when the provider wrote the frame somewhere else, and when the bytes on disk are not the ones this
459
+ * shot produced.
460
+ *
461
+ * @remarks
462
+ * The pane is staged at the declared viewport alone, no height is measured, and no taller pane is
463
+ * staged, so a mark the scroll drives keeps naming what the viewport shows. A tester that is not at
464
+ * the declared viewport is resized to it first, and the frame then holds the scroll the page keeps
465
+ * at that size. The shot is taken of a transparent fixed box, the cover, appended to the root
466
+ * element and removed on every path; the cover sends no pointer input and receives none. Its
467
+ * `position`, `inset`, `opacity`, and `pointer-events` declarations are set inline as important, so
468
+ * a page rule marked important does not paint it over the shot.
469
+ *
470
+ * The cover's box is read after it is appended, and a box that does not start at the viewport's
471
+ * origin at the viewport's size refuses the shot with
472
+ * `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`.
473
+ * The check reads the box, not its cause: a root element that becomes the cover's containing block,
474
+ * through a transform or a paint containment, lays the cover out over its own box, so the shot is
475
+ * refused wherever that box differs from the viewport, as a scrolled or a taller document's does,
476
+ * and taken where the two coincide.
477
+ *
478
+ * The pane is released and the scroll of the window and of every scroll container
479
+ * {@link collectScrollContainers} finds is restored before this returns, on every path, as
480
+ * {@link captureFrame} does. The file is verified as {@link verifyFrame} verifies it.
481
+ *
482
+ * @example
483
+ * ```ts
484
+ * await captureViewport({ path: '../../tmp/capture/contents.png', width: 390, height: 844 })
485
+ * ```
486
+ */
487
+ export declare function captureViewport(options: ViewportOptions): Promise<string>;
488
+
448
489
  /**
449
490
  * Holds detached markup an authored-class census must report as undeclared.
450
491
  *
@@ -1352,22 +1393,34 @@ export declare function createPointerEvent(name: string, options?: PointerEventI
1352
1393
  /**
1353
1394
  * Creates the capture portfolio one run places its screenshots through; a disabled run still refuses.
1354
1395
  *
1355
- * @param options - The state registry, the variant matrix, the variant this run renders, the
1356
- * directory it writes into, and whether it writes at all.
1357
- * @returns The portfolio: its registry expansion, what it has placed, and `place`.
1358
- * @throws When no registered variant carries the name `variant` names.
1396
+ * @param options - The state registry, the one state it projects, the variant matrix, the variant
1397
+ * this run renders, the directory and scopes it writes into, and whether it writes at all.
1398
+ * @returns The portfolio: its registry expansion, what it has accepted and placed, `place`, and
1399
+ * `view`.
1400
+ * @throws When no registered variant carries the name `variant` names, when the registry does not
1401
+ * carry the `state` option, and when `scope` names a scope that is not one path segment.
1359
1402
  *
1360
1403
  * @remarks
1361
- * A disabled portfolio is the ordinary run. `place` then resizes nothing, writes nothing, and
1362
- * records no placement, so a journey calls it unconditionally and a suite with the flag unset pays
1363
- * for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled or not,
1364
- * refuses an unregistered state name and a second placement of one state, so a wrong name fails the
1365
- * ordinary run. A disabled run keeps the names it has seen apart from `placements`, which stays
1366
- * empty.
1404
+ * A disabled portfolio is the ordinary run. `place` and `view` then resize nothing, write nothing,
1405
+ * and record no placement, so a journey calls them unconditionally and a suite with the flag unset
1406
+ * pays for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled
1407
+ * or not, refuses an unregistered state name and a second placement of one state, so a wrong name
1408
+ * fails the ordinary run, and an unrolled portfolio refuses every `view` in every run, with the text
1409
+ * {@link describeUnrolledView} renders. A placement holds its state from before its first await
1410
+ * until it settles, so a concurrent placement of that state is refused as already placed, and a
1411
+ * placement that throws leaves its state unplaced. `observed` lists every state `place` and `view`
1412
+ * accepted, written or not, and `placements` lists the ones they wrote, so a disabled run's
1413
+ * `placements` stays empty.
1367
1414
  *
1368
- * An enabled `place` writes through `captureFrame`, so a placed state carries that helper's staged
1369
- * pane and its byte readback: a path is recorded only after the file on disk has been proved to hold
1370
- * this run's own frame. The portfolio's `unrolled` option reaches every frame `place` writes.
1415
+ * A `state` option projects the run onto one state: `place` and `view` write that state and accept
1416
+ * every other registered state unwritten. A `scope` handler writes each state under
1417
+ * `<directory>/<scope>/`, and `files` carries the same scope, as {@link expandCaptures} expands it.
1418
+ *
1419
+ * An enabled `place` writes through `captureFrame`, and an enabled `view` through
1420
+ * `captureViewport`, so a placed state carries that helper's staged pane and its byte readback: a
1421
+ * path is recorded only after the file on disk has been proved to hold this run's own frame. The
1422
+ * portfolio's `unrolled` option reaches every frame `place` writes. `view` shoots the declared
1423
+ * viewport at the scroll the journey reached.
1371
1424
  *
1372
1425
  * @example
1373
1426
  * ```ts
@@ -1497,6 +1550,24 @@ export declare function describeScrollRegions(regions: readonly HTMLElement[]):
1497
1550
  */
1498
1551
  export declare function describeTree(element: Element): string;
1499
1552
 
1553
+ /**
1554
+ * Describes the refusal of a viewport placement in an unrolled portfolio.
1555
+ *
1556
+ * @param state - The state the placement named.
1557
+ * @returns The refusal, naming the state and the two placements that can shoot it.
1558
+ *
1559
+ * @remarks
1560
+ * An unrolled portfolio covers every row each scroll region hides, and a viewport frame covers the
1561
+ * rows the scroll shows, so a portfolio refuses the pairing in every run, written or not.
1562
+ *
1563
+ * @example
1564
+ * ```ts
1565
+ * describeUnrolledView('contents-scrolled')
1566
+ * // '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'
1567
+ * ```
1568
+ */
1569
+ export declare function describeUnrolledView(state: string): string;
1570
+
1500
1571
  /**
1501
1572
  * Holds the primary pointer button on the control a resolver returns, through the browser provider.
1502
1573
  *
@@ -1594,12 +1665,16 @@ export declare interface EscapeFixture {
1594
1665
  *
1595
1666
  * @param states - The registered state names.
1596
1667
  * @param variants - The variants the portfolio is rendered in.
1597
- * @returns One `<state>--<variant>.png` name per pair, each state's variants together, in registry
1598
- * order.
1668
+ * @param scope - The handler naming each state's scope directory. Omit it to name no directory.
1669
+ * @returns One `<state>--<variant>.png` name per pair, each under `<scope>/` where `scope` is given,
1670
+ * each state's variants together, in registry order.
1671
+ * @throws Thrown when `scope` names a scope that is empty, `.`, `..`, or carries a slash or a
1672
+ * backslash, because a scope is one path segment.
1599
1673
  *
1600
1674
  * @remarks
1601
1675
  * The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry
1602
- * defect a proof reads directly rather than a collision discovered on disk.
1676
+ * defect a proof reads directly rather than a collision discovered on disk. The handler is called
1677
+ * once per state.
1603
1678
  *
1604
1679
  * @example
1605
1680
  * ```ts
@@ -1607,7 +1682,7 @@ export declare interface EscapeFixture {
1607
1682
  * // ['start--dark-390.png']
1608
1683
  * ```
1609
1684
  */
1610
- export declare function expandCaptures(states: readonly string[], variants: readonly CaptureVariant[]): readonly string[];
1685
+ export declare function expandCaptures(states: readonly string[], variants: readonly CaptureVariant[], scope?: ScopeHandler): readonly string[];
1611
1686
 
1612
1687
  /**
1613
1688
  * Collects every element carrying a component class rendered outside the container it belongs to.
@@ -1769,13 +1844,7 @@ export declare interface FrameOffset {
1769
1844
  }
1770
1845
 
1771
1846
  /** Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. */
1772
- export declare interface FrameOptions {
1773
- /** Holds the frame's path, relative to the calling test file. */
1774
- readonly path: string;
1775
- /** Holds the viewport width in CSS pixels the frame is shot at. */
1776
- readonly width: number;
1777
- /** Holds the viewport height in CSS pixels the frame is shot at. */
1778
- readonly height: number;
1847
+ export declare interface FrameOptions extends ViewportOptions {
1779
1848
  /** Holds the element to shoot. Omit it to shoot the whole page. */
1780
1849
  readonly element?: Element | undefined;
1781
1850
  /**
@@ -2224,7 +2293,7 @@ export declare function matchesTraversalName(element: HTMLElement, name: string,
2224
2293
  *
2225
2294
  * Each element contributes its client rectangle's bottom edge in document coordinates plus its own
2226
2295
  * bottom margin, which sits outside that rectangle, and the largest contribution wins. An ancestor
2227
- * that clips its overflow, which the {@link collectClippingAncestors} helper finds through the flat
2296
+ * that clips its overflow, which the {@link readClipBound} helper finds through the flat
2228
2297
  * tree and so reaches a shadow wrapper around a slot, caps the contribution at that ancestor's clip
2229
2298
  * edge, which the {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
2230
2299
  * frame are cut, scrolled, or discarded rather than added to the document: a viewport-height
@@ -2292,9 +2361,11 @@ export declare function measureLuminance(color: RGBA): number;
2292
2361
  * The `scrollHeight` property never reads less than the `clientHeight` property, so a region whose
2293
2362
  * rows fit reads its box rather than its rows, and the slack under its last row cannot be read
2294
2363
  * there. This reading can, because it is taken over the elements inside the region rather than
2295
- * over its box: each element contributes its bottom edge plus its own bottom margin, capped at the
2296
- * clip edge, as the {@link readClipEdge} helper measures it, of every clipping ancestor between it
2297
- * and the region, and the largest contribution wins. The region's scroll offset is added back, so
2364
+ * over its box: each element contributes its bottom edge plus its own bottom margin, and the
2365
+ * largest contribution wins. Where the region itself clips its overflow, as the {@link clipsOverflow}
2366
+ * helper reports it, each contribution is capped at the clip edge, as the {@link readClipEdge}
2367
+ * helper measures it, of every clipping ancestor between the element and the region; where the
2368
+ * region clips nothing, no contribution is capped. The region's scroll offset is added back, so
2298
2369
  * a scrolled region reads the same rows as an unscrolled one. The elements are the ones
2299
2370
  * {@link collectRegionRows} reaches through the flat tree, so a host's shadow rows and a slot's
2300
2371
  * assigned rows count, and a fixed or absolute box laid out against a block outside the region
@@ -2497,7 +2568,9 @@ export declare const POINTER_HOLD = "data-pointer-hold";
2497
2568
  export declare interface PortfolioInterface {
2498
2569
  /** Holds the name of the variant this run renders. */
2499
2570
  readonly variant: string;
2500
- /** Lists every state placed so far, in placement order. */
2571
+ /** Lists every state `place` and `view` accepted so far, written or not, in placement order. */
2572
+ readonly observed: readonly string[];
2573
+ /** Lists every state written so far, in placement order. */
2501
2574
  readonly placements: readonly string[];
2502
2575
  /** Lists every path written so far, in write order. */
2503
2576
  readonly paths: readonly string[];
@@ -2509,11 +2582,25 @@ export declare interface PortfolioInterface {
2509
2582
  *
2510
2583
  * @param state - The state name from the registry.
2511
2584
  * @param element - The element to shoot. Omit it to shoot the whole page.
2512
- * @returns The written path, or `undefined` when the portfolio is not enabled.
2513
- * @throws When the state is not registered, has already been placed, or the written frame does
2514
- * not read back as the bytes this shot produced.
2585
+ * @returns The written path, or `undefined` when the portfolio is not enabled or the state is not
2586
+ * the one `state` projects.
2587
+ * @throws When the state is not registered, has already been placed or is being placed, or the
2588
+ * written frame does not read back as the bytes this shot produced.
2515
2589
  */
2516
2590
  place(state: string, element?: Element): Promise<string | undefined>;
2591
+ /**
2592
+ * Places one registered state as the declared viewport at the scroll the journey reached:
2593
+ * applies the variant, stages the pane at the variant's size alone, and writes the verified
2594
+ * screenshot.
2595
+ *
2596
+ * @param state - The state name from the registry.
2597
+ * @returns The written path, or `undefined` when the portfolio is not enabled or the state is not
2598
+ * the one `state` projects.
2599
+ * @throws When the state is not registered, has already been placed or is being placed, or the
2600
+ * portfolio is unrolled, in every run; and when the written frame does not read back as the bytes
2601
+ * this shot produced.
2602
+ */
2603
+ view(state: string): Promise<string | undefined>;
2517
2604
  }
2518
2605
 
2519
2606
  /**
@@ -2526,6 +2613,11 @@ export declare interface PortfolioOptions {
2526
2613
  * this list, so the registry and the disk cannot drift apart.
2527
2614
  */
2528
2615
  readonly states: readonly string[];
2616
+ /**
2617
+ * Holds the one state this run writes. Omit it to write every state. `place` accepts each other
2618
+ * registered state unwritten. Creation throws when the registry does not carry it.
2619
+ */
2620
+ readonly state?: string;
2529
2621
  /** Lists every variant the portfolio can be rendered in. One run renders exactly one of them. */
2530
2622
  readonly variants: readonly CaptureVariant[];
2531
2623
  /** Holds the name of the variant this run renders. Creation throws when no variant carries it. */
@@ -2533,13 +2625,20 @@ export declare interface PortfolioOptions {
2533
2625
  /** Holds the directory each written file is placed in, relative to the calling test file. */
2534
2626
  readonly directory: string;
2535
2627
  /**
2536
- * Determines whether this run writes files. An ordinary run leaves it unset, so `place` resizes
2537
- * nothing, writes nothing, and records nothing.
2628
+ * Names the scope directory each state is written under, inside `directory`. Omit it to write
2629
+ * every state into `directory` itself.
2630
+ */
2631
+ readonly scope?: ScopeHandler;
2632
+ /**
2633
+ * Determines whether this run writes files. An ordinary run leaves it unset, so `place` and
2634
+ * `view` resize nothing and write nothing, and `placements` and `paths` stay empty while
2635
+ * `observed` still lists every state they accept.
2538
2636
  */
2539
2637
  readonly enabled?: boolean;
2540
2638
  /**
2541
- * If `true`, every frame `place` writes also covers the rows every vertical scroll region hides;
2542
- * if `false` or omitted, each frame ends where the document's own content ends.
2639
+ * If `true`, every frame `place` writes also covers the rows every vertical scroll region hides,
2640
+ * and `view` refuses every state; if `false` or omitted, each frame ends where the document's own
2641
+ * content ends.
2543
2642
  */
2544
2643
  readonly unrolled?: boolean;
2545
2644
  }
@@ -2792,6 +2891,34 @@ export declare function readCensus(root: ParentNode): CensusResult;
2792
2891
  */
2793
2892
  export declare function readClasses(root: ParentNode): ReadonlySet<string>;
2794
2893
 
2894
+ /**
2895
+ * Reads the lowest clip edge the clipping ancestors between an element and a region put on it.
2896
+ *
2897
+ * @param element - The element to read.
2898
+ * @param region - The flat-tree ancestor the climb stops at, itself not counted.
2899
+ * @param bounds - The memo one measurement shares across its elements, keyed by ancestor. Default:
2900
+ * a fresh memo.
2901
+ * @returns The lowest edge, in document coordinates, that the {@link readClipEdge} helper measures
2902
+ * on a clipping ancestor strictly between the element and the region; `Infinity` where none of them
2903
+ * clips; and `undefined` where the region is no flat-tree ancestor of the element.
2904
+ * @throws Thrown when the element is not connected to a document, as the
2905
+ * {@link collectClippingAncestors} helper throws.
2906
+ *
2907
+ * @remarks
2908
+ * The climb takes the steps the {@link readFlatParent} helper reads, as the
2909
+ * {@link collectClippingAncestors} helper does. Each ancestor's entry in `bounds` holds the bound it
2910
+ * hands down: its own clip edge and every bound above it, up to the region. A measurement that
2911
+ * reads every element of a subtree through one memo therefore reads each ancestor's style once,
2912
+ * rather than once for every element under it.
2913
+ *
2914
+ * @example
2915
+ * ```ts
2916
+ * const bounds = new Map<Element, number | undefined>()
2917
+ * readClipBound(row, document.body, bounds) // the edge of the nearest hidden frame around the row
2918
+ * ```
2919
+ */
2920
+ export declare function readClipBound(element: Element, region: Element, bounds?: Map<Element, number | undefined>): number | undefined;
2921
+
2795
2922
  /**
2796
2923
  * Measures the row a clipping element cuts its content off at, in document coordinates.
2797
2924
  *
@@ -2977,6 +3104,24 @@ export declare function readContrast(element: Element, floor?: RGBA): number;
2977
3104
  */
2978
3105
  export declare function readControlValue(role: string, name: string): string;
2979
3106
 
3107
+ /**
3108
+ * Reads an element's parent in the flat tree, the tree a browser paints.
3109
+ *
3110
+ * @param element - The element to step up from.
3111
+ * @returns The slot the element is assigned to, else its parent element, else the host of the
3112
+ * shadow root it stands in, and `undefined` for an element with none of the three.
3113
+ *
3114
+ * @remarks
3115
+ * The `assignedSlot` property reports no slot of a closed shadow root, so a child assigned into one
3116
+ * steps to its light parent instead.
3117
+ *
3118
+ * @example
3119
+ * ```ts
3120
+ * readFlatParent(slotted) // the slot it is assigned to, inside its parent's open shadow root
3121
+ * ```
3122
+ */
3123
+ export declare function readFlatParent(element: Element): Element | undefined;
3124
+
2980
3125
  /**
2981
3126
  * Reads the rendered text of the element that holds focus.
2982
3127
  *
@@ -3628,6 +3773,27 @@ export declare function readToken(element: Element, name: string): string;
3628
3773
  */
3629
3774
  export declare function recordConsole(name: string, output: string[], forward: (...data: unknown[]) => void): (...data: unknown[]) => void;
3630
3775
 
3776
+ /**
3777
+ * Records the scroll position of the tester's window and of every scroll container in its body, and
3778
+ * returns the callback that scrolls each of them back.
3779
+ *
3780
+ * @returns A callback that scrolls the window and each recorded container back to the position this
3781
+ * call read, instantly.
3782
+ *
3783
+ * @remarks
3784
+ * The containers are the ones {@link collectScrollContainers} finds when this is called. A capture
3785
+ * records them before its first staging, because growing a region clamps its scroll position and an
3786
+ * element frame's alignment scrolls a container too, and restores them after the pane is released.
3787
+ *
3788
+ * @example
3789
+ * ```ts
3790
+ * const restore = recordScroll()
3791
+ * window.scrollTo({ top: 600, behavior: 'instant' })
3792
+ * restore() // the window is back at the scroll it held
3793
+ * ```
3794
+ */
3795
+ export declare function recordScroll(): () => void;
3796
+
3631
3797
  /**
3632
3798
  * Restores the media readings observed before the first stage as explicit emulation. With nothing
3633
3799
  * staged, clears every override and waits for a stable reading, not a proved engine baseline. Checks
@@ -3954,6 +4120,15 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
3954
4120
  */
3955
4121
  export declare type RGBA = readonly [red: number, green: number, blue: number, alpha: number];
3956
4122
 
4123
+ /**
4124
+ * Names the scope directory one capture state is written under, one path segment.
4125
+ *
4126
+ * @remarks
4127
+ * A portfolio calls it with each registered state, so it must return the same scope for a state on
4128
+ * every call.
4129
+ */
4130
+ export declare type ScopeHandler = (state: string) => string;
4131
+
3957
4132
  /** Names the native input types whose editable segments share one focused element. */
3958
4133
  export declare const SEGMENTED_INPUT_TYPES: readonly string[];
3959
4134
 
@@ -4024,8 +4199,8 @@ export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd'
4024
4199
  * each endless animation at its first frame.
4025
4200
  *
4026
4201
  * @param options - The time bounds of the wait, its abort signal, and whether the pointer parks.
4027
- * @returns A promise resolving, after one more frame has painted, to the resume: a function that
4028
- * sets every held animation running again.
4202
+ * @returns A promise resolving, after the listeners a finished animation's end event reaches have
4203
+ * run, to the resume: a function that sets every held animation running again.
4029
4204
  * @throws Thrown when the pointer cannot park, as {@link parkPointer} raises it, and when a finite
4030
4205
  * animation is still running at the budget, as {@link waitForAnimations} raises it. An aborted wait
4031
4206
  * rejects with the signal's reason.
@@ -4037,6 +4212,12 @@ export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd'
4037
4212
  * the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
4038
4213
  * capture that throws still owes it, so call it from a `finally` block.
4039
4214
  *
4215
+ * The settle waits one frame before it reads the animations, so a transition the page starts from
4216
+ * an animation-frame callback after the act is running when the wait reads it. The browser
4217
+ * dispatches an animation's end event, such as `transitionend`, after its `finished` promise
4218
+ * settles, so the settle yields one task after the wait: a page listener that finalizes its layout
4219
+ * on that event has run when the settle resolves.
4220
+ *
4040
4221
  * The subject is the whole document, its root element included. The pointer parks through
4041
4222
  * {@link parkPointer}, which sends no button release, so a held press stays held either way. Pass
4042
4223
  * `pointer: false` only where the pointer is part of the state, such as a drag in flight: the
@@ -4164,17 +4345,15 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
4164
4345
  *
4165
4346
  * @remarks
4166
4347
  * This depends on the runner's own tester layout, and that dependency is contract rather than an
4167
- * accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
4168
- * the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
4348
+ * accident: `vitest@5.1.0` lays its tester out inside a smaller page, fits it with a CSS scale, and
4349
+ * clips whatever overflows the pane the tester sits in. Layout inside the tester is
4169
4350
  * unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
4170
4351
  * but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
4171
4352
  * a thumbnail of the surface and a frame shot after only unscaling it is a sliver. The tester is
4172
4353
  * therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
4173
- * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
4174
- * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
4175
- * them reddens the size check that follows rather than writing a wrong frame.
4176
- * The custom-property overrides serve Vitest 4; `transform: none !important` on the pane and
4177
- * iframe also suppresses Vitest 5's direct CSS transform.
4354
+ * selector and the `--viewport-width` and `--viewport-height` custom properties are the runner's, so
4355
+ * a Vitest release that renames any of them reddens the size check that follows rather than writing
4356
+ * a wrong frame. `transform: none !important` on the pane and iframe suppresses the fitting scale.
4178
4357
  *
4179
4358
  * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
4180
4359
  * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
@@ -4185,9 +4364,10 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
4185
4364
  * there. Staging and releasing as a pair resizes and then undoes the resize, so the journey step
4186
4365
  * after it runs at the size the file started at.
4187
4366
  *
4188
- * The rule is declared rather than written inline, because the runner writes its own scale onto the
4189
- * pane as inline custom properties and rewrites them whenever the tester resizes. A declared rule
4190
- * marked important outranks an inline value and survives every rewrite. It finds the pane by the
4367
+ * The rule is declared rather than written inline, because the runner writes its scale as an inline
4368
+ * `transform` on the tester's iframe and the viewport as inline custom properties on the body, and
4369
+ * rewrites them whenever the tester resizes. A declared rule marked important outranks an inline
4370
+ * value and survives every rewrite. It finds the pane by the
4191
4371
  * tester it contains as well as by {@link CAPTURE_PANE}, because a re-render between the staging and
4192
4372
  * the shot replaces the node and takes any attribute of ours with it.
4193
4373
  *
@@ -4420,6 +4600,16 @@ export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElemen
4420
4600
  */
4421
4601
  export declare function verifyFrame(shot: FrameShot, path: string, reader?: CaptureReader): Promise<void>;
4422
4602
 
4603
+ /** Configures one viewport shot: where it is written and the viewport it is shot at. */
4604
+ export declare interface ViewportOptions {
4605
+ /** Holds the frame's path, relative to the calling test file. */
4606
+ readonly path: string;
4607
+ /** Holds the viewport width in CSS pixels the frame is shot at. */
4608
+ readonly width: number;
4609
+ /** Holds the viewport height in CSS pixels the frame is shot at. */
4610
+ readonly height: number;
4611
+ }
4612
+
4423
4613
  /**
4424
4614
  * Waits until every finite animation on one element and its subtree has stopped moving.
4425
4615
  *