@variance-authority/core 0.15.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,429 @@
 # @variance-authority/core
 
+## 0.17.1
+
+Lockstep release — nothing in this package changed. Every `@variance-authority/*` package shares one version.
+
+## 0.17.0
+
+Lockstep release — nothing in this package changed. Every `@variance-authority/*` package shares one version.
+
+## 0.16.0
+
+### Minor Changes
+
+- 40a19b9: A committed baseline is named for its story or test
+
+  Under `directory` and `lfs`, a baseline was written to
+  `<root>/<identity digest>/<percent-encoded subject id>.png`, so a pull request
+  that accepted one listed a 32-character hex directory nobody could check against
+  the change, and each machine that accepted wrote its own copy. `baselines.path`
+  is now a template rendered from what the subject is: `{dir}` and `{file}` (the
+  file that declares it), `{title}`, `{name}`, `{id}`, `{project}` (the
+  Playwright project's name, in the fixture's `varianceBaselinePath` only) and
+  `{engine}` (the engine's family). The default, `{title}/{name}-{engine}`,
+  writes `Ui/Button/Primary-chromium.png`;
+  `{dir}/__baselines__/{file}/{name}-{engine}` with `root: "."` writes
+  `src/ui/Button/__baselines__/Button.stories.tsx/Primary-chromium.png` beside the
+  code. A label is spelled `Primary__dark-chromium.png`.
+
+  The machine that painted a baseline is read from the record beside it. One file
+  holds each subject per engine family, the last accept writes it, and a run on
+  another platform, scale factor or engine version compares against it, reading
+  unchanged or changed as the pixels say, with the moved field named as the cause.
+  A laptop and CI that take turns accepting rewrite the record each time; set
+  `baselines.records` to keep the records out of version control. The tribunal's
+  bucket store answers the same way: a lookup reads the last accept on the
+  engine family, where it used to prefer this machine's own row.
+
+  Two subjects that render one path, compared case-folded, stop the run with an
+  error naming both subjects and the template. Nothing is renumbered. The record
+  names the subject it was accepted for, so a shard, a Playwright worker or a
+  later run that renders the same path for another subject stops too. Two
+  Playwright projects that differ only in scale factor, colour scheme or viewport
+  render one path; the error names both projects and `{project}`. A record left by
+  a project the config no longer runs is a renamed project's, and the first run
+  under the new name takes it over.
+
+  The Vitest plugin reads a test's `describe` path from the runner, so a title
+  that contains ` > ` stays one directory under `{title}`.
+
+  **Breaking:** `baselines.layout` is removed, and a config that sets it is
+  refused with an error naming `path`. Baselines under the identity directories
+  are still read: the subject is compared against them, unchanged or changed as
+  the pixels say, with the move from the old path to the new one given as a cause,
+  and the next accept writes the template's path and deletes the old pair, so the
+  pull request shows a rename. An accept deletes only a pair this machine's
+  identity or engine line painted; another machine's stays until that machine
+  accepts. `BaselineKey` carries `file`, `title`, `name` and
+  `project` in place of `path`; the Playwright fixture, the Vitest plugin and
+  Storybook's index supply them, and `varianceBaselinePath` and `baselinePath`
+  set the template for a suite run without the CLI.
+
+  The git-LFS store's `.gitattributes` pattern and the action's commit-back
+  pathspecs are the template's glob, so a collocated baseline is tracked and
+  committed where it is written. An `lfs` config whose root is `.` and whose
+  template has no directory of its own is refused, because its glob would track
+  every hyphenated image in the repository; give the template a directory such
+  as `__baselines__`, give the baselines a root of their own, or set
+  `baselines.pattern`. A `directory` config at root `.` with such a template is
+  refused for the same reason: the action would commit every hyphenated image
+  back. An existing LFS root gets the template's pattern as a new
+  `.gitattributes` line the next time a run opens it; commit it with the baselines.
+- 09f60c8: A reach walks type-only imports unless you name the runtime edges
+
+  `dependentsOf`, `dependenciesOf`, `affectedBy` and `carried` in
+  `@variance-authority/core/relate` now walk every edge kind, `type` included,
+  when you pass no `through`. A type-only import is still a dependency: a changed
+  type can break the file that imports it, and the walk said nothing about that
+  file. Test selection asks what a run loads, so every selection walk in Sense and
+  the CLI passes `RUNTIME_EDGES`, and what it selects does not change.
+
+  If you called one of these and relied on `type` edges being left out, pass
+  `{ through: RUNTIME_EDGES }`.
+- 0b6af81: A changed region is joined against the baseline's nodes as well as this render's
+
+  A change that replaces an element paints over the old element's box and the new
+  one's, and `attributeRegions` read only one snapshot. On todomvc's broken toggle,
+  71% of the changed region is inside the checkbox that left and 88.75% inside the
+  div that arrived. Neither reaches the 0.9 containment, so the region named the
+  row around both.
+
+  `AttributionOptions.before` is now required: the snapshot of the revision the
+  pixels are compared against, or `undefined`. Each node is joined against the
+  area its own box and the box of the node the differ's matcher pairs it with in
+  `before` cover together: the two places, not the rectangle that holds both.
+  A box that left is placed by where it was in its own image, whose corner is the
+  new `AttributionOptions.beforeOrigin`: by default the before snapshot's root, so
+  a subject the page moved between two clipped shots joins where its pixels are.
+  A call that states `origin` with a `before` snapshot and no `beforeOrigin`
+  throws, since a corner guessed from the other image is right only when the page
+  did not move.
+
+  A baseline keeps that snapshot. `Raster.snapshot` is a `PackedSnapshot`, the
+  tree gzipped and in base64, written by the Playwright fixture, its promotion,
+  the Vitest browser provider and the CLI's image sidecars. `packSnapshot` and
+  `unpackSnapshot` are exported from `@variance-authority/observe`. Every store
+  carries it as text: `sidecarFrom` keeps it, `variance push` forwards it, and
+  tribunal stores it in new `baselines.snapshot` and
+  `build_subjects.candidate_snapshot` columns (schema 21, migration
+  `0019_baseline-snapshot.sql`) and promotes it on approval. On
+  `cases/storybook-case` it adds 3.2–5.4 KB to each sidecar.
+
+  A baseline without a snapshot says so. When a changed verdict has regions and
+  its baseline kept no snapshot, or one that will not unpack, the reason ends
+  *the baseline records no snapshot of its nodes, so regions were joined against
+  this render's boxes alone: an accepting run records one on a revision where
+  this subject is unchanged*. An accepting run — `--update-snapshots`, Vitest's
+  `--update`, `variance accept` — now re-stamps an unchanged baseline that kept no
+  snapshot, as it re-stamps one painted under another identity, and the
+  observation marks it `signals.snapshot: 'unrecorded'`; `restamps` in
+  `@variance-authority/core/judge` is the one rule all three ask. Every other
+  verdict the mark is on ends *the baseline records no snapshot of its nodes, and
+  an accepting run records this one*. Two images
+  compared directly get the same clause, naming the before image, without the
+  remedy, and are never marked.
+
+  A subject whose document has not moved settles on its digest and builds no
+  observation to mark, so `settle` now renders a pictured baseline that kept no
+  snapshot when this run collected one, with the reason *the baseline records no
+  snapshot of its nodes, so this run renders it for an accepting run to record
+  one*. A suite of baselines accepted before this release renders them on every
+  run until an accepting run re-stamps them. Tribunal records one on ingest
+  instead: a pushed candidate's snapshot is written onto a baseline that has an
+  image and kept none, when it was painted from the same document under the same
+  identity, and never over one it kept, so such a subject renders once. The
+  snapshot's runtime fields (`provenance` and its `createdBy`, `wiring`, `holding`,
+  `styleProvenance`, `styleTokens`, `ignoredBy`) are then the recording run's: the
+  first push, from a build on any branch, that drew that document, as they are the
+  accepting run's on a re-stamp. `Described.keepsSnapshot`
+  is the new required field it reads:
+  the durable, LFS and tribunal stores derive it from the sidecar with
+  `keepsSnapshot` from `@variance-authority/core/format`, and the remote store
+  refuses a description without it. A packed snapshot now opens with a `v1:`
+  header naming its format version, `PACKED_SNAPSHOT_HEADER`, and a snapshot
+  without it counts as not kept. `unpackSnapshot` reads one as not recorded
+  unless every node in it is one, with `isSemanticSnapshot`, new in
+  `@variance-authority/core/format` beside `isRenderDocument` and
+  `isSubjectRef`: the checks `@variance-authority/unit-test` already made of a
+  capture file's snapshot, document and subject, which it now asks. Tribunal serves API 6, which describes a
+  baseline with `keepsSnapshot`; `variance push` against an older deployment names
+  the refused descriptions when the project's `remote` baselines are stored there,
+  and the remote store's refusal names tribunal before API 6 and a
+  `serveRasterStore` from an earlier `@variance-authority/remote`: upgrade the
+  server, tribunal or your own, before the client. `settle` takes this run's snapshot as a
+  fifth argument. `variance accept` and the MCP changelog call these subjects
+  *unchanged and re-stamped* rather than re-stamped under this run's identity,
+  which was untrue of them. The render cache no longer hands on a snapshot an
+  entry kept.
+- 18c70d3: A run collects in parallel by default, and the report says where each subject's time went
+
+  Without `workers` in the config, a run collected in one browser world, so a
+  route suite read its pages one after another on any machine. It now collects in
+  half the machine's logical cores, at least one and never more worlds than there
+  are files: two on a 4-vCPU CI runner, eight on a 16-core laptop. A `concurrency`
+  you set holds it lower, since every world keeps a page and a subject in flight.
+  A `workers` you set still wins over both. Set `workers: 1` for a server under
+  test that cannot take concurrent pages. A collector with no `openWorker` still
+  collects in one world, and the run warns about it only when you set `workers`. Verdicts and the order
+  of observations do not depend on the count, and the report's new `workers` field
+  records it. `variance collect` takes the same width.
+
+  A changed subject read in a second world is now run alone like one read in the
+  first. A worker opens no clean world of its own, so the run asked the worker and
+  reported "not re-run alone: collector has no `collectAlone`"; it now asks the
+  collector that can open one.
+
+  The `alone.limit` budget now goes to the first subjects to change in the order
+  the run takes them. It went to whichever changed subjects reached it first, so
+  with more changed subjects than the limit, which ones carried `again` and
+  `alone` evidence depended on the number of worlds and on timing.
+
+  Each observation in the report also carries `steps` beside `costMs`: every
+  phase the subject went through, in the order it ran, with its wall time. The
+  collector's phases are named `collect.*` (`collect.navigate`,
+  `collect.wait-for-fonts`, `collect.capture`), the run's own are `compose`,
+  `inspect`, `settle`, `baseline`, `cache.get`, `cache.put`, `decode`, `compare`,
+  `write`, `again.collect` and `alone.collect`, and a painted subject adds the
+  renderer's under `render.*`. The report's `steps` sums each phase over the
+  subjects that ran it and counts them. A phase a subject skipped is absent, not
+  zero. Timings are part of no digest, so images, records and baselines do not
+  move when only timing does.
+
+  `settleRecipe`, `stabilizeForObservation`, `compareRasters` and the raster
+  `Renderer.render` take an optional step clock and report the steps they ran on
+  it. The route page agent and `readRoute` always return the steps they took.
+  `stepClock`, `timeOn` and `totalsOf` are exported from
+  `@variance-authority/core/format`.
+
+  A run that is not sharded now reads the mainline's subject costs at every
+  width, as a sharded run always did, and takes its slowest files first. One
+  world takes its subjects in the same order as several, so the budget above
+  reaches the same subjects.
+
+  `concurrency` is split evenly across the worlds and rounded up, at least one
+  per world, so by default the raster tier is as wide as the number of worlds.
+
+  The frame above a subject carries its classes in code-unit order. Storybook
+  swaps its layout class on a page it reuses, so their order said which story the
+  page showed before, and a run in parallel lanes gave the same story a different
+  document, and a render-cache miss, with the same pixels.
+- 9b95dc1: A shard takes whole files in every runner, and is balanced by file count without times
+
+  Under `--shard k/n`, a Playwright config wrapped by `withTestSelection` now
+  places each spec file whole in one shard, by the time it took on the last
+  recorded run, as Vitest and Jest shards are placed. Playwright's own split,
+  which under `fullyParallel` divides a file's tests between shards, does not run.
+  The reporter places the shard in `preprocess`, after `--project`, `--grep` and
+  `.only`, and prints one line on stderr:
+  `variance-authority: shard 1/2 by file count: 2 of 3 files; no times at …`.
+  A file several projects run, or `repeatEach` repeats, goes with all its copies
+  to one shard; setup and teardown projects are not placed, and a project with no
+  file in the shard is left out whole. Playwright runs a setup project in every
+  shard that needs it, so combining the shards' records refuses its files as run
+  by two shards. `PWTEST_SHARD_WEIGHTS` is ignored for placement, though
+  Playwright still validates it.
+
+  This needs Playwright 1.62 or newer. `withTestSelection` refuses a run that asks
+  for a shard, by `--shard` or by `shard` in the configuration, when the
+  configuration is evaluated, before any test starts: on an older Playwright with
+  `variance-authority: refusing shard k/n: Playwright <version> would split it
+  test by test, …; placing whole files needs Playwright 1.62 or newer`, and when
+  a `--reporter` on the command line replaces the configuration's reporters
+  without naming `@variance-authority/playwright-test/reporter`, by that
+  specifier or by a path that resolves to it. The version is the one the
+  configuration's directory resolves, from `-c`/`--config` or the working
+  directory. A configuration that names the reporter without `withTestSelection`
+  is not refused. A run with no shard runs as before.
+
+  When the record has no times, or none for the files collected, a Vitest, Jest
+  or Playwright shard prices every file the same and places them by the same
+  rule, so the shards are balanced by file count and none is left empty while
+  there are as many files as shards. The line reads
+  `shard k/n by file count: <m> of <n> files; <why>`, in place of
+  `split by the runner, by count: <why>`. A file the runner hands in more than
+  once, for each project that runs it, is placed once at its recorded time, which
+  already sums every project, with every copy in one shard.
+
+  `place` in `@variance-authority/core/shard` is where that rule lives: with
+  nothing recorded, every group weighs one and is placed longest first on the
+  least-loaded shard like a timed one, ties broken by key in code-unit order and
+  then by the lowest shard. Its `by` reads `count` rather than `checksum`, and
+  its `cost` and `load` are always present, one per group when placed by count.
+  `variance run --shard` and `variance collect --shard` place stories and routes
+  by the same rule, and a subject another shard owns reads
+  `assigned to shard k/n by count, …`.
+
+  A Jest or Vitest configuration wrapped by `withTestSelection` and evaluated
+  under `--shard` gets `passWithNoTests: true` unless it sets `passWithNoTests`
+  itself, so a shard left no file, because there are fewer files than shards,
+  passes as it does under Playwright. Vitest 4 refused such a run before any file
+  was placed. An unsharded run that finds no file still fails.
+
+  `shardOf(files, shard, times)`, `landingTimes(record, options)` and
+  `shardArgument(argv)`, which reads the `--shard k/n` a command line asks for, are exported
+  from `@variance-authority/sense/test-selection`, for a seam that places a shard
+  by the same rule.
+
+  A Vitest, Jest or Playwright shard that cannot read the record its times come
+  from now fails before any test runs, with
+  `variance-authority: the times this shard is placed by could not be read, …`
+  and the reason: a share that did not answer or answered with what does not
+  read, a record that is there and does not decode, or a CLI that throws as it
+  loads. It used to place by file count, beside shards that may have read the
+  times. A record that is not there, a share that holds none or is not
+  configured, and a CLI that is not installed still place by count. An unsharded
+  run reads no times and runs as before. `variance shards` fails the same way.
+
+  **Breaking:**
+
+  - A Vitest or Jest shard with no times is placed by file count, in code-unit
+    order of path, not by your sequencer's `shard`. Your sequencer still sorts
+    each shard.
+  - A Playwright run below 1.62 that asks for a shard is refused. Upgrade
+    Playwright, or run without `--shard`.
+  - A sharded Playwright run whose `--reporter` leaves out
+    `@variance-authority/playwright-test/reporter` is refused. Name it in
+    `--reporter` too.
+  - `variance run --shard` and `variance collect --shard` with no recorded costs
+    place each file by count, not by a checksum of the file and the shard. The
+    shards are balanced, but adding a file can move others to another shard.
+    A collection part's `assignment`, and the `assignment` in the provenance of
+    the suite index merged from it, read `count` where they read `checksum`. An
+    index that reads `checksum` still opens. `variance collect merge` refuses
+    sharded parts an earlier version cut by checksum; collect every shard again.
+  - A sharded run whose share does not answer fails rather than placing by
+    file count. Run the job again, or hand every shard the record fetched once.
+- 402ce9f: A story's parameters are read when the story is reached, so no story file is imported before its story comes up
+
+  Your Storybook run used to read every story's `parameters.variance` before the
+  first story, through the preview's `extract()`. That imported every story file
+  up front: on a large Storybook you paid for the whole build before seeing one
+  story, and each file's first story then timed its import as 0 in `collect`.
+
+  The run now plans from `index.json` alone. When it reaches a story, it asks the
+  preview for that story's merged parameters, which imports only that story's
+  file, the import showing the story would have made anyway. That import is
+  charged to the story's `collect`, so the first story of each file carries what
+  its file costs. A story that excludes itself is still skipped and listed in the
+  report with its reason, and a story whose parameters cannot be read is read at
+  your run's `viewport` with a warning naming it. A preview too old to read one
+  story's parameters says so once per run, not once per story.
+
+  A story that declares `widths` is still read as `<story id>@<width>` at each
+  width, with its own baseline, and all its widths are read on the same page in
+  one visit: nothing is opened, booted or loaded again for a second width. A
+  run that does not read such a story, because `--subjects`, `--since` or a shard
+  left it out, because its visit failed, or because its parameters could not be read, still counts its width baselines as
+  planned rather than naming them as baselines your plan no longer holds. A
+  story that excludes itself when it is reached holds no subject of the run, so
+  every baseline it left, under its own id and at each width, is named. A
+  shard prices the story at the sum of the widths its last visit read.
+
+  If you write a collector, `collect` may now return a `Visit` instead of a
+  `Collected`: every subject the visit to the planned one produced, each with its own
+  result, each id the planned id or the planned id at a width (`<id>@<width>`),
+  and any warnings the visit raised. A visit that could not learn every subject
+  it realizes, such as a story read without its parameters, says `incomplete: true`.
+  A visit that produced no subject is
+  reported as a failed one, and so is a visit that produced any other id. The run and `variance collect` report each subject
+  at the position the plan gave the planned subject, and evidence parts record
+  the planned id as `of`; a merge refuses a part whose subject is neither. A
+  `--subjects` glob that names one width, such as `*@375`, now reaches the story
+  it comes from, and only a width suffix extends a story id: `button--primary`
+  no longer reaches `button--primary-large`.
+
+  `@variance-authority/core/format` exports `atWidth`, which writes a subject's
+  id and name at a width, and `widenedFrom`, which reads the planned id back
+  from a width id, and `realizes`, which says whether a visit to one id may
+  produce another.
+
+  `readParameters(page)` is now `readParameters(page, storyId)` and returns one
+  story's parameters; the up-front read of every story is gone.
+- f18c00c: The differ pairs the one element its author replaced, and says what it became
+
+  When, under one matched parent, exactly one element left and exactly one
+  arrived, and the same component's `createdBy` wrote both, `matchTrees` pairs
+  them. The pair is compared like any other and leads with a new `tag-changed`
+  delta, in the geometry band and counted as structural, followed by whatever else
+  differs: role, name, state, attributes, styles and box. Before, the same change
+  was a `node-removed` and a `node-added`. Two or more replaced by one author under
+  one parent stay unpaired, because either could be either, and so do two that
+  each carry an alias or a role and name of their own: every `<Button>` is created
+  by `Button`, and a Save button replaced by an Export link is two elements.
+
+  `tag-changed` is reported on every pair across two tags, so a pair that a
+  declared alias or a shared role and name joined — a `<button>` and a
+  `<div role="button">` with one name — now says its tag changed, where before it
+  reported nothing for it.
+
+  A `style-changed` or `token-changed` delta on a pair across two tags is banded
+  `geometry`, with the `tag-changed` it follows, rather than `token`: the style is
+  the new element's, and the structure a `token` delta says held did not. A
+  `bands: ['token']` ignore rule no longer reads it. `bandOf` owns the rule, as
+  `bandOf(kind, { retagged })`, and a parting row's bands now read each delta's
+  own band, so the row and the docket agree.
+- 4aa7b16: Content inserted into a page is the inserted rows, not everything under them
+
+  Two images of the same width are compared row by row after their rows are
+  aligned: each row is hashed, runs of equal rows are one token, and Myers finds
+  the shortest edit between the two sequences. Each after row is then compared
+  with the before row that shows the same content, and `pixelmatch` still judges
+  every pairing; a row that moved, came or went is a change in itself, so no
+  pairing makes a page read as unchanged. A section added to a long page marks that
+  section, and the content it pushed down matches. A pairing is kept only when it
+  leaves fewer pixels differing than position does, a row it leaves unpaired
+  charged in full, so a line that changed in place is not shifted against its
+  neighbours. The rows a gap grew by are inserted, as the rows it lost are
+  removed, so a button whose padding grew has a region where it grew. Images of
+  different widths, or an edit longer than 2,000 runs of rows, are compared
+  position by position on the union box, as before.
+
+  An inserted row is marked edge to edge, since nothing says where its content
+  begins, so a region inside one is joined by its rows rather than its area: to
+  the tightest box whose rows span it. `attributeRegions` takes the inserted rows
+  as `inserted`. Joined by area, every such band went to the subject's root, and
+  a card whose button grew named the card rather than the button.
+
+  `RasterComparison.alignment` carries the pairing as `RowAlignment`: the after
+  rows `inserted`, the before rows `removed` with the after row they left from,
+  and the rows `shifted` with how far. A comparison without it was not aligned.
+
+  Content that moved is a change. A gap that grew in one place and shrank in
+  another moves what lies between them and leaves the page as tall as it was, and
+  every moved row matches the row it came from; such a subject reports `changed`,
+  never `unchanged` or `ignored`. The reason names the edit:
+  *120 pixels differ across 1 region; 3 pixel rows inserted in 1 place, moving
+  the content under them by up to 3 rows, and the subject resized from 40×5 to
+  40×8*. The Playwright fixture's evidence now writes a diff for a subject that
+  resized, drawn on the after image.
+- 16e7c76: `dominatorsOf` is removed from `@variance-authority/core/relate`
+
+  Nothing ran it once distill read its records in the sense addon, which finds
+  the import every path from a test file runs through with its own dominator
+  pass. A caller that needs immediate dominators of a file graph computes them
+  over `Relations` directly.
+
+### Patch Changes
+
+- 8d1bcc1: A link in a doc comment opens from `node_modules`
+
+  Doc comments linked to documentation by repository paths such as
+  `../../../../docs/flakiness.md`, which resolve to nothing in an installed
+  package. They now link to the page on variance-authority.dev, or to the file on
+  GitHub when the site does not publish it, so the link works on hover in your
+  editor and in what `variance ask symbol` prints.
+
+  The MCP server's instructions and its observability answer linked to
+  `/start-cli` and `/presentation`, which the site does not serve. They now link
+  to `/start/cli` and `/docs/presentation`, and the `@variance-authority/cli`,
+  `@variance-authority/help`, `@variance-authority/mcp` and
+  `@variance-authority/vitest-browser` READMEs link to the guides where the site
+  publishes them.
+
+  `variancePrecondition`, `wiringOf`, `tapCommits` and `provenanceOf` carry an
+  `@see` link to the section of the guide that documents them.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -5,6 +5,7 @@
 > The Variance Authority format, rules, comparison, attribution and verdicts. Pure data in, pure data out, no DOM and no I/O.
 
 Part of [Variance Authority](https://variance-authority.dev).
+Point your coding agent at [`llms.txt`](https://variance-authority.dev/llms.txt).
 
 ## What this is for
 
@@ -187,13 +188,13 @@ are five, loudest first:
 | band | what changed | example delta kinds |
 |---|---|---|
 | `a11y` | a role, accessible name, description or ARIA state | `role-changed`, `name-changed`, `state-changed` |
-| `geometry` | boxes appeared, vanished, moved or resized | `node-added`, `node-moved`, `rect-changed`, `attribute-changed` |
-| `token` | style values changed while structure stayed the same | `style-changed`, `token-changed` |
+| `geometry` | boxes appeared, vanished, moved, resized or were replaced | `node-added`, `node-moved`, `tag-changed`, `rect-changed`, `attribute-changed` |
+| `token` | style values changed while structure stayed the same | `style-changed`, `token-changed`, except on a pair across two tags, where they are `geometry` |
 | `content` | text changed and nothing else did | `text-changed` |
 | `texture` | sub-semantic rendering variance | `raster-residue` |
 
-`bandOf(kind)` performs that assignment and is the default rather than the
-answer — policy may promote or demote per project, subject, region or
+`bandOf(kind, { retagged })` performs that assignment and is the default
+rather than the answer — policy may promote or demote per project, subject, region or
 component. `loudestBand(bands)` collapses a set to the loudest one present, and
 returns `null` for an empty set so that *nothing changed* and *something changed
 at the quietest band* stay apart.
@@ -231,7 +232,10 @@ const after = normalize(recapture);
 const diff = diffSnapshots(before, after);           // deltas and roots, no verdict
 
 const places = isolateRegions(mask, { cell: 8 });    // pixels → regions
-const named = attributeRegions(places.regions, after, { scale: 2 });
+const named = attributeRegions(places.regions, after, {
+  scale: 2,
+  before,                                            // where the pixels it replaced were
+});
 ```
 
 `diffSnapshots` returns `identical`, the flat `deltas`, the `roots` a docket
@@ -245,6 +249,20 @@ runner.
 screenshot at 1x and every region lands in the top-left quadrant with the wrong
 component named — a full, plausible, entirely wrong report.
 
+`before` is required too: the snapshot of the revision the pixels are compared
+against, or `undefined` when nobody kept it. A change that replaces an element
+paints over the old box and the new one, so each node is joined against its own
+box and the box of the node the differ's matcher pairs it with. A stored baseline
+carries that snapshot packed, as its `snapshot`; `unpackSnapshot` in
+`@variance-authority/observe` reads it back.
+
+Each box that left is placed by where it was in its own image. A screenshot
+clipped to the subject starts at the subject's root, and `beforeOrigin` is the
+before image's top-left corner in page CSS pixels. It defaults to the before
+snapshot's root, as `origin` defaults to this render's. When you pass `origin`
+and a `before` snapshot, pass `beforeOrigin` too, or the call throws: the page
+can move what you clipped to between the two shots.
+
 Rendered comparisons throw when the two subjects differ, or when their
 observation profiles differ.
 
@@ -253,7 +271,7 @@ observation profiles differ.
 | call | useful controls |
 |---|---|
 | `normalize` | `collapseWrappers` removes layout-only wrapper boundaries, `digestText` includes text content, and `sourceRoot` relativizes source locations |
-| `isolateRegions` / `attributeRegions` | `cell` and `limit` bound mask work; `origin` and `containment` describe the coordinate origin and how much a node must contain a region |
+| `isolateRegions` / `attributeRegions` | `cell` and `limit` bound mask work; `origin` and `containment` describe the coordinate origin and how much a node must contain a region; `inserted` names the rows the after image added, and a region inside them goes to the tightest box whose rows span it |
 | `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 |
@@ -364,4 +382,4 @@ the comparison is refused rather than reported as a difference in the product.
 
 ---
 
-**[@variance-authority/core](https://variance-authority.dev/reference/packages/core)** is part of [Variance Authority](https://variance-authority.dev) — [documentation](https://variance-authority.dev/docs) · MIT
+**[@variance-authority/core](https://variance-authority.dev/reference/packages/core)** is part of [Variance Authority](https://variance-authority.dev) — [documentation](https://variance-authority.dev/docs) · [GitHub](https://github.com/Variance-Authority/variance-authority/tree/main/packages/core) · MIT

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

@@ -49,7 +49,7 @@ export declare function hashComponents(snapshot: SemanticSnapshot): readonly Com
  * The arithmetic behind cause-first ranking, and the reason a baseline carries
  * its component hashes at all. `rankRegions` takes a list of cause names and,
  * given none, falls back to area — which
- * [journal 0013](../../../../docs/context/journal/0013-observability.md)
+ * [journal 0013](https://github.com/Variance-Authority/variance-authority/blob/main/docs/context/journal/0013-observability.md)
  * measured as backwards by 6×, because area measures displacement rather than
  * cause. This is where that list comes from on a path with no second document.
  *
@@ -81,12 +81,20 @@ export declare function causesBetween(before: readonly ComponentHash[], after: r
  * and a boolean cannot serve a route-level test, whose entire request is *tell
  * me when the page stops assembling and never when it is repainted*.
  *
- * The mapping is exact and it is the same one `bandOf` applies to a delta, which
- * is the property that matters: a subject relaxed to `layout` must absorb the
+ * The mapping is the same one `bandOf` applies to a delta, but for the one case
+ * below, and that is the property that matters: a subject relaxed to `layout` must absorb the
  * same things whether the run held two documents or two sidecars. Two mappings
  * would be one drift away from a config key meaning different things on the two
  * paths, discovered as a regression somebody let through.
  *
+ * One delta the digests cannot band as `bandOf` does: the style of an element
+ * its author replaced, which `bandOf` bands `geometry` with the tag change. Two
+ * hashes do not say the tag changed under the style, so the `style` digest still
+ * reads `token` beside it. The `structure` digest moves with the tag, so both
+ * paths report `geometry`, and the one level that asserts `token`, `strict`,
+ * asserts `geometry` too: the verdict agrees. What differs is the list a
+ * relaxed reason gives as absorbed, which names `token` on this path only.
+ *
  * | digest | band | what it covers |
  * |---|---|---|
  * | `semantics` | `a11y` | role, accessible name, ARIA state |

package/dist/attribute/component-hash.js

@@ -92,7 +92,7 @@ function byCodeUnit(a, b) {
  * The arithmetic behind cause-first ranking, and the reason a baseline carries
  * its component hashes at all. `rankRegions` takes a list of cause names and,
  * given none, falls back to area — which
- * [journal 0013](../../../../docs/context/journal/0013-observability.md)
+ * [journal 0013](https://github.com/Variance-Authority/variance-authority/blob/main/docs/context/journal/0013-observability.md)
  * measured as backwards by 6×, because area measures displacement rather than
  * cause. This is where that list comes from on a path with no second document.
  *
@@ -176,12 +176,20 @@ function ownContentMoved(before, after) {
  * and a boolean cannot serve a route-level test, whose entire request is *tell
  * me when the page stops assembling and never when it is repainted*.
  *
- * The mapping is exact and it is the same one `bandOf` applies to a delta, which
- * is the property that matters: a subject relaxed to `layout` must absorb the
+ * The mapping is the same one `bandOf` applies to a delta, but for the one case
+ * below, and that is the property that matters: a subject relaxed to `layout` must absorb the
  * same things whether the run held two documents or two sidecars. Two mappings
  * would be one drift away from a config key meaning different things on the two
  * paths, discovered as a regression somebody let through.
  *
+ * One delta the digests cannot band as `bandOf` does: the style of an element
+ * its author replaced, which `bandOf` bands `geometry` with the tag change. Two
+ * hashes do not say the tag changed under the style, so the `style` digest still
+ * reads `token` beside it. The `structure` digest moves with the tag, so both
+ * paths report `geometry`, and the one level that asserts `token`, `strict`,
+ * asserts `geometry` too: the verdict agrees. What differs is the list a
+ * relaxed reason gives as absorbed, which names `token` on this path only.
+ *
  * | digest | band | what it covers |
  * |---|---|---|
  * | `semantics` | `a11y` | role, accessible name, ARIA state |