@variance-authority/core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,197 @@
 # @variance-authority/core
 
+## 0.2.0
+
+### Minor Changes
+
+- e546e21: A collector's complaints travel into the observation
+  
+  A finding produced at collection reached the CLI's record and nobody else. A
+  suite driving this from its own runner asks the observation what is wrong with a
+  subject, and the one diagnostic that explained the moved pixels — the host, not
+  the stylesheet, chose the typeface — was produced, carried, and dropped one call
+  short of the person reading the failure.
+  
+  `mergeDiagnostics` dedupes on every field, so the CLI, which now meets the same
+  list twice, says a shared complaint once.
+- f4b328b: Mainline's evaluation can travel, so the next machine does not derive it again
+  
+  A suite index is bytes addressed by the commit they were written at, which is
+  exactly the shape a cache already wants. What was missing was anywhere to put
+  them: every checkout that wanted to know what `main` looked like had to run
+  `main`, and in CI that is the whole suite, twice, on every pull request.
+  
+  `@variance-authority/core/share` is the transport, and it has two backends
+  because there are two. A **directory** is what `actions/cache`, `aws s3 sync`, a
+  network mount and a laptop all are once the bytes are on disk; an **HTTP
+  endpoint** is what a bucket, a presigned URL and a tribunal deployment all are.
+  `createDirectoryShare` in `@variance-authority/store/share` is the filesystem
+  half, kept out of `core` because `core` takes no platform.
+  
+  A share never fails a run. `get` answers `null` and `put` resolves, whatever the
+  network did — a share that is down, misconfigured or empty is indistinguishable
+  from a cold one, and the run derives its own index and continues. The cost is
+  deliberate: a typo in an endpoint is a suite that quietly got slower rather than
+  a build that went red, and the `behind` count `variance share` prints is the
+  signal that publishing has stopped.
+  
+  The CLI gained a `share` section in its config, a `variance share` command that
+  says what the share holds for mainline or publishes what this run derived, and a
+  line on `variance run` naming where the index went. A lookup walks the lineage —
+  `merge-base` with the configured `mainline`, then first-parent — and asks this
+  machine's own cache for every commit before it asks the share, because the run
+  that just published is usually the one asking.
+  
+  `docs/sharing.md` is the arrangement end to end, GitHub Actions first.
+- e546e21: A subject is allowed to reference something that is not there
+  
+  A fixture that points an `<img>` at a path nobody serves is testing the fallback,
+  and the broken state is the subject. Capture had no way to say so: the resolver
+  returned bytes or the capture was refused, so Material UI's CardMedia,
+  ImageListItem and Avatar suites — which all reference a deliberately absent
+  `/fake.png` — could not be captured at all.
+  
+  `resolveResource` may answer `{ absent: true }`. The resource is recorded with
+  its status, and the renderer answers that status instead of counting the request
+  as one the document failed to carry.
+- e546e21: A subject with no pixels is a baseline without an image, not a subject that got away
+  
+  A wrapper whose only child went to a portal, or a conformance mount with no
+  children, occupies nothing. Refusing to photograph it is right; refusing the
+  subject was not. On Material UI's unit tier that was 1109 of 4371 subjects
+  reported as unobserved while the capture held their markup, their rules, their
+  component hashes and their accessibility tree — none of which was in doubt.
+  
+  `Raster` makes the image optional: `bytes`, `width` and `height` are absent
+  together or present together, and `pictured` is the one place that narrows all
+  three. Absent means *this subject has no pixels*, which is a measurement — it
+  never means the image was lost. `occupiesPixels` asks the same question of a
+  record read without bytes, which is the only form a sidecar takes. `observe`
+  gets a second tier in `unpictured.ts`, where the comparison such a subject can
+  still take — document digest, component hashes, accessibility — is the whole
+  verdict. `promotionOf` promotes the sidecar alone when there is no `after`,
+  because the subject reached a verdict and the only missing half is the one a
+  camera would have produced.
+  
+  The file-backed store carries the same nullable pair, and with it the split of a
+  baseline's two halves into two path prefixes. `identities` scans the record root,
+  because a subject with no pixels has no image directory to be found in and the
+  sibling scan would otherwise call another machine's baseline new.
+  
+  Capture stops handing this to Playwright to fail on. Both screenshot paths used
+  to refuse a zero-area subject in terms of their own arguments — the clip path
+  with `Expected options.clip.height to be greater than 0`, the element path by
+  spending the full actionability timeout and then complaining about visibility —
+  so a reader had a component that rendered nothing and a sentence about a
+  rectangle. `captureSubject` decides it now, and the renderer names the subject.
+  
+  **Operators:** this is schema **18**. `baselines` and `render_cache` drop
+  `NOT NULL` from `width` and `height`, shipped as `0016_pixel-less-baselines.sql`.
+  Apply it before pointing a CLI of this version at the deployment; `GET /version`
+  reports the schema a build expects.
+- f4b328b: A run leaves behind what its suite looked like, in bytes another checkout can read
+  
+  A run report answers about *this run*. Nothing answered about the suite from
+  somewhere else: which components exist, which subjects hold them, which of them
+  has an example of its own, and every name the run indexed. A branch asking any
+  of that against `main` had nothing to ask, because `main`'s answers were computed
+  on a machine that has since gone away — which is why *this component is not
+  covered anywhere* was a question with no reader, and why a second run could only
+  re-derive what the first already knew.
+  
+  `@variance-authority/report/suite-index` is that artifact. `suiteIndexOf` takes
+  the baseline-bearing half of a report — the census, the subject denominator it is
+  counted against, and the lexicon — and `encodeSuiteIndex` writes it as one
+  segment, with `readSuiteIndex` and `writeSuiteIndex` beside the report's own file
+  functions. The other half of a composition does not travel: `movements` is what
+  moved since a comparison nobody else made, and `divergences` and `echoes` are
+  readings of one commit's snapshots. None of the three is a fact about the suite.
+  
+  It carries the commit it was written at and nothing else about where it is, which
+  is the rule the selection index already settled — a commit answers *what changed
+  since this was written* exactly, and a timestamp says when a machine was rather
+  than where a tree was. An index that cannot name itself is the honest record of a
+  run that could not, and a reader holding one has nothing to diff.
+  
+  It is not JSON. A lexicon is the same few thousand strings written once per
+  subject that holds them, and in JSON the repetition *is* the payload. Interned
+  once and referenced by number it stops being one, and equal facts encode to equal
+  bytes — a sorted dictionary, so a cache that keys on content actually hits.
+  
+  `@variance-authority/core/segment` is the arithmetic underneath: named columns,
+  alignment, interned strings, and the validation a decode performs before it
+  believes a file. A column's width comes from the array's own type, so a mismatch
+  is a compile error rather than a decode against the wrong stride, and a malformed
+  reference rejects the whole file — a segment is a cache or a baseline, both of
+  which may be rebuilt, and half of either is worse than neither. The source index
+  now reads and writes through it and keeps its own bytes; what it still owns is the
+  part that is about source.
+- e546e21: Two readings of two places are not a flake
+  
+  `flake` is an accusation — *this reading is not repeatable* — and it was being
+  made about a comparison that never claimed repeatability. Lifting two instances
+  out of two subjects at one commit and parting them produces a case where every
+  input agrees, the tree holds, and the output moved; the old table had exactly one
+  row for that.
+  
+  Where a component sits is decided by the boxes around it, and no component
+  receives its own position as a prop. Two instances that agreed on everything they
+  were handed and landed at different coordinates have contradicted nothing.
+  
+  `partingOf` takes a `PartingPlace`: `same` for one subject read twice, across
+  revisions or across two moments of one scenario, and `elsewhere` for two
+  instances at one commit. It decides only between `flake` and the new `placed`
+  rung and slice, and it defaults to `same`, which is what every comparison across
+  revisions is. `divergencesOf` is the one caller that says `elsewhere`. The
+  sentence points outwards, at what put the component there, rather than at the
+  component.
+
+### Patch Changes
+
+- e546e21: Four ways a large unit tier lost subjects, none of which said so
+  
+  **The styling was gone before the capture looked.** A capture taken from a setup
+  file runs in the outermost `afterEach` a run has; every hook registered inside a
+  `describe` has already finished, and `onTestFinished` runs later still. CSS-in-JS
+  teardown lives in exactly those inner hooks — emotion's test renderer removes each
+  `<style>` tag it inserted — so the capture read the page with the styling taken
+  back off it. The class names were all still in the markup, they matched nothing,
+  and every subject captured, compared and passed against a photograph of unstyled
+  DOM. Measured on Material UI's unit tier: 399 of 400 captures carried no CSS at
+  all, and 1201 subjects laid out to zero height because nothing was sizing them.
+  `retainStyles` records style elements as they are inserted and puts the removed
+  ones back, in insertion order, for the length of one capture. The next test still
+  gets a clean page.
+  
+  **A subject id can be longer than a filename.** A suite that names subjects after
+  the test that produced them — a file path and a full test name — passes 255 bytes
+  on ordinary tests, and the point of that convention is that the id says where the
+  subject came from. `fileNameFor` in core is now the one rule: a readable prefix,
+  plus a digest of the whole id when the id does not fit, because truncation alone
+  merges two tests into one file. The baseline store, the capture archive, the
+  CLI's image directory, the Playwright evidence directory and the Eyes journal all
+  use it; before this, each was one long subject id away from a raw `ENAMETOOLONG`
+  that never mentions a subject. `@variance-authority/eyes` declares
+  `@variance-authority/core` directly rather than reaching it through `react` — the
+  host stacks it keeps optional are Playwright and Testing Library, and a filename
+  rule is not one of them.
+  
+  **An inline `url()` is spelled in entities.** `style="background-image:url(&quot;/a.png&quot;)"`
+  reaches the scan through HTML serialization, and reading it literally asked the
+  caller for bytes at a URL that exists nowhere but in the escaping. The HTML half
+  is scanned with the attribute's entities undone; the stylesheet half, which was
+  never escaped, is scanned as before.
+  
+  **A stubbed `getComputedStyle` is not a broken asset scan.** Replacing
+  `window.getComputedStyle` with a map of the two properties a component reads is
+  the only way to drive some layouts in jsdom. The scan called `getPropertyValue`
+  on the plain object it got back, and every test in the file died on a `TypeError`
+  raised four frames below anything you wrote. There is nothing to scan and nothing
+  to complain about — whatever those styles would have named, the stub already
+  removed from the page. The attributes on the element are still read.
+
+## 0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -26,11 +26,14 @@ input is a PNG.
 
 ## Entrypoints
 
-Seven groups. Five of them are the order an answer travels through; `core/plan`
+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. The default entrypoint is all
-seven and is what most callers want.
+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.
 
 | entrypoint | holds |
 |---|---|
@@ -41,6 +44,8 @@ seven and is what most callers want.
 | `core/judge` | policy: verdicts, intent claims, ignores, the docket a reader is handed |
 | `core/plan` | the whole configuration of a run — profile, ruleset version, viewport, policy, interventions — as one value, plus the identity digest derived from it |
 | `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, 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
@@ -58,7 +63,7 @@ which baselines the run can see.
 
 ## Comparison and policy
 
-`compare` says **what moved**. `judge` says **whether anyone should mind**.
+`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
@@ -74,7 +79,8 @@ Value comparison needs no host setup and returns paths and fingerprints, not a
 pass/fail verdict:
 
 ```ts
-import { compareValues, shapeValue } from '@variance-authority/core';
+import { compareValues } from '@variance-authority/core/compare';
+import { shapeValue } from '@variance-authority/core/format';
 
 const before = shapeValue({ rows: [{ id: 'a', total: 10 }] }, {
   arrayKey: { '/rows': 'id' },
@@ -90,7 +96,9 @@ console.log(deltas[0]?.pointer);                     // /rows/a/total
 For a rendered subject, the same package receives captures from a collector:
 
 ```ts
-import { attributeRegions, diffSnapshots, isolateRegions, normalize } from '@variance-authority/core';
+import { attributeRegions, isolateRegions } from '@variance-authority/core/attribute';
+import { diffSnapshots } from '@variance-authority/core/compare';
+import { normalize } from '@variance-authority/core/rules';
 
 const before = normalize(capture);                   // supplied by a collector
 const after = normalize(recapture);
@@ -106,7 +114,7 @@ returns semantic roots and, when a raster mask is supplied, regions attributed t
 the candidate snapshot. A caller still chooses policy and a verdict in
 `core/judge` or in its own runner.
 
-`scale` is device pixels per CSS pixel, it is **required**, and it has no default
+`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.
@@ -119,7 +127,9 @@ The options that change scope are explicit at the call site:
 | `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 |
 | `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 and `through` selects graph edge kinds |
+| `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 |
+| `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 |
 
@@ -133,7 +143,8 @@ carrying a JSON Pointer and a fingerprint, and — like everything else here —
 verdict.
 
 ```ts
-import { shapeValue, compareValues } from '@variance-authority/core';
+import { compareValues } from '@variance-authority/core/compare';
+import { shapeValue } from '@variance-authority/core/format';
 
 const baseline = shapeValue(before, { arrayKey: { '/rows': 'id' } });
 const deltas = compareValues(baseline, shapeValue(after, { arrayKey: { '/rows': 'id' } }));
@@ -154,6 +165,37 @@ in the record that the next run reads as removed.
 
 Rendered comparisons also throw when the subjects or observation profiles differ.
 
+## Handing an answer to another machine
+
+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:
+
+```ts
+import { httpShare, shareKey } from '@variance-authority/core/share';
+
+const share = httpShare({
+  endpoint: 'https://objects.example.com/variance',
+  headers: { authorization: `Bearer ${token}` },
+  method: 'PUT',
+});
+
+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;
+`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.
+
+**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.
+
 ## What it refuses
 
 **Absent is not empty.** Not measured, measured as zero, and unobservable are

package/dist/attribute/closure.d.ts

@@ -0,0 +1,105 @@
+import { type Digest } from '../format/hash.js';
+import type { NodePath, SemanticNode } from '../format/snapshot.js';
+/**
+ * A digest per node over everything under it, on the document tree.
+ *
+ * The component hash deliberately is not this. It covers a component's own
+ * nodes and names a hole where a child sits, so that an edit stays local and
+ * the page root does not move on every commit. The price is a sentence no such
+ * digest can say: *this whole subtree, to the leaf, is the one on three other
+ * pages*. A closure says exactly that, and it is content-addressed the way a
+ * fingerprint is — position removed, so the same bytes at two paths in two
+ * subjects are one key — which is what lets *where else is this* become a
+ * lookup rather than a comparison.
+ *
+ * Two closures per node, at two grains of the same tree. `structure` is the
+ * tag and the children's structure closures and nothing else: the join key,
+ * because two subtrees with different shapes have nothing further to compare.
+ * `semantics` is the same walk carrying what the semantics band keeps for each
+ * node — role, accessible name, state, the surviving attributes, the text — and
+ * it qualifies a match rather than making one.
+ *
+ * ## What an id contributes
+ *
+ * An identical widget with a different generated id is the case this tree is
+ * for, so an id contributes its presence and never its value. A reference to
+ * one is a fact about a *pair* of nodes, and it enters the closure of the
+ * lowest node holding both — as the two paths relative to that node, which is
+ * position-free with respect to everything outside it. A label and the input
+ * it names read the same on every page; a label naming something outside the
+ * subtree stays an unbound reference at every closure up to the one that
+ * contains its target, and at the root if nothing does.
+ *
+ * That is the one place a closure cannot be a plain fold of its children's
+ * digests: whether a reference is bound is not a property of the node carrying
+ * it. So each subtree also carries up what it defines and what it has not yet
+ * resolved, and a binding is hashed once, where it closes.
+ *
+ * ## What enters no closure
+ *
+ * Style, geometry, tokens, wiring, holding, provenance. A closure is a
+ * statement about what was rendered, and it is computed by a run over what it
+ * already collected — it enters no baseline and no stored digest.
+ */
+export interface NodeClosure {
+    readonly path: NodePath;
+    readonly tag: string;
+    /** Tag and the children's structure closures, nothing else. */
+    readonly structure: Digest;
+    /** The structure walk, carrying what the semantics band keeps per node. */
+    readonly semantics: Digest;
+    /** Nodes under this one, itself included. */
+    readonly nodes: number;
+}
+/** One closure per node, in document order. */
+export declare function nodeClosures(root: SemanticNode): readonly NodeClosure[];
+/** One subject's document tree, named. */
+export interface SubjectTree {
+    readonly subject: string;
+    readonly root: SemanticNode;
+}
+export interface ClosureSite {
+    readonly subject: string;
+    readonly path: NodePath;
+}
+/**
+ * One structure closure that recurs across subjects, at the shallowest node
+ * where it does.
+ */
+export interface SharedClosure {
+    readonly structure: Digest;
+    readonly tag: string;
+    /** Nodes under each site, the site included; every site has the same count. */
+    readonly nodes: number;
+    /** Sorted by subject, then path. Spans at least two subjects. */
+    readonly sites: readonly ClosureSite[];
+    /**
+     * `held` when every site agrees on the semantics closure too — the same
+     * shape with the same content. `parted` is the same shape carrying different
+     * content, which is what the two grains exist to keep apart.
+     */
+    readonly semantics: 'held' | 'parted';
+}
+export interface SharedClosureOptions {
+    /**
+     * The smallest subtree worth reporting, in nodes. A shared `<span>` is true
+     * and says nothing; the floor is the report's to choose, and absent means
+     * every size.
+     */
+    readonly floor?: number;
+}
+/**
+ * Every structure closure that recurs in more than one subject, reported once
+ * and at its widest.
+ *
+ * The two-subject rule is composition's: three identical rows in one list say
+ * nothing, and the same rows in two subjects say that two diffs are one review.
+ *
+ * A site is dropped when its parent recurs over exactly the same partners — the
+ * rule that makes an echo's example the shallowest boundary, applied to every
+ * node. A whole page rendered twice is one entry at the root, not one per
+ * element. A subtree that recurs in *more* places than its parent does is kept,
+ * because the extra places are the finding.
+ */
+export declare function sharedClosures(subjects: readonly SubjectTree[], options?: SharedClosureOptions): readonly SharedClosure[];
+//# sourceMappingURL=closure.d.ts.map

package/dist/attribute/closure.js

@@ -0,0 +1,180 @@
+import { digestCombine, digestString, digestValue } from '../format/hash.js';
+import { ID_REFERENCE_ATTRIBUTES, ID_REFERENCE_LIST_ATTRIBUTES } from '../rules/ruleset.js';
+/** One closure per node, in document order. */
+export function nodeClosures(root) {
+    const found = [];
+    const flatten = (closed) => {
+        found.push(closed.closure);
+        for (const child of closed.children)
+            flatten(child);
+    };
+    flatten(close(root));
+    return found;
+}
+/**
+ * Every structure closure that recurs in more than one subject, reported once
+ * and at its widest.
+ *
+ * The two-subject rule is composition's: three identical rows in one list say
+ * nothing, and the same rows in two subjects say that two diffs are one review.
+ *
+ * A site is dropped when its parent recurs over exactly the same partners — the
+ * rule that makes an echo's example the shallowest boundary, applied to every
+ * node. A whole page rendered twice is one entry at the root, not one per
+ * element. A subtree that recurs in *more* places than its parent does is kept,
+ * because the extra places are the finding.
+ */
+export function sharedClosures(subjects, options = {}) {
+    const index = new Map();
+    const file = (subject, closed, parent) => {
+        const { closure } = closed;
+        let entry = index.get(closure.structure);
+        if (entry === undefined) {
+            entry = { tag: closure.tag, nodes: closure.nodes, sites: [] };
+            index.set(closure.structure, entry);
+        }
+        entry.sites.push({ subject, path: closure.path, semantics: closure.semantics, parent });
+        const here = { structure: closure.structure, site: `${subject}\u0000${closure.path}` };
+        for (const child of closed.children)
+            file(subject, child, here);
+    };
+    for (const { subject, root } of subjects)
+        file(subject, close(root), undefined);
+    const shared = [];
+    for (const [structure, entry] of index) {
+        if (entry.nodes < (options.floor ?? 0))
+            continue;
+        if (new Set(entry.sites.map((site) => site.subject)).size < 2)
+            continue;
+        if (subsumed(entry, index))
+            continue;
+        const sites = entry.sites
+            .map(({ subject, path }) => ({ subject, path }))
+            .sort((left, right) => codeUnitOrder(left.subject, right.subject) || codeUnitOrder(left.path, right.path));
+        const held = new Set(entry.sites.map((site) => site.semantics)).size === 1;
+        shared.push({ structure, tag: entry.tag, nodes: entry.nodes, sites, semantics: held ? 'held' : 'parted' });
+    }
+    return shared.sort((left, right) => codeUnitOrder(left.structure, right.structure));
+}
+/**
+ * Whether every site sits under one recurring parent, and that parent recurs
+ * nowhere else. Two identical rows under one `<tbody>` are one parent site, so
+ * the parents are counted distinct: the rows are subsumed by the body, and the
+ * body by the table above it, up to the node that recurs on its own.
+ */
+function subsumed(entry, index) {
+    const first = entry.sites[0]?.parent;
+    if (first === undefined)
+        return false;
+    const parents = new Set();
+    for (const site of entry.sites) {
+        if (site.parent === undefined || site.parent.structure !== first.structure)
+            return false;
+        parents.add(site.parent.site);
+    }
+    return index.get(first.structure)?.sites.length === parents.size;
+}
+function close(node) {
+    const children = node.children.map((child) => close(child));
+    const defined = new Map();
+    if (node.alias !== undefined)
+        defined.set(node.alias, '');
+    children.forEach((child, index) => {
+        for (const [alias, path] of child.defined)
+            defined.set(alias, under(index, path));
+    });
+    const bindings = [];
+    const unbound = [];
+    const settle = (reference) => {
+        const to = defined.get(reference.alias);
+        if (to === undefined)
+            unbound.push(reference);
+        else
+            bindings.push({ attribute: reference.attribute, from: reference.from, to });
+    };
+    for (const reference of referencesOf(node))
+        settle(reference);
+    children.forEach((child, index) => {
+        for (const reference of child.unbound)
+            settle({ ...reference, from: under(index, reference.from) });
+    });
+    bindings.sort((left, right) => codeUnitOrder(left.from, right.from) ||
+        codeUnitOrder(left.attribute, right.attribute) ||
+        codeUnitOrder(left.to, right.to));
+    let nodes = 1;
+    for (const child of children)
+        nodes += child.closure.nodes;
+    const structure = digestCombine('closure:structure', [
+        digestString(node.tag),
+        ...children.map((child) => child.closure.structure),
+    ]);
+    const semantics = digestCombine('closure:semantics', [
+        digestValue({ own: ownSemantics(node), bindings }),
+        ...children.map((child) => child.closure.semantics),
+    ]);
+    return {
+        closure: { path: node.path, tag: node.tag, structure, semantics, nodes },
+        children,
+        defined,
+        unbound,
+    };
+}
+/** A relative path one level down: the child's index, then the path beneath it. */
+function under(index, path) {
+    return path === '' ? String(index) : `${index}/${path}`;
+}
+const REFERENCE = new Set(ID_REFERENCE_ATTRIBUTES);
+const REFERENCE_LIST = new Set(ID_REFERENCE_LIST_ATTRIBUTES);
+/** What normalization turned an id into; an `extern:` alias lies outside every subtree. */
+const ALIAS = /^#(?:a\d+|extern:.*)$/;
+/**
+ * What the semantics band keeps for one node, with every id reduced to
+ * presence. `null` rather than omitted where a node has nothing, for the reason
+ * every band gives: an omitted entry lets two different nodes agree by
+ * coincidence.
+ */
+function ownSemantics(node) {
+    const attributes = {};
+    for (const [name, value] of Object.entries(node.attributes)) {
+        attributes[name] = isReference(name) ? withoutAliases(value) : value;
+    }
+    return {
+        tag: node.tag,
+        id: node.alias !== undefined,
+        role: node.role ?? null,
+        name: node.name ?? null,
+        state: (node.state ?? null),
+        attributes,
+        text: node.text ?? null,
+    };
+}
+/** Every alias this node refers to, each as a reference from the node itself. */
+function referencesOf(node) {
+    const found = [];
+    for (const [attribute, value] of Object.entries(node.attributes)) {
+        if (!isReference(attribute))
+            continue;
+        for (const alias of aliasesIn(attribute, value))
+            found.push({ attribute, alias, from: '' });
+    }
+    return found;
+}
+function isReference(name) {
+    return REFERENCE.has(name) || name === 'href' || name === 'xlink:href';
+}
+function aliasesIn(name, value) {
+    const parts = REFERENCE_LIST.has(name) ? value.split(/\s+/) : [value];
+    return parts.filter((part) => ALIAS.test(part));
+}
+/** The attribute with each alias replaced by a marker, so the binding carries the pair and the value does not. */
+function withoutAliases(value) {
+    return value
+        .split(/\s+/)
+        .map((part) => (ALIAS.test(part) ? '#' : part))
+        .join(' ');
+}
+/** The order every other list in this package is sorted by. */
+function codeUnitOrder(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+//# sourceMappingURL=closure.js.map

package/dist/attribute/closure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closure.js","sourceRoot":"","sources":["../../src/attribute/closure.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CanonicalValue } from '../format/canonical.js';\nimport { digestCombine, digestString, digestValue, type Digest } from '../format/hash.js';\nimport type { NodePath, SemanticNode } from '../format/snapshot.js';\nimport { ID_REFERENCE_ATTRIBUTES, ID_REFERENCE_LIST_ATTRIBUTES } from '../rules/ruleset.js';\n\n/**\n * A digest per node over everything under it, on the document tree.\n *\n * The component hash deliberately is not this. It covers a component's own\n * nodes and names a hole where a child sits, so that an edit stays local and\n * the page root does not move on every commit. The price is a sentence no such\n * digest can say: *this whole subtree, to the leaf, is the one on three other\n * pages*. A closure says exactly that, and it is content-addressed the way a\n * fingerprint is — position removed, so the same bytes at two paths in two\n * subjects are one key — which is what lets *where else is this* become a\n * lookup rather than a comparison.\n *\n * Two closures per node, at two grains of the same tree. `structure` is the\n * tag and the children's structure closures and nothing else: the join key,\n * because two subtrees with different shapes have nothing further to compare.\n * `semantics` is the same walk carrying what the semantics band keeps for each\n * node — role, accessible name, state, the surviving attributes, the text — and\n * it qualifies a match rather than making one.\n *\n * ## What an id contributes\n *\n * An identical widget with a different generated id is the case this tree is\n * for, so an id contributes its presence and never its value. A reference to\n * one is a fact about a *pair* of nodes, and it enters the closure of the\n * lowest node holding both — as the two paths relative to that node, which is\n * position-free with respect to everything outside it. A label and the input\n * it names read the same on every page; a label naming something outside the\n * subtree stays an unbound reference at every closure up to the one that\n * contains its target, and at the root if nothing does.\n *\n * That is the one place a closure cannot be a plain fold of its children's\n * digests: whether a reference is bound is not a property of the node carrying\n * it. So each subtree also carries up what it defines and what it has not yet\n * resolved, and a binding is hashed once, where it closes.\n *\n * ## What enters no closure\n *\n * Style, geometry, tokens, wiring, holding, provenance. A closure is a\n * statement about what was rendered, and it is computed by a run over what it\n * already collected — it enters no baseline and no stored digest.\n */\nexport interface NodeClosure {\n  readonly path: NodePath;\n  readonly tag: string;\n  /** Tag and the children's structure closures, nothing else. */\n  readonly structure: Digest;\n  /** The structure walk, carrying what the semantics band keeps per node. */\n  readonly semantics: Digest;\n  /** Nodes under this one, itself included. */\n  readonly nodes: number;\n}\n\n/** One closure per node, in document order. */\nexport function nodeClosures(root: SemanticNode): readonly NodeClosure[] {\n  const found: NodeClosure[] = [];\n  const flatten = (closed: Closed): void => {\n    found.push(closed.closure);\n    for (const child of closed.children) flatten(child);\n  };\n  flatten(close(root));\n  return found;\n}\n\n/** One subject's document tree, named. */\nexport interface SubjectTree {\n  readonly subject: string;\n  readonly root: SemanticNode;\n}\n\nexport interface ClosureSite {\n  readonly subject: string;\n  readonly path: NodePath;\n}\n\n/**\n * One structure closure that recurs across subjects, at the shallowest node\n * where it does.\n */\nexport interface SharedClosure {\n  readonly structure: Digest;\n  readonly tag: string;\n  /** Nodes under each site, the site included; every site has the same count. */\n  readonly nodes: number;\n  /** Sorted by subject, then path. Spans at least two subjects. */\n  readonly sites: readonly ClosureSite[];\n  /**\n   * `held` when every site agrees on the semantics closure too — the same\n   * shape with the same content. `parted` is the same shape carrying different\n   * content, which is what the two grains exist to keep apart.\n   */\n  readonly semantics: 'held' | 'parted';\n}\n\nexport interface SharedClosureOptions {\n  /**\n   * The smallest subtree worth reporting, in nodes. A shared `<span>` is true\n   * and says nothing; the floor is the report's to choose, and absent means\n   * every size.\n   */\n  readonly floor?: number;\n}\n\n/**\n * Every structure closure that recurs in more than one subject, reported once\n * and at its widest.\n *\n * The two-subject rule is composition's: three identical rows in one list say\n * nothing, and the same rows in two subjects say that two diffs are one review.\n *\n * A site is dropped when its parent recurs over exactly the same partners — the\n * rule that makes an echo's example the shallowest boundary, applied to every\n * node. A whole page rendered twice is one entry at the root, not one per\n * element. A subtree that recurs in *more* places than its parent does is kept,\n * because the extra places are the finding.\n */\nexport function sharedClosures(\n  subjects: readonly SubjectTree[],\n  options: SharedClosureOptions = {},\n): readonly SharedClosure[] {\n  const index = new Map<Digest, Entry>();\n\n  const file = (subject: string, closed: Closed, parent: Parent | undefined): void => {\n    const { closure } = closed;\n    let entry = index.get(closure.structure);\n    if (entry === undefined) {\n      entry = { tag: closure.tag, nodes: closure.nodes, sites: [] };\n      index.set(closure.structure, entry);\n    }\n    entry.sites.push({ subject, path: closure.path, semantics: closure.semantics, parent });\n    const here = { structure: closure.structure, site: `${subject}\\u0000${closure.path}` };\n    for (const child of closed.children) file(subject, child, here);\n  };\n\n  for (const { subject, root } of subjects) file(subject, close(root), undefined);\n\n  const shared: SharedClosure[] = [];\n  for (const [structure, entry] of index) {\n    if (entry.nodes < (options.floor ?? 0)) continue;\n    if (new Set(entry.sites.map((site) => site.subject)).size < 2) continue;\n    if (subsumed(entry, index)) continue;\n\n    const sites = entry.sites\n      .map(({ subject, path }) => ({ subject, path }))\n      .sort((left, right) => codeUnitOrder(left.subject, right.subject) || codeUnitOrder(left.path, right.path));\n    const held = new Set(entry.sites.map((site) => site.semantics)).size === 1;\n\n    shared.push({ structure, tag: entry.tag, nodes: entry.nodes, sites, semantics: held ? 'held' : 'parted' });\n  }\n\n  return shared.sort((left, right) => codeUnitOrder(left.structure, right.structure));\n}\n\ninterface Parent {\n  readonly structure: Digest;\n  /** Subject and path, so that two rows under one parent count that parent once. */\n  readonly site: string;\n}\n\ninterface Entry {\n  readonly tag: string;\n  readonly nodes: number;\n  readonly sites: {\n    readonly subject: string;\n    readonly path: NodePath;\n    readonly semantics: Digest;\n    readonly parent: Parent | undefined;\n  }[];\n}\n\n/**\n * Whether every site sits under one recurring parent, and that parent recurs\n * nowhere else. Two identical rows under one `<tbody>` are one parent site, so\n * the parents are counted distinct: the rows are subsumed by the body, and the\n * body by the table above it, up to the node that recurs on its own.\n */\nfunction subsumed(entry: Entry, index: ReadonlyMap<Digest, Entry>): boolean {\n  const first = entry.sites[0]?.parent;\n  if (first === undefined) return false;\n  const parents = new Set<string>();\n  for (const site of entry.sites) {\n    if (site.parent === undefined || site.parent.structure !== first.structure) return false;\n    parents.add(site.parent.site);\n  }\n  return index.get(first.structure)?.sites.length === parents.size;\n}\n\ninterface Closed {\n  readonly closure: NodeClosure;\n  readonly children: readonly Closed[];\n  /** Alias → path relative to this node, for every id defined in this subtree. */\n  readonly defined: ReadonlyMap<string, string>;\n  /** References made in this subtree whose target is not in it. */\n  readonly unbound: readonly Reference[];\n}\n\ninterface Reference {\n  readonly attribute: string;\n  readonly alias: string;\n  /** Path of the referring node, relative to the subtree carrying this. */\n  readonly from: string;\n}\n\n/** A reference and its target, as two paths relative to the node they close under. */\ntype Binding = {\n  readonly attribute: string;\n  readonly from: string;\n  readonly to: string;\n};\n\nfunction close(node: SemanticNode): Closed {\n  const children = node.children.map((child) => close(child));\n\n  const defined = new Map<string, string>();\n  if (node.alias !== undefined) defined.set(node.alias, '');\n  children.forEach((child, index) => {\n    for (const [alias, path] of child.defined) defined.set(alias, under(index, path));\n  });\n\n  const bindings: Binding[] = [];\n  const unbound: Reference[] = [];\n  const settle = (reference: Reference): void => {\n    const to = defined.get(reference.alias);\n    if (to === undefined) unbound.push(reference);\n    else bindings.push({ attribute: reference.attribute, from: reference.from, to });\n  };\n  for (const reference of referencesOf(node)) settle(reference);\n  children.forEach((child, index) => {\n    for (const reference of child.unbound) settle({ ...reference, from: under(index, reference.from) });\n  });\n  bindings.sort(\n    (left, right) =>\n      codeUnitOrder(left.from, right.from) ||\n      codeUnitOrder(left.attribute, right.attribute) ||\n      codeUnitOrder(left.to, right.to),\n  );\n\n  let nodes = 1;\n  for (const child of children) nodes += child.closure.nodes;\n\n  const structure = digestCombine('closure:structure', [\n    digestString(node.tag),\n    ...children.map((child) => child.closure.structure),\n  ]);\n  const semantics = digestCombine('closure:semantics', [\n    digestValue({ own: ownSemantics(node), bindings }),\n    ...children.map((child) => child.closure.semantics),\n  ]);\n\n  return {\n    closure: { path: node.path, tag: node.tag, structure, semantics, nodes },\n    children,\n    defined,\n    unbound,\n  };\n}\n\n/** A relative path one level down: the child's index, then the path beneath it. */\nfunction under(index: number, path: string): string {\n  return path === '' ? String(index) : `${index}/${path}`;\n}\n\nconst REFERENCE = new Set(ID_REFERENCE_ATTRIBUTES);\nconst REFERENCE_LIST = new Set(ID_REFERENCE_LIST_ATTRIBUTES);\n/** What normalization turned an id into; an `extern:` alias lies outside every subtree. */\nconst ALIAS = /^#(?:a\\d+|extern:.*)$/;\n\n/**\n * What the semantics band keeps for one node, with every id reduced to\n * presence. `null` rather than omitted where a node has nothing, for the reason\n * every band gives: an omitted entry lets two different nodes agree by\n * coincidence.\n */\nfunction ownSemantics(node: SemanticNode): CanonicalValue {\n  const attributes: Record<string, string> = {};\n  for (const [name, value] of Object.entries(node.attributes)) {\n    attributes[name] = isReference(name) ? withoutAliases(value) : value;\n  }\n  return {\n    tag: node.tag,\n    id: node.alias !== undefined,\n    role: node.role ?? null,\n    name: node.name ?? null,\n    state: (node.state ?? null) as CanonicalValue,\n    attributes,\n    text: node.text ?? null,\n  };\n}\n\n/** Every alias this node refers to, each as a reference from the node itself. */\nfunction referencesOf(node: SemanticNode): readonly Reference[] {\n  const found: Reference[] = [];\n  for (const [attribute, value] of Object.entries(node.attributes)) {\n    if (!isReference(attribute)) continue;\n    for (const alias of aliasesIn(attribute, value)) found.push({ attribute, alias, from: '' });\n  }\n  return found;\n}\n\nfunction isReference(name: string): boolean {\n  return REFERENCE.has(name) || name === 'href' || name === 'xlink:href';\n}\n\nfunction aliasesIn(name: string, value: string): readonly string[] {\n  const parts = REFERENCE_LIST.has(name) ? value.split(/\\s+/) : [value];\n  return parts.filter((part) => ALIAS.test(part));\n}\n\n/** The attribute with each alias replaced by a marker, so the binding carries the pair and the value does not. */\nfunction withoutAliases(value: string): string {\n  return value\n    .split(/\\s+/)\n    .map((part) => (ALIAS.test(part) ? '#' : part))\n    .join(' ');\n}\n\n/** The order every other list in this package is sorted by. */\nfunction codeUnitOrder(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0;\n}\n"]}