@variance-authority/core 0.2.0 → 0.3.0

package/README.md

@@ -1,41 +1,153 @@
-<p align="center"><img src="./mark.svg" alt="Variance Authority mark" width="72"></p>
+<p align="center"><img src="https://variance-authority.dev/mark.svg" alt="Variance Authority mark" width="72"></p>
 
 # @variance-authority/core
 
 > The Variance Authority format, rules, comparison, attribution and verdicts. Pure data in, pure data out, no DOM and no I/O.
 
-A **subject** is whatever is under test — a component, a page, or a plain
-value. A **capture** is the raw material a collector records from it once,
-before anything is compared. Collectors extract captures; this package
-normalizes and adjudicates them, and never captures anything itself.
+Part of [Variance Authority](https://variance-authority.dev).
+
+## What this is for
+
+You already have a reading of something — a DOM recorded by a collector, a
+rendered document, a per-pixel diff mask, or a plain JSON value — and you need
+to know what changed in it, which component and file the change lands on, and
+whether anyone should mind. This package does that part and only that part. It
+opens no DOM, reads no files, makes no network calls, and has no runtime
+dependencies: what you hand it is everything it sees.
+
+A **subject** is one named UI state you asked for and can ask for again — a
+component in a given state, a page at a given route, or a plain value. A
+**capture** is the raw material a collector records from a subject once, before
+anything is compared. Collectors produce captures; this package normalizes and
+adjudicates them, and captures nothing itself.
+
+## Requirements
+
+Node 22 or newer, and ESM. There is no CommonJS build, so `require()` will not
+load it. No runtime dependencies — every input arrives from a package you
+install separately, named at each example below.
+
+## Install, and compare a value
+
+The shortest complete path needs no browser and nothing else installed.
 
 ```bash
 npm install --save-dev @variance-authority/core
 ```
+
+```ts
+import { shapeValue } from '@variance-authority/core/format';
+import { compareValues } from '@variance-authority/core/compare';
+
+const shaping = { arrayKey: { '/rows': 'id' } };
+
+const baseline = shapeValue(
+  { rows: [{ id: 'checkout', total: 10 }, { id: 'cart', total: 4 }] },
+  shaping,
+);
+const candidate = shapeValue(
+  { rows: [{ id: 'checkout', total: 12 }, { id: 'cart', total: 4 }, { id: 'search', total: 1 }] },
+  shaping,
+);
+
+console.log(baseline);
+console.log(compareValues(baseline, candidate));
+```
+
+### What you get
+
+```
+{
+  dialect: 'json',
+  text: '{"rows":{"cart":{"id":"cart","total":4},"checkout":{"id":"checkout","total":10}}}',
+  digest: 'v1:e19dcb366e2321d0c7890dd69629ac39',
+  recipe: 'value/1',
+  keyed: [ '/rows' ]
+}
+[
+  {
+    change: 'value-changed',
+    pointer: '/rows/checkout/total',
+    fingerprint: 'v1:444e8245747e15412c5142a5a44fe321'
+  },
+  {
+    change: 'added',
+    pointer: '/rows/search',
+    fingerprint: 'v1:a9bd40864996d0b80d37c034f3f62109'
+  }
+]
+```
+
+Three things in that output do work you will want later.
+
+`text` is the canonical serialization, byte for byte what `digest` was taken
+over — keys sorted, numbers written portably, `undefined` omitted. It is what a
+baseline stores and what a person reads in a pull request.
+
+`arrayKey` turned the `rows` array into an object keyed by `id` before
+canonicalization, which is why inserting `search` at the end reports one
+`added` delta. Compared by index instead, an insertion at the top of a
+two-thousand-row list reports two thousand rows as changed.
+
+`fingerprint` is the shape of the difference with the row identity and the
+values removed. Change `cart.total` instead of `checkout.total` and you get the
+same `v1:444e8245747e15412c5142a5a44fe321`, so one decision can settle the same
+edit wherever it occurred. Deltas record no values at all: the two canonical
+texts are the evidence, and a delta that quoted them would put payload into
+every record that accumulates.
+
+`compareValues` throws rather than guessing when the two sides disagree about
+how they were made — different dialects, different shaping rules, or different
+keyed arrays. `shapeValue` throws on anything that cannot be canonical text,
+naming the JSON Pointer:
+
+```
+the value at /at is a Date, which is not a value. Its state is not in its own
+enumerable keys, so it would serialize to `{}` and two different ones would
+compare as unchanged.
+```
+
+Functions, `Date`, `bigint` and non-finite numbers all fail this way. The
+alternative is `JSON.stringify`'s: drop the key silently, which the next run
+reads as a key that was removed.
+
+### Shaping options
+
+| option | effect |
+|---|---|
+| `arrayKey` | `{ '/rows': 'id' }` — the member that identifies a row, so an array becomes an object and order stops being a fact about it |
+| `drop` | records a pointer's value as the token `[dropped]` — present, never compared |
+| `replace` | puts a stable token of your choosing at a pointer |
+| `dialect` | a label saved with the text, `'json'` by default; two values with different dialects refuse to compare |
+| `generator` | `{ name, version }` of whatever emitted the value |
+
+Every key is a JSON Pointer (RFC 6901). A `-` token matches any array index, so
+`/items/-/updatedAt` names that member of every item. Neither `dialect` nor
+`generator` counts toward the digest, so labelling a value later does not orphan
+its baseline.
+
 ## Use this package when
 
 Install `@variance-authority/core` when the input is already produced: a
-capture, a semantic snapshot, a render document (serialized subject markup,
-ready to be rasterized elsewhere), a raster mask (`ChangeMask`: a per-pixel
-changed/unchanged bitmap, not an image), or a plain value. The package does
-not collect a DOM, read PNG bytes, launch a renderer, or select a test
-runner — for that, install `@variance-authority/dom` for a live DOM,
-`@variance-authority/react` for React provenance (the chain of component
-ownership attached to each node), and `@variance-authority/png` when the
-input is a PNG.
+capture, a **semantic snapshot** (a normalized tree of nodes, digests and
+boxes), a **render document** (serialized subject markup, ready to be
+rasterized elsewhere), a **change mask** (`ChangeMask`: a per-pixel
+changed/unchanged bitmap, not an image), or a plain value.
+
+To produce those inputs, install a collector beside it:
+
+```bash
+npm install --save-dev @variance-authority/dom    # collect() a live DOM into a capture
+npm install --save-dev @variance-authority/react  # React component ownership per node
+npm install --save-dev @variance-authority/png    # comparePngs() two PNGs into a ChangeMask
+```
 
 ## Entrypoints
 
-Nine groups. Five of them are the order an answer travels through; `core/plan`
-and `core/relate` sit outside that line, because both are asked *before* anything
-is captured — one decides which baselines the run can reach at all, the other
-decides which subjects are worth reaching for. `core/segment` and `core/share`
-sit outside it in the other direction: they are how a derived answer is written
-down and handed to another machine, and neither knows what it is carrying. Every
-name lives in exactly one group, and the bare specifier holds only the capture
-artifact.
+Every name lives in exactly one group, and the bare `@variance-authority/core`
+specifier exports only the capture artifact.
 
-| entrypoint | holds |
+| entrypoint | exports |
 |---|---|
 | `core/format` | what a subject *is*: capture, snapshot, document, identity, hashing |
 | `core/rules` | the versioned opinions: allowlist, applicability, cascade, canonicalization |
@@ -47,130 +159,144 @@ artifact.
 | `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, under a key that is a commit |
 
-Three terms recur across those groups. A **profile** records what a collector
-was capable of observing — jsdom sees structure and declared style, chromium
-adds layout and pixels. An **identity** is the content hash that addresses a
-result; two runs are comparable only when their identities match. A
-**verdict** is one of six words this package will commit to: `unchanged`,
-`inherited`, `authorized`, `needs-review`, `violation`, `unexplained`.
-
-The groups exist for callers who genuinely want one. Somebody implementing the
-capture format for a renderer this project has never met needs `core/format` and
-would be misled by everything else. Somebody deciding where a baseline is stored,
-or whether two runs may be compared at all, needs `core/plan` and nothing else:
-the digest it derives is the address, so changing any part of the plan changes
-which baselines the run can see.
-
-## Comparison and policy
-
-`compare` says **what changed**. `judge` says **whether anyone should mind**.
-
-Between them sits `partingOf`, which says **which input moved**. Given two
-snapshots carrying holdings it walks the component boundaries for the shallowest
-one whose inputs agreed and whose output did not, and reports that as the origin
-— a moved prop, a context, an external store, or a hook cell by call position.
-It leads with a slice (`variation`, `flake`, `refactor`, `absorbed`, `settled`,
-`unread`) so a reader knows whether to open the rest, and `explainParting` turns
-the whole thing into lines a person reads.
-
-## Smallest working path: compare a value
-
-Value comparison needs no host setup and returns paths and fingerprints, not a
-pass/fail verdict:
-
-```ts
-import { compareValues } from '@variance-authority/core/compare';
-import { shapeValue } from '@variance-authority/core/format';
+Five of those are the order an answer travels through: `format`, `rules`,
+`compare`, `attribute`, `judge`. `plan` and `relate` are asked 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.
+
+## The four words the output uses
+
+A **profile** records what a collector was capable of observing. `jsdom` sees
+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.
+
+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
+opposite each other: an accessible name almost never changes and is a defect
+when it does, while anti-aliasing changes constantly and never matters. There
+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` |
+| `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
+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.
+
+A **verdict** is the one word a result reports, and the whole pipeline exists to
+produce one with a reason attached. There are six, by severity:
+
+| verdict | means |
+|---|---|
+| `unchanged` | hash hit, or never reachable from the change |
+| `inherited` | fully explained by an adjudication that already happened upstream |
+| `authorized` | matches declared intent, or policy auto-approves this band |
+| `needs-review` | band and policy require a human to sign off |
+| `violation` | policy forbids it |
+| `unexplained` | raster residue with no semantic cause — the highest severity here, because a change the pipeline cannot explain means attribution failed |
 
-const before = shapeValue({ rows: [{ id: 'a', total: 10 }] }, {
-  arrayKey: { '/rows': 'id' },
-});
-const after = shapeValue({ rows: [{ id: 'a', total: 12 }] }, {
-  arrayKey: { '/rows': 'id' },
-});
+Beside those sits `UNOBSERVED`, which is what a band reports when the acting
+profile could not see it. It is not a verdict and the types will not let you
+spell it as one.
 
-const deltas = compareValues(before, after);
-console.log(deltas[0]?.pointer);                     // /rows/a/total
-```
+## Compare a rendered subject
 
-For a rendered subject, the same package receives captures from a collector:
+Excerpt. `capture` and `recapture` are what `collect(root, options)` from
+`@variance-authority/dom` returns for the same subject at two revisions; `mask`
+is the `mask` field of `comparePngs(before, after)` from
+`@variance-authority/png`. Core never opens an image.
 
 ```ts
-import { attributeRegions, isolateRegions } from '@variance-authority/core/attribute';
-import { diffSnapshots } from '@variance-authority/core/compare';
 import { normalize } from '@variance-authority/core/rules';
+import { diffSnapshots } from '@variance-authority/core/compare';
+import { attributeRegions, isolateRegions } from '@variance-authority/core/attribute';
 
-const before = normalize(capture);                   // supplied by a collector
+const before = normalize(capture);
 const after = normalize(recapture);
-const diff = diffSnapshots(before, after);           // deltas, roots, no verdict
+const diff = diffSnapshots(before, after);           // deltas and roots, no verdict
 
-// `mask` is a ChangeMask from the raster tier. Core never opens an image.
 const places = isolateRegions(mask, { cell: 8 });    // pixels → regions
 const named = attributeRegions(places.regions, after, { scale: 2 });
 ```
 
-The value example prints a JSON Pointer for the changed field. The rendered path
-returns semantic roots and, when a raster mask is supplied, regions attributed to
-the candidate snapshot. A caller still chooses policy and a verdict in
-`core/judge` or in its own runner.
+`diffSnapshots` returns `identical`, the flat `deltas`, the `roots` a docket
+renders and approves, and the `components` implicated, separated into causes and
+collateral — so "`Button` changed, and ten components render it" replaces
+"eleven components changed". `attributeRegions` turns regions into components
+and files. Choosing a verdict is a separate step, in `core/judge` or in your own
+runner.
 
-`scale` is device pixels per CSS pixel. It is **required**, and it has no default
-on purpose: a 2x screenshot attributed at 1x lands every region in the top-left
-quadrant and names the wrong component for each — a full, plausible, entirely
-wrong report. That last step is where regions become components and files.
+`scale` is device pixels per CSS pixel and it is required. Attribute a 2x
+screenshot at 1x and every region lands in the top-left quadrant with the wrong
+component named — a full, plausible, entirely wrong report.
 
-The options that change scope are explicit at the call site:
+Rendered comparisons throw when the two subjects differ, or when their
+observation profiles differ.
+
+### Options that change scope
 
 | 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 |
-| `fingerprintOfMask` | `grid` controls the shape sample and `coverage` controls the minimum occupied share |
+| `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 enters, and `shadows` carries per file the modules its run never reaches, so `movedBy` leaves out a file every trail to which crosses one of its own shadows |
+| `buildDocket` / dependency reach | `sampleSize` limits review examples; `through` selects graph edge kinds, `avoid` names nodes a walk never enters, and `shadows` lists per file the modules its run never reaches, so `movedBy` 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 |
+| `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 entered |
 | report summaries | `source` maps component names to files when `summarizeAdjudication` or `summarizeFindings` needs an actionable path |
 | screenshot stabilization | `animations` and `caret` are explicit intervention settings; omitted means the caller did not assert either intervention |
 
-### A subject that was never rendered
+## Which input changed
 
-`shapeValue(value, options)` is the same treatment for a value — an API
-response, a generated schema, a route table. It canonicalizes (keys sorted,
-numbers written portably, `undefined` omitted), addresses the text by content,
-and returns a `CapturedValue`; `compareValues` turns two of them into deltas
-carrying a JSON Pointer and a fingerprint, and — like everything else here — no
-verdict.
+`compare` says what changed. `judge` says whether anyone should mind. Between
+them, `partingOf` says which input changed.
 
-```ts
-import { compareValues } from '@variance-authority/core/compare';
-import { shapeValue } from '@variance-authority/core/format';
+Given two snapshots with holdings — the inputs a collector recorded at each
+component boundary — it walks the boundaries for the shallowest one whose inputs
+agreed and whose output did not, and reports that as the origin: a changed prop,
+a context, an external store, or a hook cell by call position. `explainParting`
+turns the result into lines a person reads.
 
-const baseline = shapeValue(before, { arrayKey: { '/rows': 'id' } });
-const deltas = compareValues(baseline, shapeValue(after, { arrayKey: { '/rows': 'id' } }));
-```
+It leads with a slice, so you know whether to open the rest:
 
-`drop` records a pointer's value as present without comparing it, `replace` puts
-a token you choose in its place, and `arrayKey` says which member identifies a
-row — the difference between *one row was added* and *two thousand rows moved*.
-Two more options describe the value rather than shape it: `dialect` is how a
-reader will interpret the text later (`'json'` by default, `'openapi'` and
-`'graphql'` being the ones with detectors), and `generator` names what emitted
-it. Neither reaches the digest, so declaring a dialect does not orphan a
-baseline.
+| slice | means |
+|---|---|
+| `settled` | nothing changed: not the tree, not an input, not the output |
+| `variation` | an input changed and the output followed — the ordinary case, and the only one where the detail below is worth reading |
+| `absorbed` | an input changed and the output did not; the component ignored it |
+| `refactor` | the component tree changed and the output did not |
+| `reshaped` | the tree is a different tree, no input changed, and the output followed |
+| `flake` | every input agreed, the tree matched, and the output changed anyway |
+| `placed` | the same, but between two readings taken in different places |
+| `unread` | the output changed and what would explain it was not read |
 
-Non-data throws, naming the pointer. A function, a `Date`, a `bigint` or a
-non-finite number cannot be canonical text, and dropping one silently puts a key
-in the record that the next run reads as removed.
+`flake` is an accusation against a page, so it is never returned on silence. A
+run that recorded no component provenance gets `unread` instead.
 
-Rendered comparisons also throw when the subjects or observation profiles differ.
+## Hand an answer to another machine
 
-## Handing an answer to another machine
+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` moves
+the bytes.
 
-A run derives what the suite is made of, and that is a fact about a commit
-rather than about the 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` moves the bytes:
+Excerpt: `token` is your store's credential and `bytes` is what `core/segment`
+encoded.
 
 ```ts
 import { httpShare, shareKey } from '@variance-authority/core/share';
@@ -184,28 +310,29 @@ const share = httpShare({
 await share.put(shareKey({ project: 'web', artifact: 'suite-index-v1', commit }), bytes);
 ```
 
-`endpoint` is a base URL a key is appended to; `headers` is sent on every
-request, which is where a bucket's `Authorization` or a deployment's token goes;
+`endpoint` is a base URL a key is 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. A presigned base needs none of the three but the first.
+that routes on it. A presigned base needs only the endpoint.
 
 **A share never throws.** A miss, an outage, a permission error and a body
 nobody can parse are one outcome: `get` answers `null` and `put` resolves.
-Everything a share holds was derived from a tree and can be derived again, so
-the worst a broken one does is cost the derivation — which also means a failing
-share is indistinguishable from a cold one, and only the wall clock says so.
-[Sharing an evaluation](../../docs/sharing.md) is the operator's side of it.
+Everything a share stores can be derived again, so a broken share costs you the
+derivation — and is indistinguishable from a cold one except by the wall clock.
+[Sharing an evaluation](https://variance-authority.dev/docs/sharing) is the
+operator's side of it.
 
 ## What it refuses
 
-**Absent is not empty.** Not measured, measured as zero, and unobservable are
-three states, and collapsing any two produces a pass nobody earned. A **band**
-(the frequency category a change falls into — `a11y`, `geometry`, `token`,
-`content`, `texture`, rarest to noisiest) that a profile cannot see reports
-`UNOBSERVED`, which the type system will not let you spell the same way as a
-pass.
+**Absent is not empty.** Not measured, measured as zero, and unobservable stay
+three distinct states through every type in this package. A band the profile
+could not see reports `UNOBSERVED`, and a geometry digest is absent rather than
+empty under a profile without layout.
+
+**Two results whose identities differ never compare.** A ruleset bump, a
+different viewport, a different intervention — each changes the identity, and
+the comparison is refused rather than reported as a difference in the product.
 
-**Two results whose identities differ are `incomparable`, never `different`.**
-A difference in conditions reported as a difference in the product is a
-confident wrong answer, and the confidence is what makes it expensive.
+---
 
+**[@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

package/dist/attribute/call-site.d.ts

@@ -1,4 +1,4 @@
-import type { Provenance, SourceLocation, StackFrame } from '../format/provenance.js';
+import { type Provenance, type SourceLocation, type StackFrame } from '../format/provenance.js';
 import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
 /**
  * Spending the frames a page read, to get the file a reviewer opens.
@@ -33,6 +33,24 @@ import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
  */
 /** Fetch a module's text, or answer that it cannot be had. Never throws. */
 export type FetchModule = (url: string) => Promise<string | null>;
+export interface CallSiteOptions {
+    /**
+     * The repository root, for a location that arrives holding an absolute path.
+     *
+     * Two kinds of frame reach {@link CallSiteResolver.locate} and only one of
+     * them is relative already. A frame that needed a map is answered in the map's
+     * own terms, which are the build's and so the repository's. A frame that
+     * needed none — a Node stack, or the synthetic frame React manufactures for a
+     * server component — is answered in the terms of the disk it was captured on,
+     * which means somebody's home directory in the middle of a path that is
+     * otherwise a fact about the project.
+     *
+     * Given, the two shapes come out as one. Absent, a location is returned as it
+     * arrived, because guessing at a root is how a path stops resolving for the
+     * reader who opens it.
+     */
+    readonly sourceRoot?: string;
+}
 export interface CallSiteResolver {
     /** The location that wrote an element, from the frames its fiber carried. */
     locate(frames: readonly StackFrame[]): Promise<SourceLocation | null>;
@@ -47,7 +65,7 @@ export interface CallSiteStats {
     /** Call sites that resolved to a file. */
     readonly located: number;
 }
-export declare function createCallSiteResolver(fetchModule: FetchModule): CallSiteResolver;
+export declare function createCallSiteResolver(fetchModule: FetchModule, options?: CallSiteOptions): CallSiteResolver;
 /**
  * Provenance with its frames spent: `source` filled in, `stack` gone.
  *

package/dist/attribute/call-site.js

@@ -1,6 +1,7 @@
+import { relativizeSource, } from '../format/provenance.js';
 import { inlineSourceMapOf, originalPositionFor, parseSourceMap, sourceMappingUrlOf, } from './source-map.js';
-import { isVendorPath, writerLocationOf } from './stack.js';
-export function createCallSiteResolver(fetchModule) {
+import { isVendorPath, servedPath, writerLocationOf } from './stack.js';
+export function createCallSiteResolver(fetchModule, options = {}) {
     /** Module URL → its map, `null` once we know it has none. Also the in-flight guard. */
     const maps = new Map();
     /** `url:line:column` → the answer, so a page's 4211 nodes cost 14 resolutions. */
@@ -34,10 +35,11 @@ export function createCallSiteResolver(fetchModule) {
     }
     async function locateFrame(frame) {
         const parsed = await mapsFor(frame.url);
-        // No map is not failure. A dev server serving a plain `.js` as written, and a
-        // Node test runner — which applies source maps to `Error.stack` itself, so
-        // the frame arrives already original — both land here with the answer in
-        // hand. `writerLocationOf` keeps the frame's own coordinates in that case.
+        // No map is not failure, and it is not an answer either. A Node test runner
+        // applies source maps to `Error.stack` itself, so its frame arrives already
+        // original and there is nothing left to add. A served module carries no such
+        // guarantee: a position in the text a server sent is a position in the
+        // repository only if a map says so, so `writerLocationOf` refuses it.
         if (parsed === null || parsed.length === 0)
             return null;
         const original = originalPositionFor(parsed, frame.line, frame.column);
@@ -61,8 +63,8 @@ export function createCallSiteResolver(fetchModule) {
                 sites.set(key, answer);
             }
             const located = await answer;
-            // The frame's own coordinates, for a module served as written. Delegated so
-            // there is one statement of the choosing rule rather than two.
+            // The frame's own coordinates, for a frame that names a file on disk.
+            // Delegated so there is one statement of the choosing rule rather than two.
             const chosen = located === null
                 ? writerLocationOf([frame], () => null)
                 : isVendorPath(located.file)
@@ -70,7 +72,9 @@ export function createCallSiteResolver(fetchModule) {
                     : located;
             if (chosen !== null) {
                 stats.located += 1;
-                return chosen;
+                return options.sourceRoot === undefined
+                    ? chosen
+                    : relativizeSource(chosen, options.sourceRoot);
             }
         }
         return null;
@@ -152,19 +156,12 @@ function index(root) {
  * A map's `sources` entry as a path, resolved against the module it describes.
  *
  * Maps state sources relatively — Vite writes `probe.jsx` for `/src/probe.jsx` —
- * so the entry alone is ambiguous between two directories. Resolved and then
- * stripped to a path, because the origin is a fact about the machine that ran
- * the capture: a baseline holding `http://localhost:5199/src/probe.jsx` would
- * disagree with the next run on a different port. What is left is what the
- * source index and `relativizeSource` already speak.
+ * so the entry alone is ambiguous between two directories. Resolved against the
+ * module first, then stripped of the origin it resolved against, which is a fact
+ * about the machine that served it rather than about the code.
  */
 function sourcePath(source, moduleUrl) {
-    const resolved = absolute(source, moduleUrl) ?? source;
-    const parsed = parseUrl(resolved);
-    // Not a URL: a bundler that wrote an absolute filesystem path, or a
-    // `webpack://` specifier. Left as it is — `relativizeSource` handles the
-    // first, and inventing a shape for the second would be a guess.
-    return parsed === null ? resolved : parsed.pathname.replace(/^\/+/, '');
+    return servedPath(absolute(source, moduleUrl) ?? source);
 }
 function absolute(url, base) {
     return parseUrl(url, base)?.href ?? null;