@orkestrel/scaffold 0.0.137 → 0.0.139

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.
Files changed (33) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +489 -23
  2. package/dist/bin/main.js +6 -6
  3. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +33 -27
  4. package/dist/host/agents/skills/orkestrel-journey/references/captures.md +37 -16
  5. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +628 -41
  7. package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +5 -0
  8. package/dist/host/claude/agents/orkestrel.md +54 -54
  9. package/dist/host/claude/rules/typescript.md +4 -1
  10. package/dist/host/claude/rules/workspace.md +6 -4
  11. package/dist/host/guides/capture.md +442 -313
  12. package/dist/host/guides/contract.md +314 -210
  13. package/dist/host/guides/middleware.md +489 -259
  14. package/dist/host/guides/process.md +139 -53
  15. package/dist/host/guides/router.md +282 -165
  16. package/dist/host/guides/scaffold.md +35 -23
  17. package/dist/host/guides/server.md +417 -181
  18. package/dist/host/guides/test.md +353 -232
  19. package/dist/host/manifest.json +18 -18
  20. package/dist/host/scripts/browsers.sh +0 -0
  21. package/dist/host/scripts/codex.sh +0 -0
  22. package/dist/host/scripts/cursor.sh +0 -0
  23. package/dist/host/scripts/deps.sh +0 -0
  24. package/dist/host/scripts/npm.sh +0 -0
  25. package/dist/host/scripts/ollama.sh +0 -0
  26. package/dist/host/tests/config.test.ts +19 -27
  27. package/dist/src/core/index.cjs +139 -60
  28. package/dist/src/core/index.cjs.map +1 -1
  29. package/dist/src/core/index.d.cts +1 -1
  30. package/dist/src/core/index.d.ts +1 -1
  31. package/dist/src/core/index.js +139 -60
  32. package/dist/src/core/index.js.map +1 -1
  33. package/package.json +6 -6
@@ -65,15 +65,14 @@ npm install --save-dev @orkestrel/test
65
65
 
66
66
  `@orkestrel/test` is the host-independent core. `@orkestrel/test/server` is the Node face — the
67
67
  filesystem helpers, the process and socket readings, the cookie jar, the Vitest progress reporter
68
- and its reader, and the pure leaves they are built from. `@orkestrel/test/browser` is the
69
- journey layer, which drives a real browser through the installed Vitest provider. Core touches
70
- neither `node:*` nor the DOM, so a browser test project imports it unchanged.
71
- `@orkestrel/test/reporter` is the runner entry Vitest's `--reporter` flag loads: its default
72
- export is `ProgressReporter`, and it ships ES only. The entry lives at `src/bin/reporter.ts` and
73
- builds to `dist/bin/reporter.js`; the specifier does not name that path. Use it for a run started
74
- from the command line with a configuration you cannot edit, as `@orkestrel/capture` starts a
75
- package's Vitest. In a package's own configuration, list `new ProgressReporter()` instead, as
76
- § Read a long run while it runs shows.
68
+ with its plugin and its reader, and the pure leaves they are built from. `@orkestrel/test/browser`
69
+ is the journey layer, which drives a real browser through the installed Vitest provider. Core
70
+ touches neither `node:*` nor the DOM, so a browser test project imports it unchanged.
71
+ `createProgressPlugin` carries the progress reporter into a run whose command line passes
72
+ `--reporter` flags, which replace every reporter a configuration lists. Mount it in the root
73
+ `plugins` of the configuration, as the wrapper `@orkestrel/capture` runs its stages under does, and
74
+ name the file with `--outputFile.progress`. In a configuration no command line overrides, list
75
+ `new ProgressReporter()` instead, as § Read a long run while it runs shows.
77
76
 
78
77
  The browser face ships ES only. It is built on `vitest/browser`, which is an ES-only module, so no
79
78
  CommonJS consumer can reach it and no `.d.cts` is emitted for it.
@@ -302,37 +301,39 @@ they name no target either, and neither does `stepFocus`, which takes a limit an
302
301
 
303
302
  #### Types
304
303
 
305
- | Name | Kind | Signature | Summary |
306
- | --------------------- | --------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
307
- | `CaptureReader` | type | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file through a browser command. |
308
- | `FrameShot` | interface | `{ path, base64 }` | Represents the path and base64 bytes returned by Vitest's screenshot operation. |
309
- | `RGBA` | type | `readonly [red: number, green: number, blue: number, alpha: number]` | Represents one rendered color as straight sRGB channels and its alpha. |
310
- | `ContrastOptions` | interface | `{ floor?, opacity? }` | Configures one color contrast reading: the surface the backdrop walk ends on, and the opacity the painted color is shown at. |
311
- | `ElementOptions` | interface | `{ classes?, text?, attributes? }` | Configures one built element: its class list, its text, and its attributes. |
312
- | `FrameOptions` | interface | `{ path, width, height, element?, unrolled? }` | Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. |
313
- | `FrameOffset` | interface | `{ top, left }` | Represents how far an element frame moves the tester frame from the runner window's origin for the shot, in CSS pixels. |
314
- | `FrameResult` | interface | `{ width, height, floor }` | Represents one written frame read back from the file a capture produced: its size in device pixels, and the single color its bottom row paints. |
315
- | `CaptureVariant` | interface | `{ apply? }` | Adds to a journey variant the document change a capture run applies before resizing. |
316
- | `PortfolioOptions` | interface | `{ states, variants, variant, directory, enabled?, unrolled? }` | Configures a capture portfolio: the state registry, the variant matrix, this run's variant, where it writes, and whether it writes at all. |
317
- | `PortfolioInterface` | interface | `{ variant, placements, paths, files, place() }` | Holds the registry of capture states one run places, and the files it wrote placing them. |
318
- | `JournalStep` | interface | `{ action, trigger, result }` | Represents one scripted step a journal recorded, and what the surface did about it. |
319
- | `JournalInterface` | interface | `{ steps, output, start(), stop(), record() }` | Records one scenario: every step it took and everything the page said while it ran. |
320
- | `StateOptions` | interface | `{ absent? }` | Configures a bounded wait over the states a control announces. |
321
- | `SettleOptions` | interface | `{ pointer? }` | Configures one capture settle: the time bounds of `WaitOptions` and whether the pointer parks first. |
322
- | `AnimationResult` | interface | `{ finite, endless }` | Represents the animations running on one element and its subtree, split by whether each one ends. |
323
- | `MediaOptions` | interface | `{ print?, motion?, forced?, pointer? }` | Configures the tester's print medium, motion preference, forced colours, and pointer precision. |
324
- | `StabilityOptions` | interface | `{ frames? }` | Configures how long a reading must hold still: the time bounds of `WaitOptions` and the count of reads it must agree across. |
325
- | `AccessibilityNode` | interface | `{ role, name, properties }` | Represents the accessibility node the browser computed for one element. |
326
- | `SheetAdoption` | interface | `{ sheet, release() }` | Describes an adopted stylesheet and its idempotent release operation. |
327
- | `ProtocolPoint` | interface | `{ x, y }` | Represents one point in the coordinates of the browser's top-level viewport, the space a DevTools input command addresses. |
328
- | `StorageOptions` | interface | `{ values?, reads?, writes?, quota? }` | Configures an inert `Storage`: its seed, which operations the host permits, and its quota. |
329
- | `WebStorageInterface` | interface | `{ permit(), clear(), getItem(), key(), removeItem(), setItem() }` | Holds a store the host can withhold and later grant. |
330
- | `CensusResult` | interface | `{ elements, tokens, undeclared }` | Reports an authored-class census: the population walked, the tokens found, and the undeclared. |
331
- | `ContrastFixture` | interface | `{ root, refused, accepted }` | Holds a detached translucent stack whose flat and composited readings disagree across one bar. |
332
- | `EscapeFixture` | interface | `{ root, inline, embedded, permitted }` | Holds detached markup a style-escape reading must find, and the one it must leave alone. |
333
- | `CensusFixture` | interface | `{ root, token, mark }` | Holds detached markup an authored-class census must report as undeclared. |
334
- | `HarnessOptions` | interface | `{ scenarios, build, state, pause? }` | Configures the harness that renders one transition table and drives it row by row. |
335
- | `HarnessInterface` | interface | `{ root, status, total, passed, failed, failures, execute(), destroy() }` | Holds a mounted statechart harness, the tally it publishes, and the run it drives. |
304
+ | Name | Kind | Signature | Summary |
305
+ | --------------------- | --------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
306
+ | `CaptureReader` | type | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file through a browser command. |
307
+ | `FrameShot` | interface | `{ path, base64 }` | Represents the path and base64 bytes returned by Vitest's screenshot operation. |
308
+ | `RGBA` | type | `readonly [red: number, green: number, blue: number, alpha: number]` | Represents one rendered color as straight sRGB channels and its alpha. |
309
+ | `ContrastOptions` | interface | `{ floor?, opacity? }` | Configures one color contrast reading: the surface the backdrop walk ends on, and the opacity the painted color is shown at. |
310
+ | `ElementOptions` | interface | `{ classes?, text?, attributes? }` | Configures one built element: its class list, its text, and its attributes. |
311
+ | `ViewportOptions` | interface | `{ path, width, height }` | Configures one viewport shot: where it is written and the viewport it is shot at. |
312
+ | `FrameOptions` | interface | `{ element?, unrolled? }` | Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. |
313
+ | `FrameOffset` | interface | `{ top, left }` | Represents how far an element frame moves the tester frame from the runner window's origin for the shot, in CSS pixels. |
314
+ | `FrameResult` | interface | `{ width, height, floor }` | Represents one written frame read back from the file a capture produced: its size in device pixels, and the single color its bottom row paints. |
315
+ | `CaptureVariant` | interface | `{ apply? }` | Adds to a journey variant the document change a capture run applies before resizing. |
316
+ | `ScopeHandler` | type | `(state: string) => string` | Names the scope directory one capture state is written under, one path segment. |
317
+ | `PortfolioOptions` | interface | `{ states, state?, variants, variant, directory, scope?, enabled?, unrolled? }` | Configures a capture portfolio: the state registry, the variant matrix, this run's variant, where it writes, and whether it writes at all. |
318
+ | `PortfolioInterface` | interface | `{ variant, observed, placements, paths, files, place(), view() }` | Holds the registry of capture states one run places, and the files it wrote placing them. |
319
+ | `JournalStep` | interface | `{ action, trigger, result }` | Represents one scripted step a journal recorded, and what the surface did about it. |
320
+ | `JournalInterface` | interface | `{ steps, output, start(), stop(), record() }` | Records one scenario: every step it took and everything the page said while it ran. |
321
+ | `StateOptions` | interface | `{ absent? }` | Configures a bounded wait over the states a control announces. |
322
+ | `SettleOptions` | interface | `{ pointer? }` | Configures one capture settle: the time bounds of `WaitOptions` and whether the pointer parks first. |
323
+ | `AnimationResult` | interface | `{ finite, endless }` | Represents the animations running on one element and its subtree, split by whether each one ends. |
324
+ | `MediaOptions` | interface | `{ print?, motion?, forced?, pointer? }` | Configures the tester's print medium, motion preference, forced colours, and pointer precision. |
325
+ | `StabilityOptions` | interface | `{ frames? }` | Configures how long a reading must hold still: the time bounds of `WaitOptions` and the count of reads it must agree across. |
326
+ | `AccessibilityNode` | interface | `{ role, name, properties }` | Represents the accessibility node the browser computed for one element. |
327
+ | `SheetAdoption` | interface | `{ sheet, release() }` | Describes an adopted stylesheet and its idempotent release operation. |
328
+ | `ProtocolPoint` | interface | `{ x, y }` | Represents one point in the coordinates of the browser's top-level viewport, the space a DevTools input command addresses. |
329
+ | `StorageOptions` | interface | `{ values?, reads?, writes?, quota? }` | Configures an inert `Storage`: its seed, which operations the host permits, and its quota. |
330
+ | `WebStorageInterface` | interface | `{ permit(), clear(), getItem(), key(), removeItem(), setItem() }` | Holds a store the host can withhold and later grant. |
331
+ | `CensusResult` | interface | `{ elements, tokens, undeclared }` | Reports an authored-class census: the population walked, the tokens found, and the undeclared. |
332
+ | `ContrastFixture` | interface | `{ root, refused, accepted }` | Holds a detached translucent stack whose flat and composited readings disagree across one bar. |
333
+ | `EscapeFixture` | interface | `{ root, inline, embedded, permitted }` | Holds detached markup a style-escape reading must find, and the one it must leave alone. |
334
+ | `CensusFixture` | interface | `{ root, token, mark }` | Holds detached markup an authored-class census must report as undeclared. |
335
+ | `HarnessOptions` | interface | `{ scenarios, build, state, pause? }` | Configures the harness that renders one transition table and drives it row by row. |
336
+ | `HarnessInterface` | interface | `{ root, status, total, passed, failed, failures, execute(), destroy() }` | Holds a mounted statechart harness, the tally it publishes, and the run it drives. |
336
337
 
337
338
  #### Constants
338
339
 
@@ -445,6 +446,8 @@ they name no target either, and neither does `stepFocus`, which takes a limit an
445
446
  | `readClipMargin` | function | `(element: Element) => number` | Measures how far past its own box a clipping element lets its content show. |
446
447
  | `readClippedBlock` | function | `(element: Element) => number` | Measures the block size an element shows after every clipping ancestor cuts it. |
447
448
  | `collectClippingAncestors` | function | `(element: Element) => readonly Element[]` | Collects the ancestors of an element that clip their descendants' overflow. |
449
+ | `readFlatParent` | function | `(element: Element) => Element \| undefined` | Reads an element's parent in the flat tree, the tree a browser paints. |
450
+ | `readClipBound` | function | `(element: Element, region: Element, bounds?: Map<Element, number \| undefined>) => number \| undefined` | Reads the lowest clip edge the clipping ancestors between an element and a region put on it. |
448
451
  | `collectScrollContainers` | function | `(element?: Element) => readonly Element[]` | Collects the scroll containers in an element's subtree, the element included unless it is the body or the root element. |
449
452
  | `collectUnrolledRegions` | function | `(element?: Element) => readonly Element[]` | Collects the vertical scroll regions an unrolled frame releases in an element's subtree, the element included unless it is the body or the root element. |
450
453
  | `clipsOverflow` | function | `(element: Element) => boolean` | Reports whether an element clips its descendants' overflow. |
@@ -466,6 +469,9 @@ they name no target either, and neither does `stepFocus`, which takes a limit an
466
469
  | `readFrameHeight` | function | `(options: FrameOptions, element: Element \| undefined, pane: number) => number \| undefined` | Reads a capture subject's height after applying its native scroll clearance. |
467
470
  | `takeFrameShot` | function | `(options: FrameOptions, element: Element \| undefined) => Promise<FrameShot>` | Takes a screenshot while temporarily positioning the runner frame around its subject. |
468
471
  | `captureFrame` | function | `(options: FrameOptions) => Promise<string>` | Shoots one frame at one viewport size and proves the file on disk holds this run's bytes. |
472
+ | `captureViewport` | function | `(options: ViewportOptions) => Promise<string>` | Shoots the declared viewport at the scroll the page holds and proves the file on disk holds this run's bytes. |
473
+ | `recordScroll` | function | `() => () => void` | Records the scroll position of the tester's window and of every scroll container in its body, and returns the callback that scrolls each of them back. |
474
+ | `describeUnrolledView` | function | `(state: string) => string` | Describes the refusal of a viewport placement in an unrolled portfolio. |
469
475
  | `readCaptureReader` | function | `() => CaptureReader \| undefined` | Reads the optional disk-digest command the tester page registered. |
470
476
  | `verifyFrame` | function | `(shot: FrameShot, path: string, reader?: CaptureReader) => Promise<void>` | Verifies a screenshot's destination and compares its returned bytes with the written file. |
471
477
  | `paintImage` | function | `(encoded: string) => Promise<OffscreenCanvasRenderingContext2D \| undefined>` | Decodes a base64 PNG and paints it, unscaled, onto a fresh offscreen 2D canvas. |
@@ -491,7 +497,7 @@ they name no target either, and neither does `stepFocus`, which takes a limit an
491
497
  | `readToken` | function | `(element: Element, name: string) => string` | Reads one custom property from an element's resolved style. |
492
498
  | `readRootToken` | function | `(name: string) => string` | Reads one custom property from the document element. |
493
499
  | `readPixels` | function | `(element: Element, property: string, pseudo?: string) => number` | Reads one resolved CSS length as a number of pixels. |
494
- | `expandCaptures` | function | `(states: readonly string[], variants: readonly CaptureVariant[]) => readonly string[]` | Expands a capture registry across every variant into the filenames a complete portfolio holds. |
500
+ | `expandCaptures` | function | `(states: readonly string[], variants: readonly CaptureVariant[], scope?: ScopeHandler) => readonly string[]` | Expands a capture registry across every variant into the filenames a complete portfolio holds. |
495
501
  | `buildDenial` | function | `(operation: string, key?: string) => DOMException` | Builds the refusal a host withholding a storage operation raises. |
496
502
  | `buildContrast` | function | `(bar: number) => ContrastFixture` | Builds a detached translucent stack whose composited and flat contrast readings straddle one bar. |
497
503
  | `buildEscapes` | function | `(permitted: string) => EscapeFixture` | Builds detached markup carrying one style escape of each kind, plus the sheet a project allows. |
@@ -776,12 +782,11 @@ where that distinction matters.
776
782
 
777
783
  `stagePane` unscales the runner's tester and lifts it to the window's origin, because a frame shot
778
784
  through the runner's fitting scale is a thumbnail of the surface. That couples it to Vitest's own
779
- tester layout, which is contract rather than accident: `vitest@4.1.12` is the version behind the
780
- `iframe[data-vitest]` selector and the `--tester-transform`, `--tester-margin-left`,
781
- `--viewport-width`, and `--viewport-height` custom properties it writes. A release that renames any
782
- of them reddens the size check rather than writing a wrong frame. The custom-property overrides
783
- serve Vitest 4; the pane and iframe also carry `transform: none !important` for Vitest 5's direct
784
- transform. An already matching viewport skips the resize command while retaining the staging
785
+ tester layout, which is contract rather than accident: `vitest@5.1.0` is the version behind the
786
+ `iframe[data-vitest]` selector and the `--viewport-width` and `--viewport-height` custom
787
+ properties it writes. A release that renames any of them reddens the size check rather than
788
+ writing a wrong frame. The pane and iframe carry `transform: none !important`, which suppresses the
789
+ fitting scale. An already matching viewport skips the resize command while retaining the staging
785
790
  rule, paint waits, and rendered-size check. Always hand the pane back with
786
791
  `releasePane`: a tester left pinned at a viewport taller than the window puts its lower half beyond
787
792
  what a pointer can reach, so the next ordinary press fails as a control that is covered. The release
@@ -835,9 +840,11 @@ the body instead, taking the largest bottom edge in document coordinates plus th
835
840
  bottom margin, and adds the body's and the root's bottom padding and margin under them. An
836
841
  ancestor that clips its overflow (the `clipsOverflow` helper: an `overflow-y` value other than the
837
842
  `visible` keyword, or a paint containment) caps a descendant's edge at that ancestor's clip edge,
838
- which the `readClipEdge` helper reads. The `collectClippingAncestors` helper finds those ancestors
839
- through the flat tree, from an element to the slot it is assigned to, to its parent, and out of a
840
- shadow root to its host, so a wrapper in a shadow tree around a slot clips what is slotted into it. An `overflow-y` value of the `hidden` keyword, the `auto`
843
+ which the `readClipEdge` helper reads. The `readClipBound` helper finds those ancestors through
844
+ the flat tree, one `readFlatParent` step at a time, from an element to the slot it is assigned to,
845
+ to its parent, and out of a shadow root to its host, so a wrapper in a shadow tree around a slot
846
+ clips what is slotted into it. One reading shares a memo of each ancestor's bound across every
847
+ element under it, so it reads each ancestor's style once rather than once per descendant. An `overflow-y` value of the `hidden` keyword, the `auto`
841
848
  keyword, or the `scroll` keyword clips at the padding box, whatever the ancestor's
842
849
  `overflow-clip-margin` value selects. The `clip` keyword and a paint containment over a `visible`
843
850
  overflow clip at the box that value selects, the padding box by default, expanded by the length the
@@ -919,6 +926,24 @@ naming the regions. A `:modal` dialog or a `:popover-open` element under a trans
919
926
  counted as a row, though the top layer lays it out. A region inside a closed shadow root is
920
927
  unreachable, so its rows stay hidden without a refusal.
921
928
 
929
+ To shoot what a person sees at the scroll a journey reached, call `captureViewport` with a
930
+ `ViewportOptions` value: the path, the width, and the height, and nothing else. It stages the pane
931
+ at the declared viewport alone, measures no height, and stages no taller pane, so a mark the scroll
932
+ drives, such as a contents entry naming the section in view, still names what the viewport shows.
933
+ It shoots a transparent fixed box, the cover, appended to the root element, and removes the cover
934
+ on every path. The cover's `position`, `inset`, `opacity`, and `pointer-events` declarations are
935
+ inline and important, so a page rule marked important does not paint the cover over the shot. A
936
+ tester that is not at the declared viewport is resized to it first, and the frame then holds the
937
+ scroll the page keeps at that size. The cover's box is read after it is appended, and a box that
938
+ does not start at the viewport's origin at the viewport's size refuses the shot with
939
+ `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`.
940
+ The check reads the box, not its cause: a root element that becomes the cover's containing block,
941
+ through a transform or a paint containment, lays the cover out over its own box, so the shot is
942
+ refused wherever that box differs from the viewport, as a scrolled or a taller document's does, and
943
+ taken where the two coincide. `captureViewport` hands back the pane and the scroll as
944
+ `captureFrame` does; `recordScroll` records the scroll of the window and of every scroll container
945
+ before either stages and returns the callback that restores it.
946
+
922
947
  A region that still hides rows after the settling refuses the capture with
923
948
  `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`.
924
949
  The refusal names every such region, and the cause and the correction come from what was
@@ -993,15 +1018,28 @@ pixels; a file with no PNG header is refused without a size.
993
1018
 
994
1019
  `createPortfolio` refuses an unregistered variant name at creation, so a run cannot write a filename
995
1020
  naming a combination it did not render. A portfolio left un-`enabled` is the ordinary run: `place`
996
- resizes nothing, writes nothing, and records nothing, so a journey calls it unconditionally. It
997
- still refuses an unregistered state and a second placement of one state, so a journey that names a
1021
+ and `view` resize nothing and write nothing, so a journey calls them unconditionally. They
1022
+ still refuse an unregistered state and a second placement of one state, so a journey that names a
998
1023
  state wrongly fails the ordinary run rather than the first capture run; `placements` and `paths`
999
- stay empty, because they answer for what was captured. An enabled `place` applies the variant and writes `<directory>/<state>--<variant>.png` through
1024
+ stay empty, because they answer for what was written, while `observed` lists every state `place`
1025
+ and `view` accepted, written or not, in placement order. A placement holds its state from before
1026
+ its first await until it settles, so a second placement of that state started meanwhile is refused
1027
+ as already placed, and a placement that throws leaves its state free to place again. A portfolio created with `state` writes that one
1028
+ state alone and accepts every other registered state unwritten, and creation refuses a `state` the
1029
+ registry does not carry. A `scope` handler names one directory segment per state: `files` and every
1030
+ written path carry it, and `expandCaptures` takes the same handler, so both refuse a scope that is
1031
+ empty, `.`, `..`, or carries a slash. An enabled `place` applies the variant and writes
1032
+ `<directory>/<state>--<variant>.png`, or `<directory>/<scope>/<state>--<variant>.png`, through
1000
1033
  `captureFrame`, so it stages the pane at the variant's size, covers the whole document, verifies the
1001
1034
  written bytes, and records only a path that read back as this run's own frame. A portfolio created
1002
- with `unrolled` passes it to every frame `place` writes. The tester comes back
1035
+ with `unrolled` passes it to every frame `place` writes. `place` takes an element to shoot that
1036
+ element alone. `view` writes the same filename through `captureViewport`, so it shoots the declared
1037
+ viewport at the scroll the journey reached. An unrolled portfolio refuses every `view` in every
1038
+ run, enabled or not, before it reads the projection, with
1039
+ `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`,
1040
+ the text `describeUnrolledView` renders. The tester comes back
1003
1041
  at the viewport it had before the placement, so a journey that places a state carries on at its own
1004
- size rather than at the variant's. `placements` and `paths` hand out snapshots, so a list read
1042
+ size rather than at the variant's. `observed`, `placements`, and `paths` hand out snapshots, so a list read
1005
1043
  before a placement stays what it was.
1006
1044
 
1007
1045
  `createJournal` records rather than replaces. Every intercepted console call is forwarded to the
@@ -1013,7 +1051,8 @@ drops when it stops. There is no shared instance: a file that needs one journal
1013
1051
  one per scenario.
1014
1052
 
1015
1053
  The filename law is injective within one run: one variant is selected, and every filename is
1016
- `<state>--<variant>.png`. A duplicate filename therefore implies a duplicate placement, which
1054
+ `<state>--<variant>.png`, or `<scope>/<state>--<variant>.png` under a `scope` handler, which names
1055
+ one scope per state. A duplicate filename therefore implies a duplicate placement, which
1017
1056
  `place` already refuses. Any future naming change that breaks this injectivity must reintroduce a
1018
1057
  collision refusal before writing.
1019
1058
 
@@ -1022,59 +1061,63 @@ collision refusal before writing.
1022
1061
  Imported from `@orkestrel/test/server`.
1023
1062
 
1024
1063
  The provider command consumes the browser journey's resolved selector inside Vitest's tester frame.
1025
- The progress reporter is a Vitest reporter a run lists beside its others.
1064
+ The progress reporter is a Vitest reporter a run lists beside its others, and the progress plugin
1065
+ adds it to a run whose command line names the reporters.
1026
1066
 
1027
- | Name | Kind | Signature | Summary |
1028
- | ------------------ | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1029
- | `chooseFiles` | function | `(context: ChooserContext, request: ChooserRequest) => Promise<void>` | Observes a native chooser before activating its input and supplies the verified chooser's fixture bytes. |
1030
- | `ProgressReporter` | class | `new () => Reporter` | Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live run's progress and each failure's first error can be read before the run ends. |
1067
+ | Name | Kind | Signature | Summary |
1068
+ | ---------------------- | -------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1069
+ | `chooseFiles` | function | `(context: ChooserContext, request: ChooserRequest) => Promise<void>` | Observes a native chooser before activating its input and supplies the verified chooser's fixture bytes. |
1070
+ | `ProgressReporter` | class | `new () => Reporter` | Appends one JSON line per Vitest run event to the file `--outputFile.progress` names, so a live run's progress and each failure's first error can be read before the run ends. |
1071
+ | `createProgressPlugin` | function | `() => ProgressPluginInterface` | Creates a Vitest plugin that adds one `ProgressReporter` to every run naming a progress file, so the reporter still runs when command-line `--reporter` flags replace the configured reporters. |
1031
1072
 
1032
1073
  #### Types
1033
1074
 
1034
- | Name | Kind | Signature | Summary |
1035
- | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1036
- | `ScratchInterface` | interface | `{ path, write(), read(), has(), names(), ensure(), link(), remove(), destroy() }` | Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. |
1037
- | `ScratchIdentity` | interface | `{ device, inode, birth }` | Represents the fields that together identify one allocated directory on its host. |
1038
- | `ScratchOptions` | interface | `{ parent?, prefix?, files? }` | Configures a scratch directory allocation. |
1039
- | `LoopbackInterface` | interface | `{ url, port, destroy() }` | Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. |
1040
- | `CookieJarInterface` | interface | `{ header, read(), capture() }` | Holds a name-keyed cookie store a test drives one origin with, filled from real responses. |
1041
- | `InventoryOptions` | interface | `{ extensions?, exclude? }` | Configures a source inventory read. |
1042
- | `UpgradeOptions` | interface | `{ path?, protocols? }` | Configures a client upgrade request. |
1043
- | `UpgradeResult` | type | `{ readonly claimed: true; readonly protocol: string \| undefined; } \| { readonly claimed: false; readonly status: number; }` | Represents what one server did with a client upgrade request. |
1044
- | `ChooserContext` | interface | `{ page, iframe }` | Supplies the real Playwright page and tester frame to a native chooser command. |
1045
- | `ProgressError` | interface | `{ message, location? }` | Represents one error a progress line carries: its first message line and where it was thrown. |
1046
- | `ProgressSpecification` | interface | `{ project, module }` | Names one module a run starts, under the project that runs it, as one Vitest specification. |
1047
- | `ProgressStamp` | interface | `{ time, pid }` | Represents the stamp every progress line carries. |
1048
- | `ProgressInitEvent` | interface | `{ event, version, wall, bail }` | Represents the line a reporter writes when Vitest initializes it. |
1049
- | `ProgressStartEvent` | interface | `{ event, specifications }` | Represents the line a reporter writes when a run starts, listing the modules it runs. |
1050
- | `ProgressCollectedEvent` | interface | `{ event, project, module, planned, errors }` | Represents the line a reporter writes when Vitest collects one module's cases. |
1051
- | `ProgressReadyEvent` | interface | `{ event, project, id, name }` | Represents the line a reporter writes when a planned case starts. |
1052
- | `ProgressCaseState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending'` | Names the state a case result reports, mirroring Vitest's `TestState`. |
1053
- | `ProgressCaseEvent` | interface | `{ event, project, module, id, name, state, duration?, start?, errors? }` | Represents the line a reporter writes once for each planned case's result. |
1054
- | `ProgressCancelEvent` | interface | `{ event, reason, wall }` | Represents the line a reporter writes each time Vitest cancels the run. |
1055
- | `ProgressModuleState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending' \| 'queued'` | Names the state a finished module reports, mirroring Vitest's `TestModuleState`. |
1056
- | `ProgressModuleEvent` | interface | `{ event, project, module, state, duration }` | Represents the line a reporter writes when a module finishes. |
1057
- | `ProgressEndReason` | type | `'passed' \| 'interrupted' \| 'failed'` | Names why a run ended, mirroring Vitest's `TestRunEndReason`. |
1058
- | `ProgressEndEvent` | interface | `{ event, reason, overhead, unhandled }` | Represents the line a reporter writes when a run ends. |
1059
- | `ProgressEvent` | type | `ProgressInitEvent \| ProgressStartEvent \| ProgressCollectedEvent \| ProgressReadyEvent \| ProgressCaseEvent \| ProgressCancelEvent \| ProgressModuleEvent \| ProgressEndEvent` | Represents one line of a progress file, discriminated by `event`. |
1060
- | `ProgressState` | type | `'live' \| ProgressEndReason` | Names a run's state as a reader sees it: `live` until its `end` line, then the end reason. |
1061
- | `ProgressRelation` | type | `'first' \| 'bail' \| 'later'` | Names how a failure relates to the run's bail: `first` is the earliest failure, `bail` is a failure past the bail setting whose result arrived or whose case ended after the first cancel, and `later` is any other failure. |
1062
- | `ProgressProject` | interface | `{ name, planned, done, passed, failed, skipped, modules, collected }` | Represents one project's tallies in a progress reading. |
1063
- | `ProgressCase` | interface | `{ project, name, duration }` | Represents a case that started and has not reported a result. |
1064
- | `ProgressFailure` | interface | `{ project, module, name, time, relation, error }` | Represents one failed case, or one module that failed to collect, in a progress reading. |
1065
- | `ProgressCancel` | interface | `{ reason, time }` | Represents the first cancel a run recorded. |
1066
- | `ProgressRun` | interface | `{ pid, wall, state, bail, elapsed, done, planned, exact, rate, remaining, projects, running, cancel, failures, overhead, unhandled }` | Represents where one run stands, read from its progress lines. |
1075
+ | Name | Kind | Signature | Summary |
1076
+ | ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1077
+ | `ScratchInterface` | interface | `{ path, write(), read(), has(), names(), ensure(), link(), remove(), destroy() }` | Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. |
1078
+ | `ScratchIdentity` | interface | `{ device, inode, birth }` | Represents the fields that together identify one allocated directory on its host. |
1079
+ | `ScratchOptions` | interface | `{ parent?, prefix?, files? }` | Configures a scratch directory allocation. |
1080
+ | `LoopbackInterface` | interface | `{ url, port, destroy() }` | Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. |
1081
+ | `CookieJarInterface` | interface | `{ header, read(), capture() }` | Holds a name-keyed cookie store a test drives one origin with, filled from real responses. |
1082
+ | `InventoryOptions` | interface | `{ extensions?, exclude? }` | Configures a source inventory read. |
1083
+ | `UpgradeOptions` | interface | `{ path?, protocols? }` | Configures a client upgrade request. |
1084
+ | `UpgradeResult` | type | `{ readonly claimed: true; readonly protocol: string \| undefined; } \| { readonly claimed: false; readonly status: number; }` | Represents what one server did with a client upgrade request. |
1085
+ | `ChooserContext` | interface | `{ page, iframe }` | Supplies the real Playwright page and tester frame to a native chooser command. |
1086
+ | `ProgressError` | interface | `{ message, location? }` | Represents one error a progress line carries: its first message line and where it was thrown. |
1087
+ | `ProgressSpecification` | interface | `{ project, module }` | Names one module a run starts, under the project that runs it, as one Vitest specification. |
1088
+ | `ProgressStamp` | interface | `{ time, pid }` | Represents the stamp every progress line carries. |
1089
+ | `ProgressInitEvent` | interface | `{ event, version, wall, bail }` | Represents the line a reporter writes when Vitest initializes it. |
1090
+ | `ProgressStartEvent` | interface | `{ event, specifications }` | Represents the line a reporter writes when a run starts, listing the modules it runs. |
1091
+ | `ProgressCollectedEvent` | interface | `{ event, project, module, planned, errors }` | Represents the line a reporter writes when Vitest collects one module's cases. |
1092
+ | `ProgressReadyEvent` | interface | `{ event, project, id, name }` | Represents the line a reporter writes when a planned case starts. |
1093
+ | `ProgressCaseState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending'` | Names the state a case result reports, mirroring Vitest's `TestState`. |
1094
+ | `ProgressCaseEvent` | interface | `{ event, project, module, id, name, state, duration?, start?, errors? }` | Represents the line a reporter writes once for each planned case's result. |
1095
+ | `ProgressCancelEvent` | interface | `{ event, reason, wall }` | Represents the line a reporter writes each time Vitest cancels the run. |
1096
+ | `ProgressModuleState` | type | `'passed' \| 'failed' \| 'skipped' \| 'pending' \| 'queued'` | Names the state a finished module reports, mirroring Vitest's `TestModuleState`. |
1097
+ | `ProgressModuleEvent` | interface | `{ event, project, module, state, duration }` | Represents the line a reporter writes when a module finishes. |
1098
+ | `ProgressEndReason` | type | `'passed' \| 'interrupted' \| 'failed'` | Names why a run ended, mirroring Vitest's `TestRunEndReason`. |
1099
+ | `ProgressEndEvent` | interface | `{ event, reason, overhead, unhandled }` | Represents the line a reporter writes when a run ends. |
1100
+ | `ProgressEvent` | type | `ProgressInitEvent \| ProgressStartEvent \| ProgressCollectedEvent \| ProgressReadyEvent \| ProgressCaseEvent \| ProgressCancelEvent \| ProgressModuleEvent \| ProgressEndEvent` | Represents one line of a progress file, discriminated by `event`. |
1101
+ | `ProgressState` | type | `'live' \| ProgressEndReason` | Names a run's state as a reader sees it: `live` until its `end` line, then the end reason. |
1102
+ | `ProgressRelation` | type | `'first' \| 'bail' \| 'later'` | Names how a failure relates to the run's bail: `first` is the earliest failure, `bail` is a failure past the bail setting whose result arrived or whose case ended after the first cancel, and `later` is any other failure. |
1103
+ | `ProgressProject` | interface | `{ name, planned, done, passed, failed, skipped, pending, modules, collected }` | Represents one project's tallies in a progress reading. |
1104
+ | `ProgressCase` | interface | `{ project, name, duration }` | Represents a case that started and has not reported a result. |
1105
+ | `ProgressFailure` | interface | `{ project, module, name, time, relation, error }` | Represents one failed case, or one module that failed to collect, in a progress reading. |
1106
+ | `ProgressCancel` | interface | `{ reason, time }` | Represents the first cancel a run recorded. |
1107
+ | `ProgressRun` | interface | `{ pid, wall, state, bail, elapsed, done, planned, exact, rate, remaining, projects, running, cancel, failures, overhead, unhandled }` | Represents where one run stands, read from its progress lines. |
1108
+ | `ProgressPluginInterface` | interface | `{ name, configureVitest() }` | Represents the Vitest plugin that adds one progress reporter to every run naming a progress file. |
1067
1109
 
1068
1110
  #### Constants
1069
1111
 
1070
- | Name | Kind | Signature | Summary |
1071
- | ----------------------------- | ----- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
1072
- | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
1073
- | `REMOVE_TREE_RETRY_DELAY_MS` | const | `100` | Names the synchronous delay, in milliseconds, `removeTree` waits between attempts. |
1074
- | `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]` | Names the error codes `removeTree` retries; every other code rethrows immediately. |
1075
- | `PROGRESS_VERSION` | const | `1` | Names the format version a progress file's `init` line carries; a reader refuses any other. |
1076
- | `PROGRESS_MESSAGE_LIMIT` | const | `300` | Caps the characters a progress error message keeps. |
1077
- | `PROGRESS_LABELS` | const | `Readonly<Record<ProgressRelation, string>>` | Names the label a rendered progress reading prints for each failure relation. |
1112
+ | Name | Kind | Signature | Summary |
1113
+ | ----------------------------- | ----- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
1114
+ | `REMOVE_TREE_MAX_ATTEMPTS` | const | `10` | Caps the attempts `removeTree` makes before rethrowing a retryable removal error. |
1115
+ | `REMOVE_TREE_RETRY_DELAY_MS` | const | `100` | Names the synchronous delay, in milliseconds, `removeTree` waits between attempts. |
1116
+ | `REMOVE_TREE_RETRYABLE_CODES` | const | `readonly string[]` | Names the error codes `removeTree` retries; every other code rethrows immediately. |
1117
+ | `PROGRESS_VERSION` | const | `1` | Names the format version a progress file's `init` line carries; a reader refuses any other. |
1118
+ | `PROGRESS_MESSAGE_LIMIT` | const | `300` | Caps the characters a progress error message keeps. |
1119
+ | `PROGRESS_BRAND` | const | `unique symbol` | Keys the brand every `ProgressReporter` carries, registered so that each copy of this package reads the same key. |
1120
+ | `PROGRESS_LABELS` | const | `Readonly<Record<ProgressRelation, string>>` | Names the label a rendered progress reading prints for each failure relation. |
1078
1121
 
1079
1122
  #### Validators
1080
1123
 
@@ -1085,41 +1128,42 @@ The progress reporter is a Vitest reporter a run lists beside its others.
1085
1128
 
1086
1129
  #### Helpers
1087
1130
 
1088
- | Name | Kind | Signature | Summary |
1089
- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
1090
- | `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
1091
- | `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
1092
- | `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
1093
- | `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
1094
- | `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
1095
- | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1096
- | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1097
- | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1098
- | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1099
- | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1100
- | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1101
- | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
1102
- | `removeTree` | function | `(path: string) => void` | Removes a directory tree, retrying past a transient Windows handle-release race. |
1103
- | `isRunning` | function | `(pid: number) => boolean` | Reports whether a process id names a live process. |
1104
- | `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>` | Waits for a socket to close, accepting a peer reset as a forced close. |
1105
- | `normalizeProgressPath` | function | `(file: string, root: string) => string` | Normalizes a module or stack-frame path to the form a progress line carries. |
1106
- | `extractProgressError` | function | `(error: SerializedError, root: string) => ProgressError` | Extracts the message line and location a progress line keeps from one Vitest error. |
1107
- | `matchesPlannedCase` | function | `(test: { readonly options: { readonly mode: string; }; }) => boolean` | Reports whether a collected case is one the run plans to report. |
1108
- | `readFileSnapshot` | function | `(path: string) => Buffer` | Reads the bytes a file holds when it is opened, leaving out every byte appended during the read. |
1109
- | `filterProgressEvents` | function | `<TName extends ProgressEvent['event']>(events: readonly ProgressEvent[], name: TName) => ReadonlyArray<Extract<ProgressEvent, { readonly event: TName; }>>` | Filters the progress lines of one event. |
1110
- | `extractProgressEvents` | function | `(text: string) => readonly ProgressEvent[]` | Extracts the progress lines a text holds, skipping a partial last line. |
1111
- | `computeProgressRun` | function | `(events: readonly ProgressEvent[], now: number) => ProgressRun \| undefined` | Computes where the run one process wrote stands, from its last `init` line on. |
1112
- | `computeProgress` | function | `(events: readonly ProgressEvent[], now: number) => readonly ProgressRun[]` | Computes where every run a progress file holds stands, one run per writing process. |
1113
- | `readProgress` | function | `(path: string, now?: number) => readonly ProgressRun[]` | Reads where every run a progress file holds stands, live or finished. |
1114
- | `renderDuration` | function | `(milliseconds: number) => string` | Renders a duration as whole minutes and seconds. |
1115
- | `renderProgress` | function | `(runs: readonly ProgressRun[]) => string` | Renders progress runs as the text a person reads mid-run. |
1116
- | `destroyScratch` | function | `(scratch: ScratchInterface, options?: WaitOptions) => Promise<void>` | Destroys a scratch directory, retrying until the host releases it. |
1117
- | `requestUpgrade` | function | `(port: number, options?: UpgradeOptions) => Promise<UpgradeResult>` | Drives a real client upgrade request against a loopback port and reports what the server did. |
1118
- | `supportsDirectoryLinks` | function | `() => boolean` | Checks whether this host links a directory, by creating one link and reading through it. |
1119
- | `supportsFileLinks` | function | `() => boolean` | Checks whether this host links a file, by creating one link and reading the file through it. |
1120
- | `supportsMode` | function | `() => boolean` | Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`. |
1121
- | `supportsCase` | function | `() => boolean` | Checks whether this host treats two names differing only by case as distinct files. |
1122
- | `supportsBytes` | function | `() => boolean` | Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves. |
1131
+ | Name | Kind | Signature | Summary |
1132
+ | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
1133
+ | `readLoopClock` | function | `() => number` | Reads the loop clock Node stamps on an armed timer, in whole milliseconds. |
1134
+ | `alignLoopClock` | function | `(offset?: number) => void` | Spins synchronously past a loop-clock tick and an optional millisecond offset. |
1135
+ | `readCapture` | function | `(path: string) => Promise<string>` | Reads the lowercase hexadecimal SHA-256 digest of a captured file's bytes. |
1136
+ | `readInventory` | function | `(root: URL \| string, targets: readonly string[], options?: InventoryOptions) => Readonly<Record<string, string>>` | Reads files from selected targets below a root directory. |
1137
+ | `resolveContained` | function | `(root: string, target: string) => string \| undefined` | Resolves a target that stays below a root directory. |
1138
+ | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1139
+ | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1140
+ | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1141
+ | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1142
+ | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1143
+ | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1144
+ | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
1145
+ | `removeTree` | function | `(path: string) => void` | Removes a directory tree, retrying past a transient Windows handle-release race. |
1146
+ | `isRunning` | function | `(pid: number) => boolean` | Reports whether a process id names a live process, reading each of its threads on Linux. |
1147
+ | `waitForSocketClose` | function | `(socket: Socket, options?: WaitOptions) => Promise<void>` | Waits for a socket to close, accepting a peer reset as a forced close. |
1148
+ | `normalizeProgressPath` | function | `(file: string, root: string) => string` | Normalizes a module or stack-frame path to the form a progress line carries. |
1149
+ | `extractProgressError` | function | `(error: SerializedError, root: string) => ProgressError` | Extracts the message line and location a progress line keeps from one Vitest error. |
1150
+ | `matchesPlannedCase` | function | `(test: { readonly options: { readonly mode: string; }; }) => boolean` | Reports whether a collected case is one the run plans to report. |
1151
+ | `matchesProgressReporter` | function | `(value: unknown) => boolean` | Checks whether a value is a progress reporter from any copy of this package, by the brand each one carries under `PROGRESS_BRAND`. |
1152
+ | `readFileSnapshot` | function | `(path: string) => Buffer` | Reads the bytes a file holds when it is opened, leaving out every byte appended during the read. |
1153
+ | `filterProgressEvents` | function | `<TName extends ProgressEvent['event']>(events: readonly ProgressEvent[], name: TName) => ReadonlyArray<Extract<ProgressEvent, { readonly event: TName; }>>` | Filters the progress lines of one event. |
1154
+ | `extractProgressEvents` | function | `(text: string) => readonly ProgressEvent[]` | Extracts the progress lines a text holds, skipping a partial last line. |
1155
+ | `computeProgressRun` | function | `(events: readonly ProgressEvent[], now: number) => ProgressRun \| undefined` | Computes where the run one process wrote stands, from its last `init` line on. |
1156
+ | `computeProgress` | function | `(events: readonly ProgressEvent[], now: number) => readonly ProgressRun[]` | Computes where every run a progress file holds stands, one run per writing process. |
1157
+ | `readProgress` | function | `(path: string, now?: number) => readonly ProgressRun[]` | Reads where every run a progress file holds stands, live or finished. |
1158
+ | `renderDuration` | function | `(milliseconds: number) => string` | Renders a duration as whole minutes and seconds. |
1159
+ | `renderProgress` | function | `(runs: readonly ProgressRun[]) => string` | Renders progress runs as the text a person reads mid-run. |
1160
+ | `destroyScratch` | function | `(scratch: ScratchInterface, options?: WaitOptions) => Promise<void>` | Destroys a scratch directory, retrying until the host releases it. |
1161
+ | `requestUpgrade` | function | `(port: number, options?: UpgradeOptions) => Promise<UpgradeResult>` | Drives a real client upgrade request against a loopback port and reports what the server did. |
1162
+ | `supportsDirectoryLinks` | function | `() => boolean` | Checks whether this host links a directory, by creating one link and reading through it. |
1163
+ | `supportsFileLinks` | function | `() => boolean` | Checks whether this host links a file, by creating one link and reading the file through it. |
1164
+ | `supportsMode` | function | `() => boolean` | Checks whether POSIX permission bits round-trip through this host's `chmod` and `stat`. |
1165
+ | `supportsCase` | function | `() => boolean` | Checks whether this host treats two names differing only by case as distinct files. |
1166
+ | `supportsBytes` | function | `() => boolean` | Checks whether this host accepts a filename carrying a raw byte no UTF-8 decoder resolves. |
1123
1167
 
1124
1168
  `hasScratchPath` takes a scratch's absolute path and a relative or absolute target. It checks
1125
1169
  containment before inspecting the root, returns `false` for a missing root or entry, and refuses a
@@ -1307,6 +1351,12 @@ adopted.release()
1307
1351
  | `act` | `Promise<void> \| void` | Applies the transition's event to the arranged entity. |
1308
1352
  | `assert` | `Promise<void> \| void` | Checks that the entity reached the transition's `to` state. |
1309
1353
 
1354
+ #### `ProgressPluginInterface`
1355
+
1356
+ | Method | Returns | Summary |
1357
+ | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1358
+ | `configureVitest` | `void` | Adds a `ProgressReporter` to the run's reporters when `outputFile` names `progress`, and adds nothing when no progress file is named or the reporters already hold a `ProgressReporter` from any copy of this package. |
1359
+
1310
1360
  #### `LoopbackInterface`
1311
1361
 
1312
1362
  | Method | Returns | Summary |
@@ -1322,9 +1372,10 @@ adopted.release()
1322
1372
 
1323
1373
  #### `PortfolioInterface`
1324
1374
 
1325
- | Method | Returns | Summary |
1326
- | ------- | ------------------------------ | ------------------------------------------------------------------------------------------------------ |
1327
- | `place` | `Promise<string \| undefined>` | Places one registered state: applies the variant, stages the pane, and writes the verified screenshot. |
1375
+ | Method | Returns | Summary |
1376
+ | ------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1377
+ | `place` | `Promise<string \| undefined>` | Places one registered state: applies the variant, stages the pane, and writes the verified screenshot. |
1378
+ | `view` | `Promise<string \| undefined>` | Places one registered state as the declared viewport at the scroll the journey reached: applies the variant, stages the pane at the variant's size alone, and writes the verified screenshot. |
1328
1379
 
1329
1380
  #### `JournalInterface`
1330
1381
 
@@ -1461,65 +1512,68 @@ what the link reaches, not on what it stores.
1461
1512
  Every message `src/browser` throws. Keep them distinct: a journey asserts the one it means, and
1462
1513
  absent, present-but-gated, and ambiguous are different findings about an interface.
1463
1514
 
1464
- | Voice | Thrown by |
1465
- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
1466
- | `No interactive element has the accessible name "<name>"` | `resolveRendered` |
1467
- | `Interactive target "<name>" is not visible and focus-reachable` | `resolveRendered` |
1468
- | `Interactive target "<name>" is ambiguous across <n> elements` | `resolveRendered` |
1469
- | `Interactive target "<name>" could not be resolved` | `resolveRendered` |
1470
- | `Interactive target "<name>" is unreachable after scrolling` | `resolveAccessible` |
1471
- | `Interactive target "<name>" is not reachable inside "<region>"` | `resolveAccessibleWithin` |
1472
- | `Interactive target "<name>" is ambiguous across <n> elements inside "<region>"` | `resolveAccessibleWithin` |
1473
- | `Interactive target "<name>" could not be resolved inside "<region>"` | `resolveAccessibleWithin` |
1474
- | `Native disclosure "<name>" is not visible and focus-reachable` | `clickDisclosure` |
1475
- | `Native disclosure "<name>" is ambiguous across <n> elements` | `clickDisclosure` |
1476
- | `Native disclosure "<name>" could not be resolved` | `clickDisclosure` |
1477
- | `The element is not connected to a document, so it has no point to read` | `readProtocolPoint` |
1478
- | `Interactive target "<name>" is not reachable through forward Tab traversal: <trail>` | `driveTraversal` |
1479
- | `Named region "<name>" is not visible` | `readPerception` |
1480
- | `Named region "<name>" is ambiguous across <n> elements` | `readPerception` |
1481
- | `Named region "<name>" could not be resolved` | `readPerception` |
1482
- | `Interactive target "<name>" does not carry a value` | `readControlValue` |
1483
- | `Computed foreground color is unavailable` | `readContrast` |
1484
- | `Computed background color is unavailable` | `readColorContrast` |
1485
- | `Color "<value>" is unreadable` | `readColorContrast` |
1486
- | `Contrast opacity must be between 0 and 1` | `readColorContrast` |
1487
- | `The element is not connected to a document, so it has no clipping ancestors to read` | `collectClippingAncestors`, `readClippedBlock` |
1488
- | `Tester pane is unavailable for a capture` | `stagePane` |
1489
- | `Tester pane rendered <w>x<h> for a <w>x<h> viewport` | `stagePane` |
1490
- | `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane[; scroll regions still hiding rows: <region> hides <n> px, …]` | `captureFrame` |
1491
- | `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` | `captureFrame` |
1492
- | `Capture frame was written to <path> where <path> was asked for` | `captureFrame`, `verifyFrame` |
1493
- | `Capture frame at <path> is not the one this run shot` | `captureFrame`, `verifyFrame` |
1494
- | `Capture path must be absolute: <path>` | `readCapture` |
1495
- | `Capture frame at <path> could not be read` | `readFrame` |
1496
- | `Capture frame at <path> is not an image this browser decodes` | `readFrame` |
1497
- | `Capture frame at <path> is not an image this browser decodes: <w>x<h> device pixels` | `readFrame` |
1498
- | `Capture frame at <path> cannot be measured without a 2D canvas` | `readFrame` |
1499
- | `Shot is not an image this browser decodes` | `readShotPixel` |
1500
- | `Shot cannot be measured without a 2D canvas` | `readShotPixel` |
1501
- | `Shot pixel position must be a fraction from 0 to 1` | `readShotPixel` |
1502
- | `Capture variant "<name>" is not registered` | `createPortfolio` |
1503
- | `Capture state "<state>" is not registered` | `place` |
1504
- | `Capture state "<state>" is already placed` | `place` |
1505
- | `IndexedDB database "<name>" could not be deleted` | `removeDatabase` |
1506
- | `IndexedDB database "<name>" is blocked by an open connection` | `removeDatabase` |
1507
- | `Key sequence "<keys>" was sent with nothing focused` | `pressKeys` |
1508
- | `Focus sits in a frame from another origin, which cannot be read` | `readActiveElement` |
1509
- | `Focus traversal did not end` | `walkFocus` |
1510
- | `The start element cannot take focus` | `collectTabStops` |
1511
- | `Stability frames must be a positive integer` | `waitForStability` |
1512
- | `Condition "<description>" did not hold within <n>ms (waited <n>ms)` | `waitForStability` |
1513
- | `Condition "<subject>" did not hold within <n>ms (waited <n>ms) (last states: <states>)` | `waitForState` |
1514
- | `Animation subject is not connected` | `waitForAnimations` |
1515
- | `Animation "<subject>" did not settle within <n>ms (waited <n>ms): <animations>` | `waitForAnimations` |
1516
- | `Class census walked no element` | `readCensus` |
1517
- | `Contrast control cannot straddle the bar <bar>` | `buildContrast` |
1518
- | `Access is denied for <operation> "<key>"` | `buildDenial` |
1519
- | `No room is left for <key>` | `createStorage` |
1520
- | `Storage quota must be a non-negative integer` | `createStorage` |
1521
- | `Statechart harness mounted no transition` | `createHarness` |
1522
- | `Statechart harness carries no status` | `status` |
1515
+ | Voice | Thrown by |
1516
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
1517
+ | `No interactive element has the accessible name "<name>"` | `resolveRendered` |
1518
+ | `Interactive target "<name>" is not visible and focus-reachable` | `resolveRendered` |
1519
+ | `Interactive target "<name>" is ambiguous across <n> elements` | `resolveRendered` |
1520
+ | `Interactive target "<name>" could not be resolved` | `resolveRendered` |
1521
+ | `Interactive target "<name>" is unreachable after scrolling` | `resolveAccessible` |
1522
+ | `Interactive target "<name>" is not reachable inside "<region>"` | `resolveAccessibleWithin` |
1523
+ | `Interactive target "<name>" is ambiguous across <n> elements inside "<region>"` | `resolveAccessibleWithin` |
1524
+ | `Interactive target "<name>" could not be resolved inside "<region>"` | `resolveAccessibleWithin` |
1525
+ | `Native disclosure "<name>" is not visible and focus-reachable` | `clickDisclosure` |
1526
+ | `Native disclosure "<name>" is ambiguous across <n> elements` | `clickDisclosure` |
1527
+ | `Native disclosure "<name>" could not be resolved` | `clickDisclosure` |
1528
+ | `The element is not connected to a document, so it has no point to read` | `readProtocolPoint` |
1529
+ | `Interactive target "<name>" is not reachable through forward Tab traversal: <trail>` | `driveTraversal` |
1530
+ | `Named region "<name>" is not visible` | `readPerception` |
1531
+ | `Named region "<name>" is ambiguous across <n> elements` | `readPerception` |
1532
+ | `Named region "<name>" could not be resolved` | `readPerception` |
1533
+ | `Interactive target "<name>" does not carry a value` | `readControlValue` |
1534
+ | `Computed foreground color is unavailable` | `readContrast` |
1535
+ | `Computed background color is unavailable` | `readColorContrast` |
1536
+ | `Color "<value>" is unreadable` | `readColorContrast` |
1537
+ | `Contrast opacity must be between 0 and 1` | `readColorContrast` |
1538
+ | `The element is not connected to a document, so it has no clipping ancestors to read` | `collectClippingAncestors`, `readClipBound`, `readClippedBlock` |
1539
+ | `Tester pane is unavailable for a capture` | `stagePane` |
1540
+ | `Tester pane rendered <w>x<h> for a <w>x<h> viewport` | `stagePane` |
1541
+ | `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane[; scroll regions still hiding rows: <region> hides <n> px, …]` | `captureFrame` |
1542
+ | `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` | `captureFrame` |
1543
+ | `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` | `captureViewport` |
1544
+ | `Capture frame was written to <path> where <path> was asked for` | `captureFrame`, `captureViewport`, `verifyFrame` |
1545
+ | `Capture frame at <path> is not the one this run shot` | `captureFrame`, `captureViewport`, `verifyFrame` |
1546
+ | `Capture path must be absolute: <path>` | `readCapture` |
1547
+ | `Capture frame at <path> could not be read` | `readFrame` |
1548
+ | `Capture frame at <path> is not an image this browser decodes` | `readFrame` |
1549
+ | `Capture frame at <path> is not an image this browser decodes: <w>x<h> device pixels` | `readFrame` |
1550
+ | `Capture frame at <path> cannot be measured without a 2D canvas` | `readFrame` |
1551
+ | `Shot is not an image this browser decodes` | `readShotPixel` |
1552
+ | `Shot cannot be measured without a 2D canvas` | `readShotPixel` |
1553
+ | `Shot pixel position must be a fraction from 0 to 1` | `readShotPixel` |
1554
+ | `Capture variant "<name>" is not registered` | `createPortfolio` |
1555
+ | `Capture scope "<scope>" of state "<state>" is not one path segment` | `expandCaptures`, `createPortfolio` |
1556
+ | `Capture state "<state>" is not registered` | `createPortfolio`, `place`, `view` |
1557
+ | `Capture state "<state>" is already placed` | `place`, `view` |
1558
+ | `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` | `view`, `describeUnrolledView` |
1559
+ | `IndexedDB database "<name>" could not be deleted` | `removeDatabase` |
1560
+ | `IndexedDB database "<name>" is blocked by an open connection` | `removeDatabase` |
1561
+ | `Key sequence "<keys>" was sent with nothing focused` | `pressKeys` |
1562
+ | `Focus sits in a frame from another origin, which cannot be read` | `readActiveElement` |
1563
+ | `Focus traversal did not end` | `walkFocus` |
1564
+ | `The start element cannot take focus` | `collectTabStops` |
1565
+ | `Stability frames must be a positive integer` | `waitForStability` |
1566
+ | `Condition "<description>" did not hold within <n>ms (waited <n>ms)` | `waitForStability` |
1567
+ | `Condition "<subject>" did not hold within <n>ms (waited <n>ms) (last states: <states>)` | `waitForState` |
1568
+ | `Animation subject is not connected` | `waitForAnimations` |
1569
+ | `Animation "<subject>" did not settle within <n>ms (waited <n>ms): <animations>` | `waitForAnimations` |
1570
+ | `Class census walked no element` | `readCensus` |
1571
+ | `Contrast control cannot straddle the bar <bar>` | `buildContrast` |
1572
+ | `Access is denied for <operation> "<key>"` | `buildDenial` |
1573
+ | `No room is left for <key>` | `createStorage` |
1574
+ | `Storage quota must be a non-negative integer` | `createStorage` |
1575
+ | `Statechart harness mounted no transition` | `createHarness` |
1576
+ | `Statechart harness carries no status` | `status` |
1523
1577
 
1524
1578
  `readContrast` measures through `readColorContrast`, so its background refusal is that row's voice,
1525
1579
  and `readRing` never raises it, because it names `CANVAS_COLOR` as the floor on every reading.
@@ -1910,13 +1964,12 @@ These hold across `src/core`, `src/browser`, `src/server`, and this guide.
1910
1964
  stopped, and `steps` and `output` hand out snapshots. There is no shared instance: a file that
1911
1965
  needs one journal per scenario creates one per scenario.
1912
1966
  18. **The capture layer depends on the Vitest runner's own tester layout, deliberately.** A
1913
- screenshot is taken off the page the runner painted, and `vitest@4.1.12` lays its tester out
1914
- inside a smaller page and fits it by scaling the pane the tester sits in, so a frame shot through
1915
- that scale is a thumbnail of the surface. `stagePane` therefore reaches into that layout: the
1916
- `iframe[data-vitest]` selector and the `--tester-transform`, `--tester-margin-left`,
1917
- `--viewport-width`, and `--viewport-height` custom properties are the runner's, not this
1918
- package's. Direct `transform: none !important` rules also suppress Vitest 5's pane and iframe
1919
- scaling. The disk check compares Node and browser SHA-256 digests where the consumer registers
1967
+ screenshot is taken off the page the runner painted, and `vitest@5.1.0` lays its tester out
1968
+ inside a smaller page and fits it with a CSS scale, so a frame shot through that scale is a
1969
+ thumbnail of the surface. `stagePane` therefore reaches into that layout: the
1970
+ `iframe[data-vitest]` selector and the `--viewport-width` and `--viewport-height` custom
1971
+ properties are the runner's, not this package's, and `transform: none !important` rules on the
1972
+ pane and iframe suppress the fitting scale. The disk check compares Node and browser SHA-256 digests where the consumer registers
1920
1973
  `readCapture`, and keeps the runner's built-in base64 read-back otherwise. That is contract
1921
1974
  rather than accident. A Vitest release that renames any of
1922
1975
  them reddens `stagePane`'s size check, which throws
@@ -2167,8 +2220,10 @@ the helper rather than to the host, and each names what to reach for instead.
2167
2220
  for one frame.
2168
2221
  - **`settleCapture` holds endless animations until its resume runs.** It parks the pointer through
2169
2222
  `parkPointer`, so a held press stays held and only loses its hover and pressed paint; `pointer: false`
2170
- leaves the pointer, its hover, and that paint where they are. It waits out every finite animation
2171
- in the document, root element included, then pauses each endless one at its first frame and
2223
+ leaves the pointer, its hover, and that paint where they are. It waits one frame, so a transition
2224
+ the page starts from an animation-frame callback after the act is running, waits out every finite
2225
+ animation in the document, root element included, yields one task so that a listener on an animation's end
2226
+ event, such as `transitionend`, has run, then pauses each endless one at its first frame and
2172
2227
  resolves to the resume. Call the resume from a `finally` block after the frame is shot. A settle
2173
2228
  whose wait exhausts throws before it holds anything, so it owes no resume.
2174
2229
  - **`readShotPixel` reads a shot at the runner's scale.** The position is a fraction of the shot,
@@ -3051,7 +3106,7 @@ Object.keys(
3051
3106
  Object.keys(
3052
3107
  readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
3053
3108
  )
3054
- // ['src/bin/reporter.ts', 'src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts',
3109
+ // ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts',
3055
3110
  // 'src/core/helpers.ts', 'src/core/index.ts', 'src/core/types.ts', 'src/core/validators.ts']
3056
3111
 
3057
3112
  // An exclusion also applies to a target you name, so naming one file below an excluded directory
@@ -3281,7 +3336,10 @@ synchronous write per line, so a second process can read the file at any moment.
3281
3336
  and `case` lines only for the cases each module plans to run, so a name filter's removed cases
3282
3337
  never count, and it writes one `case` line per planned case even where a bail makes Vitest report a
3283
3338
  case twice. It records every `cancel` Vitest delivers, registering its listener once a module
3284
- queues, because Vitest clears cancel listeners after `onTestRunStart`.
3339
+ queues, because Vitest clears cancel listeners after `onTestRunStart`. When one Vitest holds several
3340
+ instances, such as two a configuration lists, only the first in `vitest.config.reporters` writes,
3341
+ so a run is never counted twice. Each instance carries a brand under `PROGRESS_BRAND`, and
3342
+ `matchesProgressReporter` reads it, so an instance from another copy of the package counts too.
3285
3343
 
3286
3344
  This read summarizes the file once, from another process or the same one, and renders it.
3287
3345
 
@@ -3298,8 +3356,14 @@ console.log(renderProgress(runs))
3298
3356
  and writes nothing. It returns one run per writing process, each read from that process's last
3299
3357
  `init` line, and each run carries that line's `wall` time. The rendered text gives cases done
3300
3358
  against planned per project, with `+` on the total until every module is collected, the elapsed
3301
- time, rate, and estimate, the running cases, the cancel, and each failure under its module and case
3302
- with its first message line and location. A module that fails to collect, such as one that throws
3359
+ time, rate, and estimate, all counting the cases that passed, failed, or skipped. Under a bail,
3360
+ Vitest reports `skipped` for the case a module is running when the cancel arrives and for each case
3361
+ left after it in that module, and gives a reporter nothing that tells those cases from a case that
3362
+ skipped itself, so they count as done, in the rate, and in the estimate, as the JSON report counts
3363
+ them. Each case a bail leaves in a module that was running no case reports `pending`, as the JSON
3364
+ report reads it, stays outside done, and its project line names it beside the other tallies. The
3365
+ rendered text also gives the running cases, the cancel, and
3366
+ each failure under its module and case with its first message line and location. A module that fails to collect, such as one that throws
3303
3367
  while it is imported, reads as a failure under its module alone, and as `FIRST` when its line comes
3304
3368
  before every other failure line. The earliest failure line reads `FIRST` even when Vitest wrote the
3305
3369
  cancel before its result. Only a failed case can trigger a bail, so under a bail the first failed
@@ -3313,13 +3377,31 @@ from its last `init` line, and `wall` tells them apart. A run killed before its
3313
3377
  `live` until its file is deleted. Watch mode initializes the reporter once, so its reruns pile under
3314
3378
  one `init` line and are outside what the format reads.
3315
3379
 
3316
- Without a configuration, name the published entry and its file on the command line. Vitest
3317
- constructs the entry's default export, `ProgressReporter`.
3380
+ A command line that passes `--reporter` flags replaces the reporters a configuration lists, so
3381
+ mount the progress plugin instead. Its hook adds one `ProgressReporter` after the flags are read,
3382
+ and only when the resolved `outputFile` names `progress`, from `--outputFile.progress` or from the
3383
+ configuration's `outputFile`.
3318
3384
 
3319
- ```bash
3320
- npx vitest run --reporter=@orkestrel/test/reporter --outputFile.progress=tmp/runs/progress.jsonl
3385
+ ```ts
3386
+ import { defineConfig } from 'vitest/config'
3387
+ import { createProgressPlugin } from '@orkestrel/test/server'
3388
+
3389
+ export default defineConfig({
3390
+ // Vitest calls the plugin's configureVitest hook before it constructs the run's reporters.
3391
+ plugins: [createProgressPlugin()],
3392
+ test: { projects: [() => ({ test: { name: 'unit' } })] },
3393
+ })
3394
+ // npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
3321
3395
  ```
3322
3396
 
3397
+ The hook runs once for each project that carries the plugin, and a project that mounts the plugin
3398
+ itself makes Vitest evaluate the configuration again. A configuration that imports the package by a
3399
+ file path loads a separate copy of the module for each evaluation. The hook adds nothing while the
3400
+ run's reporters already hold a `ProgressReporter` from any copy, read by its brand, so the run
3401
+ writes one `init` line wherever the plugin is mounted, whether the configuration imports the
3402
+ package by name or by a file path. A run whose resolved `outputFile` names no `progress` file gets no reporter and writes
3403
+ nothing.
3404
+
3323
3405
  ### Probe what the host supports
3324
3406
 
3325
3407
  Gate a proof on the mechanism it needs rather than on the platform name. Each probe allocates its own
@@ -4061,18 +4143,25 @@ portfolio.files // the same four names, so a proof compares one expansion agains
4061
4143
 
4062
4144
  // Placed from inside the journey that reached the state, right after the assertion that proves it.
4063
4145
  await portfolio.place('start-empty')
4064
- // A run that omits `enabled` returns undefined here, resizes nothing, and records nothing.
4146
+ // Shot as the declared viewport at the scroll the journey reached, rather than the whole page.
4147
+ await portfolio.view('answer-ideal')
4148
+ // A run that omits `enabled` returns undefined here, resizes nothing, and writes nothing.
4065
4149
 
4066
4150
  portfolio.place('answer-partial') // rejects: Capture state "answer-partial" is not registered
4067
4151
  ```
4068
4152
 
4069
4153
  Settle the page before each frame of a capture run. `settleCapture` parks the pointer, waits out
4070
4154
  every finite animation in the document, and holds each endless one at its first frame, so a hover,
4071
- a transition caught part way, and a spinner's phase stay out of the picture. It resolves to the
4072
- resume; call `place` after it, and call the resume from a `finally` block, so the held animations
4073
- run again whether or not the frame was written. Pass `pointer: false` where the pointer is part of
4074
- the state, such as a drag in flight. Gate the settle on the flag that `enabled` takes: an ordinary run's
4075
- `place` shoots nothing, and parking the pointer there changes the journey that run is proving.
4155
+ a transition caught part way, and a spinner's phase stay out of the picture. A listener the page
4156
+ runs on a transition's end has run when the settle resolves, so the layout it finalizes is the one
4157
+ shot. It resolves to the resume; call `place` after it, and call the resume from a `finally`
4158
+ block, so the held animations run again whether or not the frame was written. Pass
4159
+ `pointer: false` where the pointer is part of the state, such as a drag in flight. Gate the settle
4160
+ on the flag that `enabled` takes: an ordinary run's `place` shoots nothing, and parking the
4161
+ pointer there changes the journey that run is proving.
4162
+ Where a run navigates under reduced motion, call `stageMedia` with `{ motion: true }` before each
4163
+ settle; the frame then equals a default-motion run's only where the application fixes no state at
4164
+ mount from the motion query.
4076
4165
  Where a frame holds a scroll region, record `describeScrollRegions` of what `collectScrollRegions`
4077
4166
  finds beside it, because a picture does not show how far a pane scrolls.
4078
4167
 
@@ -4226,7 +4315,10 @@ Each entry names the contracts its file proves. The test names carry the cases.
4226
4315
  against constructed markup. The `recordConsole` proofs cover its line format, forwarding, and recording before forwarding. The touch proofs cover a pointer-dependent target beside a sibling,
4227
4316
  a target moving across painted frames before settling, a supplied stability budget that refuses
4228
4317
  the tap, and both orders of media and touch teardown. The pointer proof restores the first coarse
4229
- reading after fine then coarse staging. The file-drag proofs reach a target under a smooth root
4318
+ reading after fine then coarse staging. Every touch and pointer proof that asserts a fine pointer
4319
+ after touch emulation ends first turns touch emulation on and off, and skips with that mechanism
4320
+ named where the browser keeps `(pointer: none)` afterward, as Chromium build 1243 does. The
4321
+ file-drag proofs reach a target under a smooth root
4230
4322
  and refuse a file name without scrolling or writing any file in the batch. The `releaseTouch`
4231
4323
  rethrow of a non-idle protocol error is covered by review: its cancellation parameters are fixed,
4232
4324
  and no controllable non-idle refusal was found through the browser provider without replacing
@@ -4269,8 +4361,12 @@ Each entry names the contracts its file proves. The test names carry the cases.
4269
4361
  outside the subject left out, and a detached element read as two empty lists. `settleCapture`
4270
4362
  takes a hovered control's transition waited out and a spinner held at its first frame until the
4271
4363
  resume sets it running, a held press whose hover and pressed paint `pointer: false` leaves in
4272
- place beside the default park that takes both away, and an exhausted wait refused with nothing
4273
- held. `collectScrollRegions` takes a vertical and a horizontal scroller beside a box whose content
4364
+ place beside the default park that takes both away, an exhausted wait and an aborted one refused
4365
+ with nothing held, a transition the page starts from an animation-frame callback waited out, a
4366
+ transition's end listener run by the time it resolves, and one frame shot
4367
+ across repeated settles of a held spinner, a parked hover, and a finalized transition, beside a
4368
+ running spinner, a kept hover, and an unfinalized transition that each shoot another.
4369
+ `collectScrollRegions` takes a vertical and a horizontal scroller beside a box whose content
4274
4370
  fits, a clipping box, and a hidden one, each axis alone, and a scrolling root counted itself;
4275
4371
  `describeScrollRegions` takes a region named by its tag, its id, and its cut accessible name with
4276
4372
  its offsets after a scroll, the window's position after a scroll, and an empty population.
@@ -4399,7 +4495,18 @@ Each entry names the contracts its file proves. The test names carry the cases.
4399
4495
  missing paths. `captureFrame` takes a real file written, read back, and matched, with a planted file as the
4400
4496
  comparison's negative control, one element shot rather than the page, and a pane pinned to the
4401
4497
  wrong size by a rule of higher specificity, which is the refusal that also proves the release runs
4402
- on the failing path. It also takes a document taller than the pane, whose frame equals the
4498
+ on the failing path. `captureViewport` takes five 400-row bands, scrolled to row 600 with the
4499
+ viewport prepared and with it resized, and holds rows 600 to 999, green at the top and blue on the
4500
+ floor, with no resize past the starting height and the scroll kept; the plain frame of the same
4501
+ page is its control, restaged to 2000 rows and ending on purple. A page rule marked important
4502
+ that sets `opacity` and a magenta background on the root element's `div` children leaves that
4503
+ frame green over blue, beside the control that the cover's declarations written without priority
4504
+ read the rule's opacity. A root element under a paint containment refuses the cover with the pane
4505
+ and the scroll handed back. A type assertion pins `ViewportOptions` to the path and the viewport
4506
+ and keeps `FrameOptions` without a viewport switch. `recordScroll` scrolls the window and a scroll
4507
+ container back to the positions it recorded, and `describeUnrolledView` renders the refusal text
4508
+ word for word. It also takes a document taller than
4509
+ the pane, whose frame equals the
4403
4510
  fixture's own declared 1600 rows and ends on the background the document declares rather than on
4404
4511
  the runner's canvas, and a document shorter than the pane, whose frame stays at the pane's height
4405
4512
  on that same floor. The equality is the control that an overshoot adds no rows: a frame taller
@@ -4460,7 +4567,10 @@ Each entry names the contracts its file proves. The test names carry the cases.
4460
4567
  the box its scroll height reads, with a trailing margin counted, and a descendant capped at an
4461
4568
  inner frame's clip edge, and leaves out a fixed box and an absolute box laid out against a block
4462
4569
  outside the region until the region is positioned; it reads the rows a host scrolls in its own
4463
- shadow root and the slotted rows a shadow scroller holds. The `collectRegionRows` function
4570
+ shadow root and the slotted rows a shadow scroller holds. `measureRegion` and `measureContent`
4571
+ each read a shared clipping ancestor's computed style as many times under twelve rows as under
4572
+ one, counted through `recordStyleReads`, beside the control that a memo per row reads it again
4573
+ for every row. The `collectRegionRows` function
4464
4574
  takes the flat tree through an open shadow root and its slot, an absolute box under a positioned
4465
4575
  ancestor and a fixed box under a transformed one, and leaves out an absolute box and a fixed box
4466
4576
  with their subtrees where no ancestor at or under the region contains them. The `containsFixed`
@@ -4532,13 +4642,22 @@ Each entry names the contracts its file proves. The test names carry the cases.
4532
4642
  contract, and the portfolio's refusals, its disabled gate, and its writes. Creation refuses an
4533
4643
  unregistered variant name; the registry expands across every variant whether or not the run
4534
4644
  writes; a run
4535
- that is not enabled applies nothing, writes nothing, and records nothing, yet refuses an
4645
+ that is not enabled applies nothing and writes nothing, yet refuses an
4536
4646
  unregistered state and a second placement of one state, and accepts two distinct registered states
4537
- with its lists still empty; an enabled run applies
4647
+ into `observed` with `placements` and `paths` still empty; a projected run writes its one state
4648
+ and accepts the rest unwritten; a scoped run writes each state under its scope and keeps placement
4649
+ order across interleaved scopes; creation refuses an unregistered projected state and a scope that
4650
+ is not one path segment; an enabled run applies
4538
4651
  the variant, resizes the viewport, writes a real file through the provider, records it, and hands
4539
4652
  out snapshots rather than its own lists; it refuses an unregistered state and a second placement of
4540
- one state; and a placement handed an element writes a frame that is not the whole page's and leaves
4541
- the staged pane released. `createJournal` takes a step recorded only while it is started, every
4653
+ one state; a placement handed an element writes a frame that is not the whole page's and leaves
4654
+ the staged pane released; `view` of five 400-row bands scrolled to row 600 writes the 844-row
4655
+ viewport ending on yellow beside a placement of the page that writes 2000 rows ending on purple,
4656
+ with the scroll kept; an unrolled portfolio refuses `view` enabled, disabled, and projected away
4657
+ alike and records nothing, while the disabled and projected runs accept `place` for that state;
4658
+ the second of two concurrent `place` calls, and of two concurrent `view` calls, for one state is
4659
+ refused as already placed while the first writes; and a `view` that throws leaves its state free
4660
+ for a later `view` that writes. `createJournal` takes a step recorded only while it is started, every
4542
4661
  console channel forwarded to the recorder that was there, a call's arguments joined into a line,
4543
4662
  an uncaught error and an unhandled rejection recorded and then ignored after the stop, the
4544
4663
  channels handed back by identity with a second stop proven a no-op against a replacement, a restart
@@ -4574,7 +4693,9 @@ Each entry names the contracts its file proves. The test names carry the cases.
4574
4693
  holding the tree as its working directory, and the hosts split rather than branching at
4575
4694
  runtime: on Windows the un-retried `rmSync` baseline is proven to fail first, so the retry is what
4576
4695
  succeeds, and on POSIX the removal is permitted outright. `isRunning` takes the process making the
4577
- call, a child that has exited, and a pid the host refuses without throwing. `waitForSocketClose`
4696
+ call, a child that has exited, a pid the host refuses without throwing, pid `0`, and, where the
4697
+ host publishes each thread's state, a child read while its leader thread has exited and a worker
4698
+ thread still runs, and an unreaped zombie whose every thread has exited. `waitForSocketClose`
4578
4699
  takes an already-closed socket, a peer that ends the connection, a reset waited past to the close
4579
4700
  that follows it, a socket error that is not a reset, a socket left open past the budget, both
4580
4701
  listeners removed after it resolves and after it rejects, an abort before and during the wait, and