@variance-authority/core 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,459 @@
 # @variance-authority/core
 
+## 0.15.0
+
+### Minor 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.
+- 6755276: `variance distill --file <path>` lists each module no case entered under the
+  import that made the test file load it: the topmost import every path from the
+  test file to the module runs through, with nothing behind it that a case
+  entered, often in a module the test used rather than in the test file. A module
+  two imports reach is listed as shared, with the nearest file every path to it
+  runs through; one no static import reaches, such as a dynamic import's, is
+  listed apart. The file graph is read from the checkout only when the reading
+  has a module no case entered. A module the file mocked with a factory was never
+  evaluated, and its import is not walked.
+
+  `@variance-authority/core/relate` exports `dominatorsOf`, each node's immediate
+  dominator from a root. `distillFile` takes an optional `imports` lookup and
+  sets `cause` on each module no case entered; `@variance-authority/distill`
+  exports `LoadCause`.
+- b065364: `::before` and `::after` are read as children of the element they hang from
+
+  Restyling or rewording a `::before` or `::after` box used to repaint the page
+  and move no hash: the rules written for it were matched against the element,
+  failed, and were dropped from both the snapshot and the render document. A
+  generated box now enters the capture as a child node tagged `::before` (first)
+  or `::after` (last), carrying the rules written for it. In a browser it carries
+  its computed style, projected onto the allowlist, and the text its `content`
+  says as a `#text` child; a box whose `content` is `none` or `normal`, or whose
+  `display` is `none`, is not in the tree. Strings are joined and `attr()` reads
+  the element's attribute; a part such as `counter()` or `open-quote` is carried
+  as written.
+
+  Under JSDOM, which computes no generated content, the declared rules answer,
+  picked by the same cascade order normalization uses: a box is in the tree when
+  the winning `content` gives it one and the winning `display` is not `none`, with the rules that style it and no computed style.
+  When that `content` is strings and `attr()`, the box says its words as a
+  `#text` child, as in a browser, so rewording it moves the snapshot. When it
+  holds a `counter()`, a quote, a `var()` or a `url()`, the box has no text and
+  carries `unread` on `RawNode` and `SemanticNode`, naming the parts it could not
+  resolve; `unread` is outside every hash. JSDOM's own parser drops a `content`
+  that is a single `attr()` or `counter()` and nothing else, so no box is read
+  for one.
+
+  This is part of `RULESET_VERSION` `r2`, the same `r2` that keeps the served
+  port out of a render. A subject with a `::before` or `::after` box has a new
+  render document, so after this upgrade its image shows the box and reads
+  `changed`; `variance accept --all` and Playwright's
+  `--update-snapshots=changed` adopt it.
+- 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.
+- 14aefbf: Ask what one test, or one story, checks that the narrower ones inside it do
+  not.
+
+  - `variance ask test-composition --file <test> --name <words>`, and
+    `docs_test_composition`, read one recorded test as the smaller tests whose
+    regions sit inside its own, the larger tests holding it, and the regions no
+    smaller test entered: modules only it enters, and paths through a smaller
+    test's module only it takes.
+  - `variance_composition {subject}` closes with the same reading for a story:
+    the smaller stories inside it, the larger ones holding it, and what no
+    smaller story renders — components only it mounts, and components a smaller
+    story renders another way. The run carries it per subject in the report's
+    structure section; `piecesOf` in `@variance-authority/core/attribute`
+    computes it.
+  - A component mounted by more than half the suite's subjects is structure. A
+    subject that mounts a component many times now counts once, where every
+    mount used to count: a chip story is an example of the chip again when the
+    pages around it mount chips many times over.
+- f1c1b64: A bumped package and a moved manifest are read as the repository files they
+  change, once, before anything else is asked. `beyondReach` in
+  `@variance-authority/core/relate` walks a bump through the install to the first
+  files whose runtime imports load it, and stops there: a test that entered
+  anything further along evaluated that file on the way. A moved manifest becomes
+  every file beside it. `variance select`, `variance reach` and `variance run
+  --since` hand those files on as changed whole, so the suite's `before` and the
+  record answer for them as they do for an edited file.
+
+  `before` now holds files alone. A bump of a package your setup imports runs the
+  whole suite and names the setup file, not the package. `changedBefore` takes the
+  changed files only, and `BeforeReach.packages` is gone.
+
+  The `packages` option of `narrowByJourneys`, `narrowByExecution` and
+  `selectJourneyFile` is removed: pass the files `beyondReach` returns, each with
+  no line ranges.
+- a4f55c1: One walk carries a change to every file that loads it
+
+  `@variance-authority/core/relate` exports `carried`, the walk against the
+  arrows that `dependentsOf`, its narrowed form and test selection's two importer
+  walks now all run. You pass seeds, each with what its change carries — the
+  whole file, or the names that moved — and a step that says what one importer
+  does with what reached it. The walk owns the worklist, enters each file once
+  per name, ends on any cycle, and treats a step with no answer as the whole
+  file. A walk you write over the graph gets the same answers on cycles,
+  self-imports and re-exports as the ones the selector runs, with no loop of your
+  own.
+- bd98c3a: `--shard` in Vitest and Jest is placed by recorded time, and `variance shards` says how many to start
+
+  A Vitest or Jest config wrapped by `withTestSelection` now places the files of
+  `--shard k/n` by the time each took on the last recorded run, rather than
+  leaving the runner to divide them by count. Each shard computes the whole
+  placement from the same record and keeps its own part: files go longest first
+  to the shard with the least time so far, and a file the record has not seen is
+  priced at the median of the ones it has. The run says on stderr which record
+  placed it and what each shard was given:
+
+  ```text
+  variance-authority: shard 1/2 by the times recorded at 8e3b0f0e9028: 1 of 5 files, 9.0 s (shards 400 ms to 9.0 s)
+  ```
+
+  When the times cannot be read, the runner's own split runs instead, and the
+  line says why. A failed read never fails the run. A Jest config that names no
+  `testSequencer` finds Jest's own through Jest, so a layout that does not hoist
+  `@jest/test-sequencer`, as pnpm does not, runs as before. Under
+  `VARIANCE_AUTHORITY_SINCE`, only the files the selection keeps are placed.
+
+  `variance shards --setup <seconds>` prints how many shards a recorded suite is
+  worth, and with `--format json` a `matrix` of `k/n` strings for a CI job to
+  start. Every shard is charged its setup, so a shard is added only when it
+  shortens the wait by more than it spends, and the count stops at the slowest
+  test file, which the answer names with its slowest case. `--budget` asks for
+  the fewest shards that finish within it, `--workers` divides a shard's share
+  among its runner's workers, and `--since` leaves out what the change lets the
+  run skip, so a change that reaches no test answers `0 shards`. `--collected
+  <file>`, the runner's list of test files, counts a test file the record has not
+  seen, priced at the median.
+
+  It always answers, and names what it could not weigh, in `notes` under
+  `--format json`. Without `--setup` the count weighs no setup. A budget no
+  longer than the setup is out of reach at any count, and the answer is the count
+  that finishes soonest, with `why` set to `setup over budget`. `--since` without
+  `--collected` counts only recorded files and never answers fewer than one
+  shard, and `--at-distance` without `--since` counts the whole suite. With
+  nothing recorded it answers one shard until `--unrecorded <n>` names the count
+  to start.
+
+  `@variance-authority/core/shard` is the placement and the count, which
+  `variance run --shard` places stories and routes by too.
+  `@variance-authority/sense` exports `recordedTimes` and `fileCases`, and
+  `@variance-authority/cli` exports `suiteTimes`.
+- af6b022: `before` moves out of `source` and is declared where the suite is. The top-level
+  `before` is what every suite rests on — a CI workflow, a `.nvmrc` — and a
+  suite's own `before`, beside its `kind`, is its runner config and its setup
+  files, each listed, since a config names its setup as a string and a string is
+  not an import. `variance select` now reads both for the suite it reads: each
+  entry is walked down the file graph, and a change to any file it reaches, a
+  `package.json` whose `exports`, `main` or `type` moved over one of those files,
+  or a bump of a package those files import, runs the whole suite and names what
+  moved. A directory in either list is walked from every file under it. `select
+  --execution` reads the same lists for the suite `--suite` names, the only one
+  declared, or every declared suite when none is named; beside a snapshot
+  `--execution`, `--suite` is refused, since both name the record. A manifest move
+  is read when the diff leaves every lockfile alone. A
+  config below the repository root inherits the root's `before`, as it inherits
+  its suites. A suite that declares nothing has nothing before its reach, and
+  `select` says so.
+  `variance run --since` reads the top-level list as it read `source.before`.
+
+  `source.before` is refused: move it to the top level.
+- 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.
+- 8187fb1: `didYouMean` and `nearest` are exported from `@variance-authority/core` and no
+  longer from `@variance-authority/mcp/tools`. Import them from
+  `@variance-authority/core`. A mistyped command or flag is refused, with the
+  nearest right one, without loading the MCP server's tools.
+- ca7813e: `intersectionArea` is exported from `@variance-authority/core/format`
+
+  The area two `Rect`s share, zero when they only touch or do not meet. It sits
+  beside `Rect`, where the attribution already used it, so the review service can
+  ask whether two builds changed the same place.
+
+### Patch Changes
+
+- 85e1a40: `wait-for-fonts` gives up after 15 seconds and names the font
+
+  A web font whose request never answered kept `document.fonts.ready` pending, and
+  the capture waited forever. `wait-for-fonts` now waits at most 15 seconds, the
+  same bound as `wait-for-images`, then fails naming every font still loading:
+  its family, and the `src` that requested it when the stylesheet declaring it is
+  same-origin. A face declared in a cross-origin stylesheet is named by family
+  alone, because the page cannot read that sheet's rules.
+- cb8a52f: A source index another release wrote is no longer reported as damaged
+
+  After an upgrade, the first command that read the source index said it was
+  damaged and read only up to its first bad segment, and in CI it refused with
+  the same words. The segments were whole: an earlier release had written them in
+  another format version. Now the reader names both versions, for example that
+  the index was written in format version 15 and this release reads version 18.
+  On a workstation it rebuilds the index and says so, and `variance index` prints
+  `source index rebuilt over one written in format version 15`. In CI the refusal
+  names both versions and asks you to run `variance index` with this release
+  before the command that reads it. `ask orient --files` over such an index says
+  which version wrote it and that `variance index` rebuilds it.
+- 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".
+
 ## 0.14.0
 
 Lockstep release — nothing in this package changed. Every `@variance-authority/*` package shares one version.

package/README.md

@@ -158,12 +158,14 @@ specifier exports only the capture artifact.
 | `core/relate` | what rests on what: a file graph in adjacency form, the components a change reaches, and a closure digest over each one |
 | `core/segment` | columnar bytes: named columns, interned strings, and the validation a decode performs before it believes a file |
 | `core/share` | leaving those bytes where another machine finds them, as the latest of a mainline or a branch |
+| `core/shard` | which shard runs which group of a suite, by recorded time, and how many shards it is worth: `shardCount` weighs each shard's `setup` against the time it saves, within a `budget` or up to a `max`, with `workers` running a shard's groups at once |
 
 Five of those are the order an answer travels through: `format`, `rules`,
-`compare`, `attribute`, `judge`. `plan` and `relate` are asked before anything
+`compare`, `attribute`, `judge`. `plan` and `relate` run before anything
 is captured — one decides which baselines a run can use, the other which
 subjects are worth reading. `segment` and `share` are how a derived answer
-is written down and handed to another machine.
+is written down and handed to another machine. `shard` splits one run across
+several.
 
 ## The four words the output uses
 
@@ -172,9 +174,9 @@ structure and declared style; `chromium` adds layout and pixels. A profile that
 cannot measure a box cannot decide pixels either.
 
 An **identity** is the content hash that addresses a result, derived from the
-whole plan — ruleset version, viewport, policy, interventions. Two runs are
-comparable only when their identities match, so changing any part of the plan
-changes which baselines the run can see.
+whole plan — ruleset version, viewport, policy, interventions. Two runs share
+a result only when their identities match, so changing any part of the plan
+changes the address its result is stored under.
 
 A **band** is the kind of change a delta is, and which band a delta lands in
 decides how loudly it is reported. Change frequency and change importance run
@@ -255,6 +257,7 @@ observation profiles differ.
 | `fingerprintOfMask` | `grid` controls the shape sample and `coverage` the minimum occupied share |
 | `compareLocales` / ignore validation | `slack` permits a declared locale distance; `sites` supplies resolved ignore locations and `now` evaluates expiry |
 | `buildDocket` / dependency reach | `sampleSize` limits review examples; `through` selects graph edge kinds, `avoid` names nodes a walk never covers, and `shadows` lists per file the modules its run never loads, so `affectedBy` leaves out a file every trail to which crosses one of its own shadows; `depends` adds the install — which package rests on which — so a dependency bump is a seed like any other and affects only the files that import it; `uses` names what each import binds and each re-export republishes, and `moved` lists per seed the exports its change changed, so `affectedBy` covers only the files that import one of them |
+| `carried` | the walk under every reach question, with your own step per importer: `through` and `avoid` as above; `mask` and `via` take arrays you already hold, so a caller that walks again writes into the same marks and trail; `seedsHold` set to `false` lets a seed take back what a cycle carries to it, for a file that reads its own names through an importer |
 | `beforeReach` | `sensed` names the directories the scan already answers for, and the descent from a declared entry point stops at the first file under one of them rather than dragging the repository's own source in behind the harness |
 | `sharedClosures` | `floor` drops a shared subtree below a node count |
 | `lexiconOf` | `examples`, `declaredIn` and `regions` supply what the instances cannot: which components a subject is the example of, the files declaring each component, and the regions its journey covered |
@@ -263,8 +266,8 @@ observation profiles differ.
 
 ## Which input changed
 
-`compare` says what changed. `judge` says whether anyone should mind. Between
-them, `partingOf` says which input changed.
+`compare` finds what changed. `judge` decides whether anyone should mind.
+Between them, `partingOf` finds which input changed.
 
 Given two snapshots with holdings — the inputs a collector recorded at each
 component boundary — it walks the boundaries for the shallowest one whose inputs
@@ -293,7 +296,7 @@ run that recorded no component provenance gets `unread` instead.
 What a suite is made of is a fact about a commit rather than about a run.
 `core/segment` writes such a thing as columns — equal facts encode to equal
 bytes, which is what lets a transport skip an upload — and `core/share` keeps
-the latest of those bytes on a line. A checkout asks *what is mainline now*,
+the latest of those bytes on a line. A checkout looks up *what is mainline now*,
 and a line answers that: one mainline or one branch, holding the latest entry
 of each kind — the run report, one record per suite — and the images those
 entries name, by digest.
@@ -329,7 +332,7 @@ appended to. `headers` is sent on every request, which is where a bucket's
 `Authorization` or a deployment's token goes. `method` is the verb a write uses
 — `PUT` for a bucket, `POST` for a deployment that routes on it. `timeoutMs`
 is how long one request may take, reading its body included, before the store
-is `unreachable` with a message that says it timed out; it is 60 000 when you
+is `unreachable` with a message naming the timeout; it is 60 000 when you
 leave it out. A presigned base needs only the endpoint. `memoryLineCell()`
 holds a line in this process, for tests and for a run that shares with itself.
 
@@ -343,7 +346,7 @@ A publish replaces only the entries it carries, so suites from different jobs
 land on one line. On a mainline, a held entry whose commit descends from yours
 stays: that is an older run finishing last. A held entry in a newer format stays
 on any line. A line reports why it missed — `absent`, `newer`, `refused`,
-`unreachable` or `unreadable` — because each asks you for a different action.
+`unreachable` or `unreadable` — because each needs a different action from you.
 Everything a line holds can be derived again, so a miss costs you the
 derivation. [Sharing an evaluation](https://variance-authority.dev/docs/sharing)
 is the operator's side of it.

package/dist/attribute/component-hash.d.ts

@@ -103,8 +103,9 @@ export declare function causesBetween(before: readonly ComponentHash[], after: r
  * A missing `geometry` on either side is the profile saying it has no layout
  * engine, and is not a difference. Treating absent as a change would report
  * every component as having moved the moment a jsdom baseline met a Chromium
- * run — which the environment key already refuses as `incomparable`, so this
- * would be a second, wronger answer to a question already settled.
+ * run — which the environment key already names as the cause of that
+ * comparison, so this would be a second, wronger answer to a question already
+ * settled.
  */
 export declare function movedBands(before: BandDigests, after: BandDigests): readonly Band[];
 /**

package/dist/attribute/component-hash.js

@@ -198,8 +198,9 @@ function ownContentMoved(before, after) {
  * A missing `geometry` on either side is the profile saying it has no layout
  * engine, and is not a difference. Treating absent as a change would report
  * every component as having moved the moment a jsdom baseline met a Chromium
- * run — which the environment key already refuses as `incomparable`, so this
- * would be a second, wronger answer to a question already settled.
+ * run — which the environment key already names as the cause of that
+ * comparison, so this would be a second, wronger answer to a question already
+ * settled.
  */
 export function movedBands(before, after) {
     const moved = new Set();