@variance-authority/presentation 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# @variance-authority/presentation
+
+## 0.1.0
+
+### Minor Changes
+
+- 5b2a28f: Carry the caller-established font identities onto the presentation report.
+  
+  `sensePresentation` accepted a `fonts` option, threaded it into the capture it
+  builds, then analyzed that capture and dropped it — so through the live door the
+  option had no observable consequence: three different font lists produced a
+  byte-identical report. The report now carries them, from the capture, so the
+  pure entry point answers the same way.
+  
+  Fonts are a render input of the more consequential kind — a substitution moves
+  every metric on the page without changing a byte of code — so the identities
+  participate in `digest` and a reading taken under different ones is a different
+  reading. `contentDigest` is untouched: content identity is what has to survive
+  presentation moving. Absent rather than empty when none were established, and
+  sorted, because the order a caller listed them in is not part of their identity.
+
+### Patch Changes
+
+- Updated dependencies [1d402d1]
+- Updated dependencies [f800342]
+- Updated dependencies [26ae9ed]
+- Updated dependencies [e8fee66]
+- Updated dependencies [5c34e6d]
+  - @variance-authority/report@0.1.0
+  - @variance-authority/dom@0.1.0
+  - @variance-authority/react@0.1.0
+  - @variance-authority/core@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machine Garden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+<p align="center"><img src="./mark.svg" alt="Variance Authority mark" width="72"></p>
+
+# @variance-authority/presentation
+
+> Sense spacing, alignment, prominence and repetition inside one live interface, as evidence an agent can read.
+
+Sense one rendered subject and return a machine-readable presentation graph. The
+report keeps semantic anchors attached to concrete element references, measures
+geometry and presentation relationships, and exposes deterministic collapse (the
+gap that should separate repeated instances, or the size difference that should
+separate a heading from body text, disappearing) and drift (one instance's
+position, baseline, or presentation diverging from the dominant pattern) —
+without recommending a layout or assigning a UI quality score.
+
+It reads a `RawCapture` — a normalized, serializable snapshot of one rendered DOM
+subject, produced by a collector such as this package's Playwright entry point.
+The layout-derived evidence arrives only when that capture's profile — a
+declaration of what its collector could observe (ARIA, style, layout, pixels) —
+includes computed style and layout.
+
+This is a sensing and support surface, not a visual-regression assertion. It does
+not create a baseline, approve a change, or produce a pass/fail verdict; pair it
+with `@variance-authority/report` (or another comparison layer) when a run needs
+one.
+
+```bash
+npm install --save-dev @variance-authority/presentation @playwright/test
+npx playwright install chromium
+```
+
+## Sense once, then choose the structural owner
+
+```ts
+import type { Page } from '@playwright/test';
+import { focusPresentation } from '@variance-authority/presentation';
+import { sensePresentation } from '@variance-authority/presentation/playwright';
+
+declare const page: Page;
+
+const report = await sensePresentation(page, page.getByRole('main'));
+const pattern = report.patterns?.find((candidate) => candidate.instances.length >= 3);
+if (pattern === undefined) throw new Error('the subject has no repeated presentation pattern');
+
+const ownerReading = focusPresentation(report, pattern.parent, {
+  paint: ['repetition', 'findings'],
+});
+
+console.log(ownerReading.owner, ownerReading.findings, ownerReading.nested);
+```
+
+Playwright supplies the live layout and its ARIA snapshot. The browser agent
+can paint from the same report it returns, but acquisition is normally left
+unpainted. Its default settlement — the waits, for fonts, images, and
+animations, that hold a page still before it is measured — covers images inside
+the subject and its React portals, not unrelated images elsewhere in the
+document.
+`focusPresentation` reads one owner from that report without touching
+the page again. Its default `owner` depth includes the owner and its immediate
+children; evidence owned by nested boxes is counted in `nested` rather than
+folded into the current reading. Use `depth: 'subtree'` only when the product
+question deliberately treats the complete composition as one subject.
+
+Focus options are `depth`, `paint`, and `findings`. `depth` defaults to `owner`;
+`paint` limits retained layers; `findings` limits the reading to report-local
+finding ids owned at the selected depth.
+
+Every finding — a detected rule violation such as `SEPARATION_COLLISION`, tying
+specific graph nodes to a measurement — has a stable report-local `id` and the
+graph-node `owner` whose relationship produced it. Pass `findings: [id]` to
+isolate one question. Paint that focused evidence without another acquisition:
+
+```ts
+import type { Page } from '@playwright/test';
+import { focusPresentation, type PresentationReport } from '@variance-authority/presentation';
+import { paintPresentationFocus } from '@variance-authority/presentation/playwright';
+
+declare const page: Page;
+declare const report: PresentationReport;
+
+const finding = report.findings?.[0];
+if (finding !== undefined) {
+  const isolated = focusPresentation(report, finding.owner, {
+    findings: [finding.id],
+    paint: ['findings'],
+  });
+  await paintPresentationFocus(page, isolated);
+}
+```
+
+Call `clearPresentationPaint(page)` to remove the overlay. No ARIA, or a partial
+ARIA tree with no parent or children, remains an observed value rather than an
+acquisition error.
+
+`subjectId` and `title` identify the sensed boundary in the returned report.
+`fonts` records the browser fonts whose identities the caller has established;
+the report carries them back, and a substitution changes its digest while
+content identity — a digest of semantic classes, names, text, state, and the
+browser ARIA reading, independent of layout — holds.
+`suspense` controls settlement of React boundaries before sensing. `paint` is
+either `true` for every diagnostic layer (`semantic`, `spacing`, `axes`,
+`baselines`, `surfaces`, `prominence`, `repetition`, `findings`) or a list of
+named layers; omitting it leaves the page unpainted.
+
+`stabilize` replaces the default collection recipe by intervention id. Pass an
+empty list only for a caller-owned static document such as an MHTML archive whose
+page clock cannot advance; a live page normally needs the default recipe.
+
+Use the pure entry point below when another collector already supplies a
+`RawCapture`.
+
+## Inspect a visual flow across nested boxes
+
+Use this when peers — a brand mark and navigation controls, say — live in
+different DOM wrappers but should be read as one visual flow: select their graph
+node ids explicitly. A node id encodes a path from a capture root, so
+`r0:0/1/2` is capture root `0`, its child `1`, and that child's child `2`; get
+real ids from `report.graph.nodes` rather than hardcoding them as this example
+does:
+
+```ts
+import type { Page } from '@playwright/test';
+import {
+  inspectPresentationAlignment,
+  type PresentationReport,
+} from '@variance-authority/presentation';
+import { paintPresentationAlignment } from '@variance-authority/presentation/playwright';
+
+declare const page: Page;
+declare const report: PresentationReport;
+
+const reading = inspectPresentationAlignment(
+  report,
+  'r0:0',
+  ['r0:0/0/0', 'r0:0/1/0', 'r0:0/1/1', 'r0:0/1/2'],
+  'vertical-center',
+);
+
+console.log(reading.coordinatePx, reading.spreadPx, reading.members);
+await paintPresentationAlignment(page, reading);
+```
+
+The owner must contain every selected member, and at least two distinct members
+are required. Members must sit at one structural level — a wrapper and its own
+nested control sharing a semantic role do not count as two peers. The result
+reports coordinates and deviations; it does not add a finding. Its `paint`
+marks the median axis and every selected member with its signed deviation;
+painting reuses the report and does not acquire the page.
+
+## Inspect spacing at a composition owner
+
+Select consecutive immediate children at the owner that arranges them — they
+don't need matching semantic shape to belong to one composition:
+
+```ts
+import {
+  inspectPresentationSpacing,
+  type PresentationReport,
+} from '@variance-authority/presentation';
+import type { Page } from '@playwright/test';
+import { paintPresentationSpacing } from '@variance-authority/presentation/playwright';
+
+declare const browserPage: Page;
+declare const report: PresentationReport;
+
+const page = report.graph.nodes.find((node) => node.parent === undefined)!;
+const reading = inspectPresentationSpacing(report, page.id, page.children, 'vertical');
+
+console.log(reading.distance, reading.boundary, reading.separations);
+await paintPresentationSpacing(browserPage, reading);
+```
+
+The reading preserves every adjacent distance, boundary strength and spacing
+cluster, plus min/median/max summaries. Members must be consecutive immediate
+children in the owner's structural order. The result is evidence — distances and
+clusters — not a preferred gap or an automatic finding.
+
+## Declare relationship roles instead of trusting tokens
+
+Declare which measured separations in an existing report stand for which
+product-defined role, independent of the design-system token that implemented
+the spacing:
+
+```ts
+import {
+  inspectPresentationHierarchy,
+  type PresentationHierarchyContract,
+  type PresentationReport,
+} from '@variance-authority/presentation';
+import type { Page } from '@playwright/test';
+import { paintPresentationHierarchy } from '@variance-authority/presentation/playwright';
+
+declare const page: Page;
+declare const report: PresentationReport;
+
+const contract: PresentationHierarchyContract = {
+  id: 'demand-record',
+  owner: 'r0:0',
+  axis: 'vertical',
+  levels: [
+    { role: 'owner-boundary', relations: [{ from: 'r0:0/0', to: 'r0:0/1' }] },
+    { role: 'leading-to-body', relations: [{ from: 'r0:0/1/0', to: 'r0:0/1/1' }] },
+    { role: 'body-peer', relations: [{ from: 'r0:0/1/1', to: 'r0:0/1/2' }] },
+    { role: 'content-internal', relations: [{ from: 'r0:0/1/1/0', to: 'r0:0/1/1/1' }] },
+  ],
+};
+const hierarchy = inspectPresentationHierarchy(report, contract);
+
+console.log(hierarchy.levels, hierarchy.collisions, hierarchy.findings);
+await paintPresentationHierarchy(page, hierarchy);
+```
+
+Roles are ordered outside-in and may not repeat. Every relationship must be a
+measured separation inside the declared owner, and one pair cannot hold two
+roles. Adjacent roles occupying the same spacing cluster or calibrated
+distribution produce `SPACING_HIERARCHY_COLLISION` — a finding that two declared
+roles are not actually distinguishable in the rendered spacing; the result does
+not choose a replacement value. Paint labels each declared role.
+
+## Analyze one capture
+
+```ts
+import type { AccessibilitySnapshot, RawCapture } from '@variance-authority/core';
+import { analyzePresentation } from '@variance-authority/presentation';
+
+declare const capture: RawCapture;
+declare const browserAccessibility: AccessibilitySnapshot;
+
+const report = analyzePresentation(capture, {
+  accessibility: browserAccessibility,
+});
+
+console.log(report.telemetry, report.patterns, report.findings);
+```
+
+`telemetry` records content volume, dimensions, utilization, and density as
+neutral context. It never creates a finding independently. `patterns` describe
+repeated semantic shapes and their dominant presentation signatures. `findings`
+contain measurements before prose: the involved nodes, pattern, coordinates,
+ratios, distances, or cluster identities.
+
+The browser accessibility snapshot is retained as an independent semantic
+reading. The `accessibility` option omits that reading only when the browser did
+not observe it. An empty root or a root with no parent or children is an observed
+value and remains present without repair.
+
+A capture whose profile cannot observe layout still produces content telemetry
+and semantic anchors. Its layout-derived `patterns`, `findings`, clusters, and
+paint instructions are absent rather than empty. A layout-capable capture that
+omits an element rect is refused.
+
+## Re-sense after an edit
+
+```ts
+import type { PresentationReport } from '@variance-authority/presentation';
+import { comparePresentation } from '@variance-authority/presentation';
+
+declare const before: PresentationReport;
+declare const after: PresentationReport;
+
+const change = comparePresentation(before, after);
+console.log(change.findings, change.information);
+```
+
+`change.findings` and `change.information` are reported separately, never
+folded into a global score or verdict. `information` holds the content identity
+plus the element, character, and repeated-object counts. A matching content
+identity proves content held while presentation moved; it is derived before
+layout analysis, so the same check works for a capture whose layout is
+unobserved. Re-sensing can therefore show fewer findings resolved alongside an
+unchanged content identity, and no stored baseline is required.
+
+## Carry presentation impact into a run report
+
+Use `presentationSignal` when the same consequence must survive the browser
+session and travel with a general regression report:
+
+```ts
+import type { ObservationRecord } from '@variance-authority/report';
+import {
+  presentationSignal,
+  type PresentationHierarchyReading,
+  type PresentationReport,
+} from '@variance-authority/presentation';
+
+declare const before: PresentationReport;
+declare const after: PresentationReport;
+declare const beforeHierarchy: PresentationHierarchyReading;
+declare const afterHierarchy: PresentationHierarchyReading;
+
+const presentation = presentationSignal(before, after, {
+  beforeHierarchy: [beforeHierarchy],
+  afterHierarchy: [afterHierarchy],
+});
+
+const observation: ObservationRecord = {
+  subject: 'underwriting:demands',
+  verdict: 'changed',
+  because: 'the candidate differs from its baseline',
+  changedPixels: 320,
+  regions: [],
+  signals: { presentation },
+};
+
+console.log(observation.signals?.presentation);
+```
+
+The function combines automatic findings with the supplied product-owned
+hierarchy readings, matching relationship identities across the two reports and
+recording introduced, resolved, and measurement-changing effects.
+`beforeHierarchy` and `afterHierarchy` are optional; omit both when automatic
+findings are the complete evidence for the subject. Missing reports or layout
+findings produce `incomparable`, never an empty clean list. The content
+identity and information counts travel alongside the effects.
+
+The stored signal reports consequence only, not severity: renderer impact —
+whether a changed CSS property can only repaint or must also reflow the page —
+still answers how far a change can reach, and project policy still decides
+whether any finding blocks a run. A collector that participates in the general
+regression pipeline returns this value as its optional `presentation` field.

package/dist/alignment.d.ts

@@ -0,0 +1,9 @@
+import type { PresentationAlignmentKind, PresentationAlignmentReading, PresentationReport } from './model.js';
+/**
+ * Measure an explicitly chosen visual flow, including peers nested in different boxes.
+ *
+ * Selection remains with the product-aware caller. The reading supplies coordinates
+ * and deviations without converting their spread into a design verdict.
+ */
+export declare function inspectPresentationAlignment(report: PresentationReport, ownerId: string, members: readonly string[], kind: PresentationAlignmentKind): PresentationAlignmentReading;
+//# sourceMappingURL=alignment.d.ts.map

package/dist/alignment.js

@@ -0,0 +1,100 @@
+import { codeUnitCompare, median, round } from './math.js';
+/**
+ * Measure an explicitly chosen visual flow, including peers nested in different boxes.
+ *
+ * Selection remains with the product-aware caller. The reading supplies coordinates
+ * and deviations without converting their spread into a design verdict.
+ */
+export function inspectPresentationAlignment(report, ownerId, members, kind) {
+    const byId = new Map(report.graph.nodes.map((node) => [node.id, node]));
+    const owner = byId.get(ownerId);
+    if (owner === undefined)
+        throw new Error(`presentation owner ${ownerId} is not in report ${report.digest}`);
+    const uniqueMembers = [...new Set(members)].sort(codeUnitCompare);
+    if (uniqueMembers.length < 2)
+        throw new Error('presentation alignment needs at least two distinct members');
+    const descendants = new Set(descendantIds(owner, byId));
+    const selected = uniqueMembers.map((id) => {
+        const node = byId.get(id);
+        if (node === undefined)
+            throw new Error(`presentation alignment member ${id} is not in report ${report.digest}`);
+        if (!descendants.has(id))
+            throw new Error(`presentation alignment member ${id} is not inside owner ${ownerId}`);
+        return node;
+    });
+    const values = selected.map((node) => coordinate(node, kind));
+    const center = median(values);
+    const membersWithCoordinates = selected.map((node) => {
+        const coordinatePx = coordinate(node, kind);
+        return { node, coordinatePx: round(coordinatePx, 2), deviationPx: round(coordinatePx - center, 2) };
+    });
+    const horizontal = ['top', 'bottom', 'vertical-center'].includes(kind);
+    const readingId = `alignment:${kind}:${uniqueMembers.join('+')}`;
+    return {
+        formatVersion: 1,
+        report: report.digest,
+        owner,
+        kind,
+        coordinatePx: round(center, 2),
+        spreadPx: round(Math.max(...values) - Math.min(...values), 2),
+        members: membersWithCoordinates,
+        paint: [
+            {
+                id: readingId,
+                owner: ownerId,
+                nodes: uniqueMembers,
+                layer: 'axes',
+                shape: 'line',
+                color: '#70ff70',
+                label: `${kind} ${round(center, 2)}px`,
+                line: horizontal
+                    ? {
+                        x1: Math.min(...selected.map((node) => node.rect.x)),
+                        y1: round(center, 2),
+                        x2: Math.max(...selected.map((node) => node.rect.x + node.rect.width)),
+                        y2: round(center, 2),
+                    }
+                    : {
+                        x1: round(center, 2),
+                        y1: Math.min(...selected.map((node) => node.rect.y)),
+                        x2: round(center, 2),
+                        y2: Math.max(...selected.map((node) => node.rect.y + node.rect.height)),
+                    },
+            },
+            ...membersWithCoordinates.map(({ node, coordinatePx, deviationPx }) => ({
+                id: `${readingId}:${node.id}`,
+                owner: ownerId,
+                nodes: [node.id],
+                layer: 'axes',
+                shape: 'rect',
+                color: '#70ff70',
+                label: `${coordinatePx}px (${deviationPx >= 0 ? '+' : ''}${deviationPx}px)`,
+                rect: node.rect,
+            })),
+        ],
+    };
+}
+function coordinate(node, kind) {
+    if (kind === 'left')
+        return node.rect.x;
+    if (kind === 'right')
+        return node.rect.x + node.rect.width;
+    if (kind === 'horizontal-center')
+        return node.rect.x + node.rect.width / 2;
+    if (kind === 'top')
+        return node.rect.y;
+    if (kind === 'bottom')
+        return node.rect.y + node.rect.height;
+    return node.rect.y + node.rect.height / 2;
+}
+function descendantIds(owner, byId) {
+    const result = [];
+    for (const id of owner.children) {
+        const child = byId.get(id);
+        if (child === undefined)
+            continue;
+        result.push(id, ...descendantIds(child, byId));
+    }
+    return result;
+}
+//# sourceMappingURL=alignment.js.map

package/dist/alignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.js","sourceRoot":"","sources":["../src/alignment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAQ3D;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA0B,EAC1B,OAAe,EACf,OAA0B,EAC1B,IAA+B;IAE/B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,qBAAqB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5G,MAAM,aAAa,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAClE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAC5G,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,EAAE,qBAAqB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACjH,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,EAAE,wBAAwB,OAAO,EAAE,CAAC,CAAC;QAChH,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAE,CAAC;IAC/B,MAAM,sBAAsB,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACnD,MAAM,YAAY,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,YAAY,GAAG,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC;IACtG,CAAC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvE,MAAM,SAAS,GAAG,aAAa,IAAI,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACjE,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK;QACL,IAAI;QACJ,YAAY,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9B,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QAC7D,OAAO,EAAE,sBAAsB;QAC/B,KAAK,EAAE;YACL;gBACE,EAAE,EAAE,SAAS;gBACb,KAAK,EAAE,OAAO;gBACd,KAAK,EAAE,aAAa;gBACpB,KAAK,EAAE,MAAM;gBACb,KAAK,EAAE,MAAM;gBACb,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI;gBACtC,IAAI,EAAE,UAAU;oBACd,CAAC,CAAC;wBACE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;wBACpD,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;wBACpB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;wBACtE,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;qBACrB;oBACH,CAAC,CAAC;wBACE,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;wBACpB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;wBACpD,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;wBACpB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;qBACxE;aACN;YACD,GAAG,sBAAsB,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;gBACtE,EAAE,EAAE,GAAG,SAAS,IAAI,IAAI,CAAC,EAAE,EAAE;gBAC7B,KAAK,EAAE,OAAO;gBACd,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChB,KAAK,EAAE,MAAe;gBACtB,KAAK,EAAE,MAAe;gBACtB,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,GAAG,YAAY,OAAO,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,WAAW,KAAK;gBAC3E,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC,CAAC;SACJ;KACF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAsB,EAAE,IAA+B;IACzE,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IAC3D,IAAI,IAAI,KAAK,mBAAmB;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IAC3E,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,aAAa,CAAC,KAAuB,EAAE,IAA2C;IACzF,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { codeUnitCompare, median, round } from './math.js';\nimport type {\n  PresentationAlignmentKind,\n  PresentationAlignmentReading,\n  PresentationNode,\n  PresentationReport,\n} from './model.js';\n\n/**\n * Measure an explicitly chosen visual flow, including peers nested in different boxes.\n *\n * Selection remains with the product-aware caller. The reading supplies coordinates\n * and deviations without converting their spread into a design verdict.\n */\nexport function inspectPresentationAlignment(\n  report: PresentationReport,\n  ownerId: string,\n  members: readonly string[],\n  kind: PresentationAlignmentKind,\n): PresentationAlignmentReading {\n  const byId = new Map(report.graph.nodes.map((node) => [node.id, node]));\n  const owner = byId.get(ownerId);\n  if (owner === undefined) throw new Error(`presentation owner ${ownerId} is not in report ${report.digest}`);\n  const uniqueMembers = [...new Set(members)].sort(codeUnitCompare);\n  if (uniqueMembers.length < 2) throw new Error('presentation alignment needs at least two distinct members');\n  const descendants = new Set(descendantIds(owner, byId));\n  const selected = uniqueMembers.map((id) => {\n    const node = byId.get(id);\n    if (node === undefined) throw new Error(`presentation alignment member ${id} is not in report ${report.digest}`);\n    if (!descendants.has(id)) throw new Error(`presentation alignment member ${id} is not inside owner ${ownerId}`);\n    return node;\n  });\n  const values = selected.map((node) => coordinate(node, kind));\n  const center = median(values)!;\n  const membersWithCoordinates = selected.map((node) => {\n    const coordinatePx = coordinate(node, kind);\n    return { node, coordinatePx: round(coordinatePx, 2), deviationPx: round(coordinatePx - center, 2) };\n  });\n  const horizontal = ['top', 'bottom', 'vertical-center'].includes(kind);\n  const readingId = `alignment:${kind}:${uniqueMembers.join('+')}`;\n  return {\n    formatVersion: 1,\n    report: report.digest,\n    owner,\n    kind,\n    coordinatePx: round(center, 2),\n    spreadPx: round(Math.max(...values) - Math.min(...values), 2),\n    members: membersWithCoordinates,\n    paint: [\n      {\n        id: readingId,\n        owner: ownerId,\n        nodes: uniqueMembers,\n        layer: 'axes',\n        shape: 'line',\n        color: '#70ff70',\n        label: `${kind} ${round(center, 2)}px`,\n        line: horizontal\n          ? {\n              x1: Math.min(...selected.map((node) => node.rect.x)),\n              y1: round(center, 2),\n              x2: Math.max(...selected.map((node) => node.rect.x + node.rect.width)),\n              y2: round(center, 2),\n            }\n          : {\n              x1: round(center, 2),\n              y1: Math.min(...selected.map((node) => node.rect.y)),\n              x2: round(center, 2),\n              y2: Math.max(...selected.map((node) => node.rect.y + node.rect.height)),\n            },\n      },\n      ...membersWithCoordinates.map(({ node, coordinatePx, deviationPx }) => ({\n        id: `${readingId}:${node.id}`,\n        owner: ownerId,\n        nodes: [node.id],\n        layer: 'axes' as const,\n        shape: 'rect' as const,\n        color: '#70ff70',\n        label: `${coordinatePx}px (${deviationPx >= 0 ? '+' : ''}${deviationPx}px)`,\n        rect: node.rect,\n      })),\n    ],\n  };\n}\n\nfunction coordinate(node: PresentationNode, kind: PresentationAlignmentKind): number {\n  if (kind === 'left') return node.rect.x;\n  if (kind === 'right') return node.rect.x + node.rect.width;\n  if (kind === 'horizontal-center') return node.rect.x + node.rect.width / 2;\n  if (kind === 'top') return node.rect.y;\n  if (kind === 'bottom') return node.rect.y + node.rect.height;\n  return node.rect.y + node.rect.height / 2;\n}\n\nfunction descendantIds(owner: PresentationNode, byId: ReadonlyMap<string, PresentationNode>): string[] {\n  const result: string[] = [];\n  for (const id of owner.children) {\n    const child = byId.get(id);\n    if (child === undefined) continue;\n    result.push(id, ...descendantIds(child, byId));\n  }\n  return result;\n}\n"]}

package/dist/analyze.d.ts

@@ -0,0 +1,20 @@
+import { type AccessibilitySnapshot, type RawCapture } from '@variance-authority/core';
+import type { PresentationReport } from './model.js';
+export interface AnalyzePresentationOptions {
+    /**
+     * Browser-computed ARIA evidence observed beside this capture.
+     *
+     * Omit only when it was not observed. `roots: ['']` and partial roots are
+     * readings and remain byte-for-byte present in the report.
+     */
+    readonly accessibility?: AccessibilitySnapshot;
+}
+/**
+ * Derive machine-readable presentation relationships from one browser capture.
+ *
+ * Telemetry is descriptive and never creates a finding by itself. Findings are
+ * limited to measured relationships; this function does not recommend a layout,
+ * remove information, or produce an overall quality score.
+ */
+export declare function analyzePresentation(capture: RawCapture, options?: AnalyzePresentationOptions): PresentationReport;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.js

@@ -0,0 +1,132 @@
+import { digestValue, } from '@variance-authority/core';
+import { detectFindings } from './findings.js';
+import { buildGraph } from './graph.js';
+import { measureGraph } from './measure.js';
+import { paintInstructions } from './paint.js';
+import { inferPatterns } from './patterns.js';
+import { telemetryOf } from './telemetry.js';
+/**
+ * Derive machine-readable presentation relationships from one browser capture.
+ *
+ * Telemetry is descriptive and never creates a finding by itself. Findings are
+ * limited to measured relationships; this function does not recommend a layout,
+ * remove information, or produce an overall quality score.
+ */
+export function analyzePresentation(capture, options = {}) {
+    const anchors = semanticAnchors(capture);
+    const contentDigest = digestValue(contentEvidence(capture));
+    if (!capture.profile.layout) {
+        const body = {
+            formatVersion: 1,
+            contentDigest,
+            subject: capture.subject,
+            ...fontsOf(capture),
+            semantic: {
+                anchors,
+                ...(options.accessibility === undefined ? {} : { browserAccessibility: options.accessibility }),
+            },
+            telemetry: telemetryOf(capture, [], undefined),
+            graph: { nodes: [], relations: [] },
+        };
+        return { ...body, digest: digestValue(body) };
+    }
+    assertLayout(capture);
+    const graph = buildGraph(capture);
+    const measured = measureGraph(graph);
+    const inferred = inferPatterns(graph, measured);
+    const findings = detectFindings(graph, measured, inferred.patterns);
+    const relations = [...measured.relations, ...inferred.peerRelations];
+    const paint = paintInstructions({
+        nodes: measured.nodes,
+        relations,
+        axes: measured.axes,
+        baselines: measured.baselines,
+        prominence: measured.prominence,
+        surfaces: measured.surfaces,
+        patterns: inferred.patterns,
+        findings,
+    });
+    const body = {
+        formatVersion: 1,
+        contentDigest,
+        subject: capture.subject,
+        ...fontsOf(capture),
+        semantic: {
+            anchors,
+            ...(options.accessibility === undefined ? {} : { browserAccessibility: options.accessibility }),
+        },
+        telemetry: telemetryOf(capture, measured.nodes, inferred.patterns),
+        graph: { nodes: measured.nodes, relations },
+        spacing: measured.spacing,
+        axes: measured.axes,
+        baselines: measured.baselines,
+        prominence: measured.prominence,
+        surfaces: measured.surfaces,
+        patterns: inferred.patterns,
+        findings,
+        paint,
+    };
+    return { ...body, digest: digestValue(body) };
+}
+/**
+ * Carry the caller-established font identities onto the report.
+ *
+ * The live entry accepts a `fonts` option and threads it into the capture, and
+ * the capture is then analyzed and dropped — so through that door the option
+ * had no observable consequence at all. It has one here. Fonts are a render
+ * input of the more consequential kind: a substitution moves every metric on
+ * the page without changing a byte of code, so a reading taken under different
+ * pinned identities is a different reading and the digest says so.
+ *
+ * Sorted, because the order a caller happened to list them in is not part of
+ * their identity — the same position `normalize` takes on the environment key.
+ * Absent rather than empty when none were established, matching the capture,
+ * which says the same thing a second way with its `unverified-fonts` caveat.
+ * The content digest is deliberately untouched: font identity is presentation,
+ * and content identity is what has to survive presentation moving.
+ */
+function fontsOf(capture) {
+    const fonts = capture.environment.fonts;
+    return fonts.length === 0 ? {} : { fonts: [...fonts].sort() };
+}
+function contentEvidence(capture) {
+    const read = (node) => ({
+        tag: node.tag,
+        ...(node.aria === undefined ? {} : { aria: node.aria }),
+        ...(node.text === undefined ? {} : { text: node.text }),
+        children: node.children.map(read),
+        ...(node.shadowChildren === undefined ? {} : { shadowChildren: node.shadowChildren.map(read) }),
+    });
+    return {
+        root: read(capture.root),
+        ...(capture.portals === undefined ? {} : { portals: capture.portals.map(read) }),
+    };
+}
+function semanticAnchors(capture) {
+    const anchors = [];
+    [capture.root, ...(capture.portals ?? [])].forEach((root, rootIndex) => walk(root, rootIndex, '0'));
+    return anchors;
+    function walk(node, root, path) {
+        if (node.tag !== '#text' &&
+            node.aria !== undefined &&
+            (node.aria.role !== null || node.aria.name !== null)) {
+            const role = node.aria?.role ?? node.tag;
+            const name = node.aria?.name ?? '';
+            anchors.push(`r${root}:${path} ${role}${name.length > 0 ? ` "${name}"` : ''}`);
+        }
+        node.children.forEach((child, index) => walk(child, root, `${path}/${index}`));
+        node.shadowChildren?.forEach((child, index) => walk(child, root, `${path}/shadow:${index}`));
+    }
+}
+function assertLayout(capture) {
+    [capture.root, ...(capture.portals ?? [])].forEach((root, rootIndex) => walk(root, `r${rootIndex}:0`));
+    function walk(node, path) {
+        if (node.tag !== '#text' && node.rect === undefined) {
+            throw new Error(`the ${capture.profile.id} capture claims layout is observable but ${path} has no rect; ` +
+                'an absent measurement cannot be analyzed as an empty box');
+        }
+        node.children.forEach((child, index) => walk(child, `${path}/${index}`));
+        node.shadowChildren?.forEach((child, index) => walk(child, `${path}/shadow:${index}`));
+    }
+}
+//# sourceMappingURL=analyze.js.map