@variance-authority/storybook-collector 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,346 @@
 # @variance-authority/storybook-collector
 
+## 0.15.0
+
+### Minor Changes
+
+- 1a0b845: A subject is read with nothing hovered, nothing focused, motion reduced and `Date` fixed
+
+  Every layout and raster baseline made before this release is compared under a
+  moved recipe once; a semantic baseline, read in jsdom, does not move. The
+  default recipes gained tricks, so the stabilization digest every reading records
+  has changed, and each subject names that recipe as the cause of whatever it
+  reports. Review the changes and adopt them with `variance accept --all`, as for
+  any recipe change.
+
+  The standard collection recipe now also holds:
+
+  - `no-hover`: the pointer is moved to `(-1, -1)`, off the page, once per page
+    before it loads. On the `variance` fixture's page it is moved again before
+    every observation, a frame each, and not put back: a menu a script opened on
+    hover is closed for your test's next step.
+  - `no-focus`: whatever holds focus is blurred before the subject is read,
+    including an element inside a shadow root. On a page your test or agent goes
+    on using, focus goes back to that element once the reading and any screenshot
+    of it are taken, so a test types where it left off. The blur still ran the
+    page's blur handlers, and what they did, such as a validate-on-blur error,
+    stays.
+  - `reduced-motion`: the browser reports `prefers-reduced-motion: reduce`, which
+    stops the script animations of a page that honours it, and the reading
+    declares the same preference among the conditions its `@media` rules are
+    resolved against. A `prefers-reduced-motion` condition you declare through
+    `createHarness`'s `features` wins, and the browser is asked for that value;
+    a declared `no-preference` is not recorded as `reduced-motion`. Rules under
+    `@media (prefers-reduced-motion: no-preference)` are not read by default;
+    leave `reduced-motion` out to read them.
+  - `freeze-clock`: `Date` reads one instant. A script added before the page's
+    own replaces `new Date()`, `Date()` and `Date.now()`, and gives the same
+    instant to `Intl.DateTimeFormat`'s `format()` and `formatToParts()` called
+    without a date. Timers, animation frames and `performance.now()` are the
+    browser's own, so a page that settles on a timer still settles. No Playwright
+    clock is installed, so `page.clock` stays yours, and a clock your test
+    installs replaces the fixed `Date`; the reading still records `freeze-clock`,
+    so leave it out of the list when your test owns the clock. `Temporal.Now` and
+    `Date` inside a worker are not fixed. The default instant is in the past, and
+    the browser's cookie store keeps real time: a cookie your page's script sets
+    with an expiry counted from `Date.now()` is already expired and is not
+    stored, so a dismissed consent banner can come back after the next
+    navigation. Set `varianceNow` or `now` near today, or leave `freeze-clock`
+    out.
+
+  The render and layout recipes gain `no-focus` alone, because a painted document
+  still honours a collected `autofocus`. The other three have nothing to act on
+  there: the date the page printed is already text in the document, and its
+  `@media` rules were resolved when it was read. A `<script>` inside a subject
+  root is carried into the render document and runs there under the real clock.
+  Every document is painted under the render recipe, so a reading taken without
+  `no-focus` is still painted blurred.
+
+  The instant defaults to `DEFAULT_NOW`, `2024-06-15T12:00:00.000Z`, exported
+  from `@variance-authority/core/format`. `routeCollector` and
+  `storybookCollector` take a `now` option to choose another. It must be an ISO
+  8601 instant with its zone; anything else is refused before a browser opens.
+  An instant other than the default is spelled in the clock's id,
+  `freeze-clock@<instant>`, so it is part of the environment key, and a baseline taken at one instant is compared
+  with a run at another with the moved instant named as the cause.
+
+  To read a subject hovered, focused, animated or at the real time, pass your own
+  `stabilize` list without that trick: `DEFAULT_STABILIZE`, the ids of the
+  default recipe, filtered, as in
+  `DEFAULT_STABILIZE.filter((id) => id !== 'freeze-clock')`. It is exported from
+  `@variance-authority/core/format`, `@variance-authority/route-collector`,
+  `@variance-authority/storybook-collector` and
+  `@variance-authority/playwright-test`. `storybookCollector` and `observe` in
+  `@variance-authority/playwright-test` now take `stabilize`, as `routeCollector`
+  already did.
+
+  A trick needs a browser driver to apply it, and is recorded only where one did.
+  The collectors apply all four. So does the `variance` fixture in
+  `@variance-authority/playwright-test`: it sets `reduced-motion` and
+  `freeze-clock` on the `page` it hands your test, before the test body runs, and
+  takes the pointer off the page and releases focus before every observation,
+  giving focus back after it. Two new fixture options, `varianceStabilize` and
+  `varianceNow`, choose what it sets and the instant, and are set with
+  `test.use`; `varianceDriven` holds the ids it set. A fixed `Date` stops code
+  that times itself with `Date.now()`: a debounce or a throttle, such as lodash's
+  `debounce`, sees no time pass and never fires, so a test that types into a
+  debounced search box can stop getting results after this upgrade. A loop that
+  waits for `Date.now()` to pass a mark hangs the page, an animation timed by
+  `Date`, such as jQuery's `animate`, never calls its `complete`, and a client
+  that checks a token's `nbf` or `iat` against `Date.now()` can refuse a token
+  issued today. None of these failures names the clock. Leave
+  `freeze-clock` out for such a test, and for one that sets `page.clock` itself:
+
+  ```ts
+  import { DEFAULT_STABILIZE } from '@variance-authority/playwright-test';
+
+  test.use({ varianceStabilize: DEFAULT_STABILIZE.filter((id) => id !== 'freeze-clock') });
+  ```
+
+  On a page the fixture never handed your test,
+  such as one opened from your own browser context, call the new
+  `driveBeforeTest(page)` before `page.goto()` to set the same two; `observe` and
+  `createVariance` there apply `no-hover` and `no-focus`.
+  `@variance-authority/vitest-browser` reads from inside your page and has no
+  driver; `@variance-authority/presentation` reads through the Playwright `Page`
+  you hand it, a test's or an agent's live browser, and does not drive it. Both
+  apply `no-focus` only, giving focus back once the reading is taken. A trick left out is absent from the
+  reading's ids and digest, as a trick a tier cannot reach already is.
+  `stabilizeForObservation` in `@variance-authority/dom` takes `driven`, the ids
+  your driver applied, and returns `refocus()`, which gives focus back to the
+  element the reading released. `stabilizeAsRequested` takes the recipe by id, as
+  a page agent receives it. `createHarness` in `@variance-authority/playwright`
+  takes a `stabilize` recipe to drive its page before the first navigation, and
+  reports the ids it applied as `driven`. `createObservedHarness` opens one with
+  `observeNetwork` started before its first navigation, as both collectors do.
+
+  `createPlaywrightRenderer` no longer couples `no-focus` to `waitForFonts`:
+  `waitForFonts: false` turns off the waits alone.
+
+  `@variance-authority/core/format` exports `DEFAULT_STABILIZE`, `DEFAULT_NOW`,
+  `driveBeforeLoad` and `driveBeforeRead`, which apply the driver tricks to a
+  Playwright `Page`, `forDriver`, which drops the ones a host did not apply,
+  `featuresOf`, which declares the motion preference a recipe drove, and
+  `recipeToDrive`, which resolves a `stabilize` list and checks `now` before a
+  browser opens.
+- d432339: A page reads its clock in UTC and formats for en-US, not for the host
+
+  The harness the route and Storybook collectors open, and the pages the renderer
+  paints, took their timezone and locale from the machine. A date the page
+  formatted read one way on a laptop in Sydney and another on a runner in
+  Virginia, from one build, and the two compared against one baseline as
+  `changed`.
+
+  Both are pinned: `timezoneId` to `UTC` and `locale` to `en-US`. Declare either
+  in `variance.config.json` (`"timezoneId": "Europe/Berlin"`, `"locale":
+  "de-DE"`) and the collectors and the renderer pin that instead; an unknown
+  timezone or a malformed language tag is refused by its field.
+  `createHarness` and `createPlaywrightRenderer` take the same two options.
+  `@variance-authority/core/format` exports their type, `PageRegion`, and
+  `@variance-authority/playwright` exports `pinnedRegion`, which fills in `UTC`
+  and `en-US` for a field left out.
+
+  Both are part of the environment key, and the renderer's pair is part of
+  `RenderIdentity.rasterization`. A capture read in another timezone or language
+  is another environment, and an image painted in one is compared with a
+  baseline painted in another, with `rasterization` named as the cause of
+  whatever moved.
+
+  `@variance-authority/playwright-test` paints each test in the timezone and
+  locale its page runs in: whatever the Playwright project or `test.use` sets.
+  When neither sets a `timezoneId`, `varianceFixtures` opens the page in `UTC`
+  rather than the host's, so a laptop and a runner in UTC read it under one key;
+  Playwright Test already opens it in `en-US` when nothing sets a `locale`. That
+  reaches every test of a suite extended with `varianceFixtures`, including tests
+  that never call `variance`, so a test that asserts a date formatted in your
+  machine's timezone reads it in `UTC` after this upgrade; set `timezoneId` in
+  `use` to keep your own. A page
+  you hand to `createVariance` is read and painted in whatever its own context
+  opened it in, which is the host's timezone when that context set none: open the
+  context with `timezoneId: 'UTC'` to match. `varianceRenderer` is now a test fixture, chosen
+  by the page, and `varianceRenderers` is the worker's set of renderers, one per
+  timezone and locale; a project that overrode `varianceRenderer` at worker scope
+  overrides it at test scope instead.
+
+  **Every image painted by the Playwright renderer is compared under a moved
+  recipe once after this upgrade**, because its recipe now carries the timezone
+  and locale. Each subject names `rasterization` as the cause of what it reports,
+  and one whose pixels moved is `changed`:
+
+  - With `variance run`: the run exits `1` for each `changed` subject. Review
+    them in `variance report --format html` and adopt them with
+    `variance accept --all`. A rerun reports `unchanged`.
+  - With `@variance-authority/playwright-test`: the suite fails each `changed`
+    test, and `--update-snapshots=changed` adopts them.
+  - With `@variance-authority/vitest-browser`: `vitest --update` adopts them, as
+    `variance accept --all` does.
+
+  `@variance-authority/vitest-browser` reads no `variance.config.json` and takes no
+  timezone or locale, so it paints in `UTC` and `en-US` whatever its tab ran in,
+  and neither it nor `@variance-authority/unit-test` writes a timezone or locale
+  to the environment key.
+- 3e6a370: A run's cases travel in its record
+
+  The case index, the cases a run replaced and the run that replaced them are
+  sections of `coverage.bin`, no longer a `coverage.bin.cases.bin` beside it. The
+  one file is landed, layered, seeded, repinned, sharded and shared by the same
+  rules and under the same lock as the coverage it was recorded with, so the two
+  always answer for the same runs. A share, a seed or a fetch carries the index
+  and drops the replaced cases and the run that names them, which belong to the
+  machine that ran.
+
+  A record that carries cases is format 10, and a reader that knows only coverage
+  refuses it rather than misreading it. A record without cases keeps format 9. A
+  `coverage.bin.cases.bin` left from an earlier run is not read; the next run
+  writes its cases into the record.
+
+  The `executionFile` option is removed from `withTestSelection`, the Jest and
+  rstest seams, `startRecording`, the Playwright reporter and the Storybook
+  collector, along with the JSON it could write. `decodeExecutionIndex`,
+  `readExecutionIndex`, `variance covering --against`, `variance review` and
+  `distill --execution` read the index out of a record; JSON stays readable as
+  the spelling a foreign tool supplies. `landCaseIndexes` is replaced by
+  `landCases`, which returns the sections for the record you write, and
+  `lastCaseRunOf` reads the run they name. `caseLayerFiles` and
+  `executionIndexBytes`, which named and read the file beside the record, are
+  removed. `CaseSections`, `caseSectionsAt`, `caseSectionsOf`, `caseIndexOf`,
+  `recordedCases`, `withCaseSections`, `keepsCases` and `sharedRecord` read and
+  write the sections.
+- 754d04c: The port a build is served on is no part of a render
+
+  The route and Storybook collectors serve a build on a free port, and that port
+  reached three identities. An asset the page loaded was keyed by its absolute
+  URL, a `url()` in a computed style was the absolute URL the engine resolved,
+  and the document digest read both. One build served twice therefore read as two
+  environment keys and two documents: each run missed the render cache, painted
+  again, and read its document as changed against its own baseline.
+
+  An asset the page's own origin serves is keyed by its path, and the page's
+  origin is dropped from a `url()` before it is hashed. An asset another origin
+  serves keeps its absolute URL. A capture carries the page's `baseUrl` so core
+  knows which origin is the page's, and the renderer resolves a path-keyed asset
+  against the document's `baseUrl`. `documentDigest` reads the page's own base
+  and resources as paths, so one build served on two ports addresses one render
+  and the render cache hits; the document keeps them absolute for the renderer,
+  and a resource another origin serves stays absolute in the digest too.
+
+  A `@variance-authority/unit-test` capture keys its assets the same way, so a
+  `@variance-authority/vitest-browser` observation, which captures through it on
+  the port the runner had free, keeps the port out of its environment key.
+  `readCapture` reads back a capture whose asset is keyed by path, resolving the
+  key against the document's `baseUrl` as the renderer does; `assetUrl` in
+  `@variance-authority/core/format` is that one resolution.
+
+  **The document of every page served over `http` moves once after this
+  upgrade.** `documentDigest` now reads a document's base and resources without
+  the page's origin, so the digest of every document served over `http` or
+  `https` changes: every route, every story, every Vitest browser page, and every
+  Playwright page opened by URL. A moved document misses the render cache once,
+  and its image is still compared with the baseline: a page whose pixels did not
+  move reads `unchanged`, and one whose pixels did reads `changed`, which
+  `variance accept --all` and Playwright's `--update-snapshots=changed` adopt.
+  `RULESET_VERSION` moves from `r1` to `r2`. The ruleset is part of a snapshot's
+  environment key, not of the render recipe, so no image names it as a moved
+  identity; a snapshot diffed against one recorded under `r1` names the ruleset as its
+  environment root.
+
+### Patch Changes
+
+- 8dbc834: The components a module declares are read from its code. A declaration written
+  in a block comment, a JSDoc example or a template literal no longer names a
+  component, so a commented-out `function Retired()` no longer makes its file
+  the one that declares `Retired`. A name is declared by a statement of the
+  module itself: a function, class or binding inside a function body belongs to
+  that function and no longer counts. An `export async function Page()`, an
+  abstract class, a generator, a second name in `const A = 1, B = 2`, and a name
+  that starts with a non-ASCII capital or carries a `$` are now declared too.
+
+  `variance run`, `variance collect`, the Storybook collector and the route
+  collector resolve a component to its `file:line` from the same reading, through
+  `indexDeclarations`, which `sense` now exports. What that changes in the index
+  they build from `source.dirs`:
+
+  - The line is the first line of the declaring statement. A decorated class
+    sits at its first decorator, or at its `export` when the decorator is written
+    above the `export`, and a second name in a multi-line `const` at the line of
+    the `const`.
+  - `.d.ts` files, and test, spec and story files your own `exclude` lets
+    through, declare nothing.
+  - A file the parser cannot read declares nothing, where the text scan found
+    the components in it. That covers a Flow-annotated `.js` file, and a `.vue`,
+    `.svelte` or `.mdx` file you add to a collector's `extensions`, which is
+    parsed as TSX and fails. The index built from `source.dirs` or a collector's
+    `source` does not say so: the file's components are missing, and nothing
+    names the file. Only `sense`'s source index, for a file it records, names the
+    parse error in that file's record.
+  - Building the index needs `sense`'s native addon, which ships for macOS on
+    arm64, Linux on x64 and arm64 with glibc, and Windows on x64. On any other
+    machine, including an Intel Mac, an Alpine image and Windows on arm64, a
+    configured `source.dirs` fails at its first file and names why the addon did
+    not load, where the text scan ran anywhere. The route collector depends on
+    `sense` for it.
+
+  `indexSource` is removed from `@variance-authority/core/attribute`. Build a
+  `SourceIndex` with `indexDeclarations` from `@variance-authority/sense`, or
+  write one as plain data: a map from component name to `{ file, line, via }`.
+  `SourceRef['via']` loses `'declared'`, which nothing produced, and
+  `readCapture` in `@variance-authority/unit-test` refuses a capture whose source
+  index carries it.
+
+  The source index format moves to version 18, so an index written before this
+  release is rebuilt once instead of keeping the names it read from comments.
+- 1eed290: A form filled in after mount is painted and compared filled in
+
+  Text a play function or a test typed into an `<input>` or `<textarea>`, the
+  option it chose in a `<select>` and the box it ticked now reach the render
+  document and the snapshot. Before, the document painted the form as the server
+  sent it and the snapshot did not move for typed text or a chosen option. A
+  password field's value is carried as one `•` per character, and a file input's
+  value is not carried. A form nobody filled in reads exactly as before.
+
+  This is part of `RULESET_VERSION` `r2`. A subject whose form was filled in
+  after the server sent it has a new render document, so after this upgrade its
+  image shows the form filled in and reads `changed` against a baseline painted
+  empty; `variance accept --all` adopts it. A Playwright test painted its form
+  filled in before this change, so it does not move there.
+- ef496ad: READMEs name what the program does
+
+  The package READMEs, and the `@variance-authority/vantage` and
+  `@variance-authority/playwright-test` descriptions, no longer write a test, a
+  record or a run as something that says, asks or knows. Each sentence names what
+  the program does: a command prints, a record holds a field, a test runs or
+  covers. Where a value is filled in from configuration or a default rather than
+  recorded, the README says so. Four renamed headings change their anchors:
+  `help`'s "Where the declaration is undocumented", `playwright`'s "Where a
+  component is declared, read from the engine", `storybook`'s "What a pass sends
+  the preview" and `sense`'s "Correct what a file's text declares it imports".
+- 4799688: The checkout says what the probes meant: no build writes module records
+
+  A probe names the file it was placed on and the digest of that text,
+  `path@digest`. When a run is folded, each module the journals name is cut again
+  from the file in the checkout. A file whose text still matches is read on its
+  own regions; a file that has moved on since the build reads as one whose reach
+  is not known, which selects every test that entered it; a file that is gone
+  counts the same way. Nothing is written beside the build, and nothing under the
+  cache's `test-selection/<key>/<label>/` is read.
+
+  Breaking:
+
+  - `testSelectionProbes()` takes no `cacheRoot`. Its `label` names the journey
+    head and nothing else.
+  - `recordExecution()` takes no `label` and no `heads`.
+  - The Jest journeys options (`withJourneyCoverage`) take no `heads`.
+  - `jestStore` is removed from `@variance-authority/sense/jest`.
+  - `instrumentModule(code, file)` takes no options: call it first, on the file as
+    it is on disk.
+  - A journal names a module by `path@digest`. A driver that writes its own
+    journal builds the id with `moduleId(path, code)` from
+    `@variance-authority/sense/journal`.
+
+## 0.14.0
+
+Lockstep release — nothing in this package changed. Every `@variance-authority/*` package shares one version.
+
 ## 0.13.0
 
 Lockstep release — nothing in this package changed. Every `@variance-authority/*` package shares one version.

package/README.md

@@ -34,7 +34,7 @@ This is the Storybook adapter, not the `variance` binary. The binary lives in
 | Module format | ESM only. Every `@variance-authority/*` package sets `"type": "module"`; `require()` will not load them. |
 | Browser | Chromium, installed through Playwright. The binaries do not arrive with an `npm install`. |
 | Storybook | Exercised against Storybook 10 with `@storybook/react-vite`. Index versions `3`, `4` and `5` are read, and the story root is looked for at `#storybook-root` (Storybook 7 and later) and then `#root` (before it). Storybook 8.3 and later emit `storyFinished`, which this package waits for; it falls back to `storyRendered` when the event is absent. |
-| Builder | Collection reads `index.json` and drives the preview channel, so it does not know or care whether Vite or Webpack 5 built the Storybook. Two optional precision features are Vite plugins with no Webpack equivalent, and are named as such where they appear below: `@variance-authority/jsx-source` and the `tests` option. |
+| Builder | Collection reads `index.json` and drives the preview channel, so it works the same whether Vite or Webpack 5 built the Storybook. Two optional precision features are Vite plugins with no Webpack equivalent, and are named as such where they appear below: `@variance-authority/jsx-source` and the `tests` option. |
 | React | Required for component attribution, the `wiring` band and the Suspense wait. The reading is of the expando `react-dom` writes on host nodes — `__reactFiber$` on React 17 and later, `__reactInternalInstance$` on React 16 — so there is no React version to match and none is imported. The suite runs against React 19. |
 
 A Storybook whose renderer is not React still collects: documents, pixels,
@@ -64,7 +64,7 @@ the build.
 
 ### 2. Write the collector module
 
-The collector is the module that tells the run how to find and read your
+The collector is the module that defines how the run finds and reads your
 stories. Create it anywhere in your project and default-export the factory.
 
 ```js
@@ -146,8 +146,9 @@ full form is:
 npx variance accept [--config <path>] <subject>... | --all | --shape <fingerprint>[,...] [--message-file <path> [--message <text>]]
 ```
 
-Keep `--all` for the first run and for deliberate re-baselines; it cannot tell a
-story nobody looked at from one that changed. After setup, name subject ids:
+Keep `--all` for the first run and for deliberate re-baselines; it does not
+separate a story nobody looked at from one that changed. After setup, name
+subject ids:
 
 ```bash
 npx variance accept --config variance.config.json story:checkout--empty story:checkout--one-item
@@ -207,6 +208,8 @@ Everything below is passed to `storybookCollector(...)` in the module from step
 | `source` | Reports should resolve component names to `file:line`. | Omitted; component names remain available. An empty or mistyped scan is refused. |
 | `baseUrl` | Storybook is already running, e.g. `http://localhost:6006`. | Omitted; the directory containing `subjects.index` is served on loopback for the run. |
 | `headless` | You need to watch collection while debugging. | `true`. |
+| `stabilize` | A story is about its hover, focus, motion or the current date, or your preview has its own determinism strategy. | The standard collection recipe, which also takes the pointer off the page, releases focus, asks for reduced motion and fixes `Date`; `[]` records an untouched story. A list replaces the recipe: start from the exported `DEFAULT_STABILIZE` and filter out what you want read, as in `DEFAULT_STABILIZE.filter((id) => id !== 'no-hover')`. |
+| `now` | Your stories print a date and you want one other than the default. | `2024-06-15T12:00:00.000Z`. An ISO 8601 instant with its zone; anything else is refused before a browser opens. |
 | `network` | Asset bytes at stable URLs must participate in render identity. | `true`; set `false` only when asset URLs are already content-addressed. |
 | `hashAssets` | Your asset URLs already contain their own content hash. | `true`. Read only while `network` is on, so GIF freezing and blanking survive it — this, not `network: false`, is the setting for a content-addressed build. |
 | `wiring` | Your preview's renderer is not React. | `true`. Reads props, context, hook cells and keys into a band of its own; turning it off changes no stored digest. |
@@ -356,7 +359,7 @@ export default {
   framework: { name: '@storybook/react-vite', options: {} },
   viteFinal: async (config) => ({
     ...config,
-    plugins: [...(config.plugins ?? []), testSelectionProbes({ label: 'storybook' })],
+    plugins: [...(config.plugins ?? []), testSelectionProbes()],
   }),
 };
 ```
@@ -367,19 +370,21 @@ import { storybookCollector } from '@variance-authority/storybook-collector';
 
 export default storybookCollector({
   source: { dirs: ['src'] },
-  tests: { label: 'storybook' },
+  tests: true,
 });
 ```
 
-`tests` accepts `true` or an options object: `label` must match the one the
-preview's `testSelectionProbes()` was given, and `cacheRoot` and `coverageFile`
-override the repository-keyed cache paths for the block records and the coverage
-index. `suite` names the suite this run is, when the root `variance.config.json`
+`tests` accepts `true` or an options object: `cacheRoot` and `coverageFile`
+override the repository-keyed cache paths for the coverage layers and the
+coverage index. The preview's probes report each module's file and a digest of
+the text they were placed on, and the run cuts that file again from your
+checkout, so the preview's build writes nothing the run has to find. `suite` names the suite this run is, when the root `variance.config.json`
 declares its suites under `suites`; it is required once any suite is declared,
-and cannot be combined with `coverageFile`. `root` is the directory Storybook ran in, the cwd by default: story paths
-and a relative `coverageFile` or `executionFile` are read from it, and every
-path the run records is relative to the repository that contains it.
-Without a collector in the page, the run says so on stderr and records nothing.
+and cannot be combined with `coverageFile`. `root` is the directory Storybook
+ran in, the cwd by default: story paths and a relative `coverageFile` are read
+from it, and every path the run records is relative to the repository that
+contains it. Without a collector in the page, the run prints that on stderr and
+records nothing.
 
 `mode` is the probe recipe, and it has to be the one the preview was built
 under: a snapshot names the recipe its ordinals were cut by, and a merge
@@ -387,17 +392,17 @@ discards a layer cut by another one, so a preview probing under `entries` and a
 run folding under `presence` would each wipe the other. `preconditions` names
 files whose contents are a precondition of every story's observation — a
 `preview.js` that decides what renders belongs there, because a change to it
-invalidates every reading and no crossing will ever say so. `heads` and
-`commit` stamp the snapshot with the branch tips this recording stands on and
-the commit it was taken at, which is what lets a later run tell a stale layer
-from a current one.
+invalidates every reading and no crossing will ever record it. `commit`
+stamps the snapshot with the commit it was taken at, the checkout's `HEAD` by
+default, which is what lets a later run separate a stale layer from a current
+one.
 
 A story is its own owner in the recorded index — Storybook is an execution
 surface this tool drives one subject at a time — and a story that did not render
 still contributes its crossings while never justifying a later skip.
 
 Every run also writes the execution index: one row per story per region,
-beside the coverage index, or wherever `executionFile` points. That is the file
+inside the coverage index. That is the file
 `variance covering` and `@variance-authority/distill` read to answer *which
 stories walk this branch*.
 
@@ -431,8 +436,9 @@ a diff touches.
   URL already identifies the bytes.
 - **The browser is missing:** run `npx playwright install chromium`, then
   `npx variance doctor` again.
-- **A rerun reports `incomparable`:** the approved image was stored under a
-  different identity than this machine produces. `npx variance doctor` lists the
+- **A rerun reports every story `changed`, a moved identity first:** the
+  approved image was stored under a different identity than this machine
+  produces. `npx variance doctor` lists the
   identities the baseline root stores.
 
 ## Boundaries

package/dist/contract.d.ts

@@ -1,5 +1,5 @@
 import type { CallSiteResolver, SourceIndex } from '@variance-authority/core/attribute';
-import type { Diagnostic, RenderDocument, SemanticSnapshot, SubjectRef, Viewport } from '@variance-authority/core/format';
+import type { Diagnostic, PageRegion, RenderDocument, SemanticSnapshot, SubjectRef, Viewport } from '@variance-authority/core/format';
 /**
  * The contract a collector satisfies, restated here rather than imported.
  *
@@ -10,8 +10,11 @@ import type { Diagnostic, RenderDocument, SemanticSnapshot, SubjectRef, Viewport
  * collector in its own tests, so a drift between them fails a build rather than
  * a run.
  */
-/** The subset of a run's configuration this collector reads. */
-export interface CollectorConfig {
+/**
+ * The subset of a run's configuration this collector reads. A region field it
+ * leaves out is pinned to `UTC` or `en-US`, never the host's.
+ */
+export interface CollectorConfig extends PageRegion {
     readonly viewport: Viewport;
     readonly fonts?: readonly string[];
     /**
@@ -102,9 +105,9 @@ export type Collected = {
      * Stabilization tricks applied to the page before this subject was read.
      *
      * Reported so a run can say what it did to somebody else's page. The
-     * digest of the same list is in the environment key, which is what makes a
-     * differently-stabilized baseline `incomparable`; this is the half a
-     * person reads.
+     * digest of the same list is in the environment key, which is what names a
+     * differently-stabilized baseline as the cause of a change; this is the
+     * half a person reads.
      */
     readonly stabilization?: readonly string[];
     /**

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"","sourcesContent":["import type { CallSiteResolver, SourceIndex } from '@variance-authority/core/attribute';\nimport type {\n  Diagnostic,\n  RenderDocument,\n  SemanticSnapshot,\n  SubjectRef,\n  Viewport,\n} from '@variance-authority/core/format';\n\n/**\n * The contract a collector satisfies, restated here rather than imported.\n *\n * The CLI declares the same shapes and this package does not depend on it — a\n * surface package pulling in the binary would put a config parser, a docket and\n * six commands into an adopter's dependency tree to describe four values\n * (ADR-0024). What keeps the two copies honest is that the CLI imports *this*\n * collector in its own tests, so a drift between them fails a build rather than\n * a run.\n */\n\n/** The subset of a run's configuration this collector reads. */\nexport interface CollectorConfig {\n  readonly viewport: Viewport;\n  readonly fonts?: readonly string[];\n  /**\n   * Subtrees this project excludes, from `config.ignore` (spec 0024).\n   *\n   * Only the two fields a page needs: a rule id to record the mark under, and a\n   * selector to find it with. Everything else about a rule — its reason, its\n   * expiry, the bands it narrows to — is decided after collection, where a clock\n   * and the whole run's diffs are available and a browser is not.\n   */\n  readonly ignore?: readonly {\n    readonly id: string;\n    readonly select?: string;\n    /**\n     * Subjects the rule names. Read here to decide what to send, and never sent.\n     *\n     * A page can resolve a selector and cannot know which subject it is one of,\n     * so scoping has to happen on this side of the boundary. Without it a rule\n     * written for one route marks its element in every subject that renders the\n     * same shared layout, and a real regression inside that element is absorbed\n     * everywhere — an ignore silencing more than it says, which is the one thing\n     * the mechanism must not do.\n     */\n    readonly subjects?: readonly string[];\n\n    /** Tags the subject must carry. Read here to decide what to send, never sent. */\n    readonly tags?: readonly string[];\n  }[];\n\n  /**\n   * Images to serve as nothing, from `config.blank`.\n   *\n   * Handed to the driver rather than to the page, because it is enforced on the\n   * wire — before a byte is decoded, and therefore before the layout it would\n   * have participated in exists. Not scoped by subject, and it cannot be: a\n   * request carries no idea which subject will end up using it, which is the\n   * same reason the asset map is per page rather than per subject.\n   */\n  readonly blank?: readonly {\n    readonly id: string;\n    readonly url?: string;\n    readonly minPixels?: number;\n    readonly maxPixels?: number;\n  }[];\n\n  /**\n   * The subjects section of the config, as the operator wrote it.\n   *\n   * `index` is optional because it belongs to `subjects.kind: \"storybook\"`, and\n   * a config naming any other kind still reaches this collector — the kind is\n   * chosen in the config and the collector is chosen in the config, and nothing\n   * makes the operator pick a matching pair. Typed as always present, the first\n   * thing to read it hands `undefined` to `node:path` and the adopter gets a\n   * TypeError about an argument instead of a sentence naming the wrong word.\n   */\n  readonly subjects: { readonly index?: string };\n}\n\nexport interface PlannedSubject {\n  readonly subject: SubjectRef;\n  readonly viewport?: Viewport;\n\n  /**\n   * What the subject declares itself to be, from the artifact that produced it.\n   *\n   * Storybook's built index carries `tags` and does not carry a story's\n   * `parameters`, so a tag is the one per-story declaration the index can plan\n   * from — and it is the right one anyway: what a subject *is* belongs in its\n   * own name, next to it, rather than in a central file repeating every id.\n   * How a story is *read* — excluded, resized, read at several widths — comes\n   * from its parameters, which `withParameters` lays over this plan from the\n   * running preview.\n   *\n   * Selection lives here; definition lives in the config. A tag is a word a\n   * story wears, and what that word *means* is the operator's to write down\n   * once, where a typo can be refused by name.\n   */\n  readonly tags?: readonly string[];\n}\n\nexport interface Plan {\n  readonly subjects: readonly PlannedSubject[];\n  readonly notObserved: readonly unknown[];\n  readonly warnings: readonly string[];\n}\n\nexport type Collected =\n  | {\n      readonly ok: true;\n      readonly document: RenderDocument;\n      readonly snapshot?: SemanticSnapshot;\n      readonly source?: SourceIndex;\n\n      /**\n       * Stabilization tricks applied to the page before this subject was read.\n       *\n       * Reported so a run can say what it did to somebody else's page. The\n       * digest of the same list is in the environment key, which is what makes a\n       * differently-stabilized baseline `incomparable`; this is the half a\n       * person reads.\n       */\n      readonly stabilization?: readonly string[];\n\n      /**\n       * What the adapter noticed about the *way* this subject was produced.\n       *\n       * Not about the picture — the document and the snapshot carry that — but\n       * about the reading: a story Storybook finished by reporting it failed, a\n       * preview that had to be reloaded to show it, a render that never\n       * finished. Each of those leaves a real image that a run can compare, and\n       * each of them changes what a person should conclude from a green verdict,\n       * so they travel with the subject rather than being dropped at the seam.\n       */\n      readonly diagnostics?: readonly Diagnostic[];\n    }\n  | { readonly ok: false; readonly because: string };\n\nexport interface CollectorContext {\n  readonly config: CollectorConfig;\n  /** Computed by the run from the story index. Returned unchanged. */\n  readonly plan?: Plan;\n}\n\nexport interface Collector {\n  plan(): Promise<Plan>;\n  collect(subject: PlannedSubject): Promise<Collected>;\n\n  /**\n   * The frames a snapshot carries, spent on demand.\n   *\n   * Present when the collector drives a browser, because resolving a frame means\n   * fetching the module it names and the page is the only place that request is\n   * already correct. Absent otherwise, and absence is not a degradation: it means\n   * either that nothing captured frames, or that the run has no live page to\n   * fetch through — and both are a report without call sites rather than a\n   * report that is wrong.\n   *\n   * Handed to `locateSites` with the few nodes a region or a finding names. The\n   * resolver is per collector rather than per subject: the cache is what makes\n   * this bounded, and a suite's subjects share their modules.\n   */\n  readonly callSites?: CallSiteResolver;\n\n  /**\n   * Collect this subject again, in a world nothing else has touched.\n   *\n   * The saving this whole tool is built on is that the world is *not* rebuilt\n   * between subjects (ADR-0009): one browser, one page, one Storybook, for the\n   * length of a run. What it buys is the possibility that story B renders\n   * differently because story A ran first — and a comparison cannot tell that\n   * apart from a regression, because both arrive as \"the pixels moved\".\n   *\n   * One clean collection settles it. If the difference is gone with nothing else\n   * in the world, the baseline was right and the session moved this subject, and\n   * the run reports `order-dependent` rather than asking anybody to accept it.\n   *\n   * Optional in the contract the CLI declares, because a collector holding a\n   * single page open has no clean world to offer and the run says so rather than\n   * reading silence as \"nothing leaked\". This collector implements it: a\n   * Storybook preview can be opened twice, and the second one costs a browser\n   * launch — which is why the run only spends it on subjects it already called\n   * `changed`, up to `alone.limit`.\n   */\n  collectAlone?(subject: PlannedSubject): Promise<Collected>;\n\n  /**\n   * Another standing world from the same recipe and the same server, for a\n   * second worker. Optional in the contract the CLI declares; absent, a run\n   * configured with `workers` collects in one world and says so.\n   */\n  openWorker?(): Promise<Collector>;\n\n  /**\n   * `costs` is what the run timed for each story, first collection to\n   * decision, by subject id; the execution record carries it as each story's\n   * duration.\n   */\n  close(costs?: ReadonlyMap<string, number>): Promise<void>;\n}\n"]}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"","sourcesContent":["import type { CallSiteResolver, SourceIndex } from '@variance-authority/core/attribute';\nimport type {\n  Diagnostic,\n  PageRegion,\n  RenderDocument,\n  SemanticSnapshot,\n  SubjectRef,\n  Viewport,\n} from '@variance-authority/core/format';\n\n/**\n * The contract a collector satisfies, restated here rather than imported.\n *\n * The CLI declares the same shapes and this package does not depend on it — a\n * surface package pulling in the binary would put a config parser, a docket and\n * six commands into an adopter's dependency tree to describe four values\n * (ADR-0024). What keeps the two copies honest is that the CLI imports *this*\n * collector in its own tests, so a drift between them fails a build rather than\n * a run.\n */\n\n/**\n * The subset of a run's configuration this collector reads. A region field it\n * leaves out is pinned to `UTC` or `en-US`, never the host's.\n */\nexport interface CollectorConfig extends PageRegion {\n  readonly viewport: Viewport;\n  readonly fonts?: readonly string[];\n  /**\n   * Subtrees this project excludes, from `config.ignore` (spec 0024).\n   *\n   * Only the two fields a page needs: a rule id to record the mark under, and a\n   * selector to find it with. Everything else about a rule — its reason, its\n   * expiry, the bands it narrows to — is decided after collection, where a clock\n   * and the whole run's diffs are available and a browser is not.\n   */\n  readonly ignore?: readonly {\n    readonly id: string;\n    readonly select?: string;\n    /**\n     * Subjects the rule names. Read here to decide what to send, and never sent.\n     *\n     * A page can resolve a selector and cannot know which subject it is one of,\n     * so scoping has to happen on this side of the boundary. Without it a rule\n     * written for one route marks its element in every subject that renders the\n     * same shared layout, and a real regression inside that element is absorbed\n     * everywhere — an ignore silencing more than it says, which is the one thing\n     * the mechanism must not do.\n     */\n    readonly subjects?: readonly string[];\n\n    /** Tags the subject must carry. Read here to decide what to send, never sent. */\n    readonly tags?: readonly string[];\n  }[];\n\n  /**\n   * Images to serve as nothing, from `config.blank`.\n   *\n   * Handed to the driver rather than to the page, because it is enforced on the\n   * wire — before a byte is decoded, and therefore before the layout it would\n   * have participated in exists. Not scoped by subject, and it cannot be: a\n   * request carries no idea which subject will end up using it, which is the\n   * same reason the asset map is per page rather than per subject.\n   */\n  readonly blank?: readonly {\n    readonly id: string;\n    readonly url?: string;\n    readonly minPixels?: number;\n    readonly maxPixels?: number;\n  }[];\n\n  /**\n   * The subjects section of the config, as the operator wrote it.\n   *\n   * `index` is optional because it belongs to `subjects.kind: \"storybook\"`, and\n   * a config naming any other kind still reaches this collector — the kind is\n   * chosen in the config and the collector is chosen in the config, and nothing\n   * makes the operator pick a matching pair. Typed as always present, the first\n   * thing to read it hands `undefined` to `node:path` and the adopter gets a\n   * TypeError about an argument instead of a sentence naming the wrong word.\n   */\n  readonly subjects: { readonly index?: string };\n}\n\nexport interface PlannedSubject {\n  readonly subject: SubjectRef;\n  readonly viewport?: Viewport;\n\n  /**\n   * What the subject declares itself to be, from the artifact that produced it.\n   *\n   * Storybook's built index carries `tags` and does not carry a story's\n   * `parameters`, so a tag is the one per-story declaration the index can plan\n   * from — and it is the right one anyway: what a subject *is* belongs in its\n   * own name, next to it, rather than in a central file repeating every id.\n   * How a story is *read* — excluded, resized, read at several widths — comes\n   * from its parameters, which `withParameters` lays over this plan from the\n   * running preview.\n   *\n   * Selection lives here; definition lives in the config. A tag is a word a\n   * story wears, and what that word *means* is the operator's to write down\n   * once, where a typo can be refused by name.\n   */\n  readonly tags?: readonly string[];\n}\n\nexport interface Plan {\n  readonly subjects: readonly PlannedSubject[];\n  readonly notObserved: readonly unknown[];\n  readonly warnings: readonly string[];\n}\n\nexport type Collected =\n  | {\n      readonly ok: true;\n      readonly document: RenderDocument;\n      readonly snapshot?: SemanticSnapshot;\n      readonly source?: SourceIndex;\n\n      /**\n       * Stabilization tricks applied to the page before this subject was read.\n       *\n       * Reported so a run can say what it did to somebody else's page. The\n       * digest of the same list is in the environment key, which is what names a\n       * differently-stabilized baseline as the cause of a change; this is the\n       * half a person reads.\n       */\n      readonly stabilization?: readonly string[];\n\n      /**\n       * What the adapter noticed about the *way* this subject was produced.\n       *\n       * Not about the picture — the document and the snapshot carry that — but\n       * about the reading: a story Storybook finished by reporting it failed, a\n       * preview that had to be reloaded to show it, a render that never\n       * finished. Each of those leaves a real image that a run can compare, and\n       * each of them changes what a person should conclude from a green verdict,\n       * so they travel with the subject rather than being dropped at the seam.\n       */\n      readonly diagnostics?: readonly Diagnostic[];\n    }\n  | { readonly ok: false; readonly because: string };\n\nexport interface CollectorContext {\n  readonly config: CollectorConfig;\n  /** Computed by the run from the story index. Returned unchanged. */\n  readonly plan?: Plan;\n}\n\nexport interface Collector {\n  plan(): Promise<Plan>;\n  collect(subject: PlannedSubject): Promise<Collected>;\n\n  /**\n   * The frames a snapshot carries, spent on demand.\n   *\n   * Present when the collector drives a browser, because resolving a frame means\n   * fetching the module it names and the page is the only place that request is\n   * already correct. Absent otherwise, and absence is not a degradation: it means\n   * either that nothing captured frames, or that the run has no live page to\n   * fetch through — and both are a report without call sites rather than a\n   * report that is wrong.\n   *\n   * Handed to `locateSites` with the few nodes a region or a finding names. The\n   * resolver is per collector rather than per subject: the cache is what makes\n   * this bounded, and a suite's subjects share their modules.\n   */\n  readonly callSites?: CallSiteResolver;\n\n  /**\n   * Collect this subject again, in a world nothing else has touched.\n   *\n   * The saving this whole tool is built on is that the world is *not* rebuilt\n   * between subjects (ADR-0009): one browser, one page, one Storybook, for the\n   * length of a run. What it buys is the possibility that story B renders\n   * differently because story A ran first — and a comparison cannot tell that\n   * apart from a regression, because both arrive as \"the pixels moved\".\n   *\n   * One clean collection settles it. If the difference is gone with nothing else\n   * in the world, the baseline was right and the session moved this subject, and\n   * the run reports `order-dependent` rather than asking anybody to accept it.\n   *\n   * Optional in the contract the CLI declares, because a collector holding a\n   * single page open has no clean world to offer and the run says so rather than\n   * reading silence as \"nothing leaked\". This collector implements it: a\n   * Storybook preview can be opened twice, and the second one costs a browser\n   * launch — which is why the run only spends it on subjects it already called\n   * `changed`, up to `alone.limit`.\n   */\n  collectAlone?(subject: PlannedSubject): Promise<Collected>;\n\n  /**\n   * Another standing world from the same recipe and the same server, for a\n   * second worker. Optional in the contract the CLI declares; absent, a run\n   * configured with `workers` collects in one world and says so.\n   */\n  openWorker?(): Promise<Collector>;\n\n  /**\n   * `costs` is what the run timed for each story, first collection to\n   * decision, by subject id; the execution record carries it as each story's\n   * duration.\n   */\n  close(costs?: ReadonlyMap<string, number>): Promise<void>;\n}\n"]}

package/dist/execution.d.ts

@@ -21,23 +21,12 @@ export interface StoryExecutionOptions {
      * read from here, because it is relative to the directory Storybook ran in.
      */
     readonly root?: string;
-    /** Matches the `label` the build's `testSelectionProbes()` used. Defaults to `build`. */
-    readonly label?: string;
-    /** Where the build wrote its block records. Defaults to the repository's cache. */
+    /** Where the coverage layers live. Defaults to the repository's cache. */
     readonly cacheRoot?: string;
     /** Coverage index. Defaults to the repository-keyed cache the runner seams share. */
     readonly coverageFile?: string;
     /** The suite this run is, as the root `variance.config.json` declares it under `suites`. */
     readonly suite?: string;
-    /**
-     * Where the execution index — which individual story entered which region —
-     * goes. Defaults beside the snapshot, as the Vitest seam's does.
-     *
-     * A story is the case this costs nothing to name: the driver shows one at a
-     * time, so the per-case grain a unit runner needs a custom runner for is
-     * already here.
-     */
-    readonly executionFile?: string;
     /**
      * The probe recipe the preview was built with, matching
      * `testSelectionProbes()`'s `mode`. `presence` when absent, as it is there.
@@ -55,14 +44,6 @@ export interface StoryExecutionOptions {
      * the ones no story declares and nothing enters.
      */
     readonly preconditions?: readonly string[];
-    /**
-     * Other builds this same run drove, by the label each instrumented under.
-     *
-     * A preview and the application behind it are two builds of overlapping
-     * source, and a story that reaches both is one observation. Their stores
-     * join this recording rather than getting one of their own.
-     */
-    readonly heads?: readonly string[];
     /**
      * Where this recording stands. Defaults to the checkout's `HEAD`, which is
      * the answer in every case except a caller that already knows better.

package/dist/execution.js

@@ -94,7 +94,6 @@ export async function createStoryRecorder(index, options) {
                 record = await recordExecution({
                     root,
                     subjects: zip(observed, timedOnce(observed.map((one) => one.owner), costs)),
-                    ...(options.label === undefined ? {} : { label: options.label }),
                     ...(options.cacheRoot === undefined ? {} : { cacheRoot: options.cacheRoot }),
                     // Against `root`, as the runner seams resolve them, never the checkout.
                     ...(options.coverageFile === undefined
@@ -105,16 +104,10 @@ export async function createStoryRecorder(index, options) {
                     ...(options.preconditions === undefined
                         ? {}
                         : { preconditions: options.preconditions }),
-                    ...(options.heads === undefined || options.heads.length === 0
-                        ? {}
-                        : { heads: options.heads }),
                     ...(options.commit === undefined ? {} : { commit: options.commit }),
                     ...(cases.length === 0
                         ? {}
                         : { cases: zip(cases.map((one) => one.observed), timedOnce(cases.map((one) => one.subject), costs)) }),
-                    ...(options.executionFile === undefined
-                        ? {}
-                        : { executionFile: resolve(ran, options.executionFile) }),
                 });
             }
             catch (error) {