@variance-authority/presentation 0.1.0

package/dist/patterns.js

@@ -0,0 +1,148 @@
+import { codeUnitCompare, median, round } from './math.js';
+export function inferPatterns(graph, measured) {
+    const patterns = [];
+    const peerRelations = [];
+    const surfaceByNode = new Map();
+    for (const group of measured.surfaces)
+        for (const member of group.members)
+            surfaceByNode.set(member, group.id);
+    for (const parent of measured.nodes) {
+        const groups = new Map();
+        for (const childId of parent.children) {
+            const child = measured.nodes.find((candidate) => candidate.id === childId);
+            if (child === undefined)
+                continue;
+            const shape = semanticShape(child, graph);
+            const members = groups.get(shape) ?? [];
+            members.push(child);
+            groups.set(shape, members);
+        }
+        for (const [shape, instances] of [...groups.entries()].sort(([a], [b]) => codeUnitCompare(a, b))) {
+            if (instances.length < 2)
+                continue;
+            const id = `R${patterns.length + 1}`;
+            const signatures = instances.map((node) => signatureOf(node, measured, surfaceByNode));
+            const dominant = dominantSignature(signatures);
+            const deviations = signatures.map((signature) => signatureDeviation(signature, dominant));
+            const stateMode = mode(instances.map((node) => node.stateSignature));
+            const dominantInstances = instances
+                .filter((_node, index) => deviations[index] <= 0.3)
+                .map((node) => node.id);
+            const outliers = instances.flatMap((node, index) => {
+                const deviation = deviations[index];
+                return deviation <= 0.3
+                    ? []
+                    : [{
+                            node: node.id,
+                            deviation: round(deviation),
+                            explainedByState: node.stateSignature !== stateMode && node.stateSignature.length > 0,
+                        }];
+            });
+            const similarity = Math.max(0, 1 - (median(deviations) ?? 0));
+            patterns.push({
+                id,
+                parent: parent.id,
+                semanticShape: shape,
+                instances: instances.map((node) => node.id),
+                recurringLabels: recurringLabels(instances, graph),
+                presentationSimilarity: round(similarity),
+                dominant,
+                dominantInstances,
+                outliers,
+            });
+            for (let index = 0; index < instances.length - 1; index += 1) {
+                const from = instances[index].id;
+                const to = instances[index + 1].id;
+                peerRelations.push({ id: `peer:${id}:${from}:${to}`, kind: 'semantic-peer', from, to });
+            }
+        }
+    }
+    return { patterns, peerRelations };
+}
+function semanticShape(node, graph) {
+    const children = node.children
+        .map((id) => graph.byId.get(id)?.semanticClass)
+        .filter((value) => value !== undefined);
+    return `${node.semanticClass}[${children.join(',')}]`;
+}
+function signatureOf(node, measured, surfaceByNode) {
+    const internal = measured.relations.filter((relation) => relation.kind === 'separates' &&
+        node.children.includes(relation.from) &&
+        node.children.includes(relation.to));
+    const external = measured.relations.filter((relation) => relation.kind === 'separates' && (relation.from === node.id || relation.to === node.id));
+    const internalGapPx = median(internal.flatMap((relation) => relation.distancePx ?? []));
+    const boundaryStrength = median(external.flatMap((relation) => relation.boundaryStrength ?? []));
+    return {
+        widthPx: node.rect.width,
+        heightPx: node.rect.height,
+        leftPx: node.rect.x,
+        ...(internalGapPx === undefined ? {} : { internalGapPx: round(internalGapPx, 2) }),
+        ...(boundaryStrength === undefined ? {} : { boundaryStrength: round(boundaryStrength) }),
+        ...(node.prominence.cluster === undefined ? {} : { prominenceCluster: node.prominence.cluster }),
+        ...(surfaceByNode.get(node.id) === undefined ? {} : { surfaceGroup: surfaceByNode.get(node.id) }),
+    };
+}
+function dominantSignature(signatures) {
+    const numbers = (select) => median(signatures.flatMap((signature) => select(signature) ?? []));
+    const internalGapPx = numbers((signature) => signature.internalGapPx);
+    const boundaryStrength = numbers((signature) => signature.boundaryStrength);
+    const prominenceCluster = mode(signatures.map((signature) => signature.prominenceCluster ?? ''));
+    const surfaceGroup = mode(signatures.map((signature) => signature.surfaceGroup ?? ''));
+    return {
+        widthPx: round(numbers((signature) => signature.widthPx) ?? 0, 2),
+        heightPx: round(numbers((signature) => signature.heightPx) ?? 0, 2),
+        leftPx: round(numbers((signature) => signature.leftPx) ?? 0, 2),
+        ...(internalGapPx === undefined ? {} : { internalGapPx: round(internalGapPx, 2) }),
+        ...(boundaryStrength === undefined ? {} : { boundaryStrength: round(boundaryStrength) }),
+        ...(prominenceCluster.length === 0 ? {} : { prominenceCluster }),
+        ...(surfaceGroup.length === 0 ? {} : { surfaceGroup }),
+    };
+}
+function signatureDeviation(actual, dominant) {
+    const relative = (left, right, floor) => Math.abs(left - right) / Math.max(floor, Math.abs(right));
+    const values = [
+        relative(actual.widthPx, dominant.widthPx, 8),
+        relative(actual.heightPx, dominant.heightPx, 16) * 0.35,
+        Math.abs(actual.leftPx - dominant.leftPx) / 8,
+    ];
+    if (actual.internalGapPx !== undefined && dominant.internalGapPx !== undefined) {
+        values.push(relative(actual.internalGapPx, dominant.internalGapPx, 4));
+    }
+    if (actual.prominenceCluster !== dominant.prominenceCluster)
+        values.push(0.5);
+    if (actual.surfaceGroup !== dominant.surfaceGroup)
+        values.push(0.5);
+    return Math.max(...values);
+}
+function recurringLabels(instances, graph) {
+    const labelSets = instances.map((instance) => {
+        const labels = descendants(instance, graph)
+            .flatMap((node) => node.name ?? node.text ?? [])
+            .map((label) => label.trim())
+            .filter((label) => label.length > 0 && label.length <= 80);
+        return new Set(labels);
+    });
+    const first = labelSets[0];
+    if (first === undefined)
+        return [];
+    return [...first]
+        .filter((label) => labelSets.every((labels) => labels.has(label)))
+        .sort(codeUnitCompare);
+}
+export function descendants(node, graph) {
+    const result = [];
+    for (const id of node.children) {
+        const child = graph.byId.get(id);
+        if (child === undefined)
+            continue;
+        result.push(child, ...descendants(child, graph));
+    }
+    return result;
+}
+function mode(values) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    return [...counts.entries()].sort((left, right) => right[1] - left[1] || codeUnitCompare(left[0], right[0]))[0]?.[0] ?? '';
+}
+//# sourceMappingURL=patterns.js.map

package/dist/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../src/patterns.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BuiltGraph } from './graph.js';\nimport type { Measurements } from './measure.js';\nimport type {\n  PresentationNode,\n  PresentationRelation,\n  PresentationSignature,\n  RepeatedPattern,\n} from './model.js';\nimport { codeUnitCompare, median, round } from './math.js';\n\nexport interface PatternResult {\n  readonly patterns: RepeatedPattern[];\n  readonly peerRelations: PresentationRelation[];\n}\n\nexport function inferPatterns(graph: BuiltGraph, measured: Measurements): PatternResult {\n  const patterns: RepeatedPattern[] = [];\n  const peerRelations: PresentationRelation[] = [];\n  const surfaceByNode = new Map<string, string>();\n  for (const group of measured.surfaces) for (const member of group.members) surfaceByNode.set(member, group.id);\n\n  for (const parent of measured.nodes) {\n    const groups = new Map<string, PresentationNode[]>();\n    for (const childId of parent.children) {\n      const child = measured.nodes.find((candidate) => candidate.id === childId);\n      if (child === undefined) continue;\n      const shape = semanticShape(child, graph);\n      const members = groups.get(shape) ?? [];\n      members.push(child);\n      groups.set(shape, members);\n    }\n    for (const [shape, instances] of [...groups.entries()].sort(([a], [b]) => codeUnitCompare(a, b))) {\n      if (instances.length < 2) continue;\n      const id = `R${patterns.length + 1}`;\n      const signatures = instances.map((node) => signatureOf(node, measured, surfaceByNode));\n      const dominant = dominantSignature(signatures);\n      const deviations = signatures.map((signature) => signatureDeviation(signature, dominant));\n      const stateMode = mode(instances.map((node) => node.stateSignature));\n      const dominantInstances = instances\n        .filter((_node, index) => deviations[index]! <= 0.3)\n        .map((node) => node.id);\n      const outliers = instances.flatMap((node, index) => {\n        const deviation = deviations[index]!;\n        return deviation <= 0.3\n          ? []\n          : [{\n              node: node.id,\n              deviation: round(deviation),\n              explainedByState: node.stateSignature !== stateMode && node.stateSignature.length > 0,\n            }];\n      });\n      const similarity = Math.max(0, 1 - (median(deviations) ?? 0));\n      patterns.push({\n        id,\n        parent: parent.id,\n        semanticShape: shape,\n        instances: instances.map((node) => node.id),\n        recurringLabels: recurringLabels(instances, graph),\n        presentationSimilarity: round(similarity),\n        dominant,\n        dominantInstances,\n        outliers,\n      });\n      for (let index = 0; index < instances.length - 1; index += 1) {\n        const from = instances[index]!.id;\n        const to = instances[index + 1]!.id;\n        peerRelations.push({ id: `peer:${id}:${from}:${to}`, kind: 'semantic-peer', from, to });\n      }\n    }\n  }\n  return { patterns, peerRelations };\n}\n\nfunction semanticShape(node: PresentationNode, graph: BuiltGraph): string {\n  const children = node.children\n    .map((id) => graph.byId.get(id)?.semanticClass)\n    .filter((value): value is string => value !== undefined);\n  return `${node.semanticClass}[${children.join(',')}]`;\n}\n\nfunction signatureOf(\n  node: PresentationNode,\n  measured: Measurements,\n  surfaceByNode: ReadonlyMap<string, string>,\n): PresentationSignature {\n  const internal = measured.relations.filter(\n    (relation) =>\n      relation.kind === 'separates' &&\n      node.children.includes(relation.from) &&\n      node.children.includes(relation.to),\n  );\n  const external = measured.relations.filter(\n    (relation) =>\n      relation.kind === 'separates' && (relation.from === node.id || relation.to === node.id),\n  );\n  const internalGapPx = median(internal.flatMap((relation) => relation.distancePx ?? []));\n  const boundaryStrength = median(external.flatMap((relation) => relation.boundaryStrength ?? []));\n  return {\n    widthPx: node.rect.width,\n    heightPx: node.rect.height,\n    leftPx: node.rect.x,\n    ...(internalGapPx === undefined ? {} : { internalGapPx: round(internalGapPx, 2) }),\n    ...(boundaryStrength === undefined ? {} : { boundaryStrength: round(boundaryStrength) }),\n    ...(node.prominence.cluster === undefined ? {} : { prominenceCluster: node.prominence.cluster }),\n    ...(surfaceByNode.get(node.id) === undefined ? {} : { surfaceGroup: surfaceByNode.get(node.id)! }),\n  };\n}\n\nfunction dominantSignature(signatures: readonly PresentationSignature[]): PresentationSignature {\n  const numbers = (select: (signature: PresentationSignature) => number | undefined): number | undefined =>\n    median(signatures.flatMap((signature) => select(signature) ?? []));\n  const internalGapPx = numbers((signature) => signature.internalGapPx);\n  const boundaryStrength = numbers((signature) => signature.boundaryStrength);\n  const prominenceCluster = mode(signatures.map((signature) => signature.prominenceCluster ?? ''));\n  const surfaceGroup = mode(signatures.map((signature) => signature.surfaceGroup ?? ''));\n  return {\n    widthPx: round(numbers((signature) => signature.widthPx) ?? 0, 2),\n    heightPx: round(numbers((signature) => signature.heightPx) ?? 0, 2),\n    leftPx: round(numbers((signature) => signature.leftPx) ?? 0, 2),\n    ...(internalGapPx === undefined ? {} : { internalGapPx: round(internalGapPx, 2) }),\n    ...(boundaryStrength === undefined ? {} : { boundaryStrength: round(boundaryStrength) }),\n    ...(prominenceCluster.length === 0 ? {} : { prominenceCluster }),\n    ...(surfaceGroup.length === 0 ? {} : { surfaceGroup }),\n  };\n}\n\nfunction signatureDeviation(actual: PresentationSignature, dominant: PresentationSignature): number {\n  const relative = (left: number, right: number, floor: number): number =>\n    Math.abs(left - right) / Math.max(floor, Math.abs(right));\n  const values = [\n    relative(actual.widthPx, dominant.widthPx, 8),\n    relative(actual.heightPx, dominant.heightPx, 16) * 0.35,\n    Math.abs(actual.leftPx - dominant.leftPx) / 8,\n  ];\n  if (actual.internalGapPx !== undefined && dominant.internalGapPx !== undefined) {\n    values.push(relative(actual.internalGapPx, dominant.internalGapPx, 4));\n  }\n  if (actual.prominenceCluster !== dominant.prominenceCluster) values.push(0.5);\n  if (actual.surfaceGroup !== dominant.surfaceGroup) values.push(0.5);\n  return Math.max(...values);\n}\n\nfunction recurringLabels(instances: readonly PresentationNode[], graph: BuiltGraph): string[] {\n  const labelSets = instances.map((instance) => {\n    const labels = descendants(instance, graph)\n      .flatMap((node) => node.name ?? node.text ?? [])\n      .map((label) => label.trim())\n      .filter((label) => label.length > 0 && label.length <= 80);\n    return new Set(labels);\n  });\n  const first = labelSets[0];\n  if (first === undefined) return [];\n  return [...first]\n    .filter((label) => labelSets.every((labels) => labels.has(label)))\n    .sort(codeUnitCompare);\n}\n\nexport function descendants(node: PresentationNode, graph: BuiltGraph): PresentationNode[] {\n  const result: PresentationNode[] = [];\n  for (const id of node.children) {\n    const child = graph.byId.get(id);\n    if (child === undefined) continue;\n    result.push(child, ...descendants(child, graph));\n  }\n  return result;\n}\n\nfunction mode(values: readonly string[]): string {\n  const counts = new Map<string, number>();\n  for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);\n  return [...counts.entries()].sort((left, right) => right[1] - left[1] || codeUnitCompare(left[0], right[0]))[0]?.[0] ?? '';\n}\n"]}

package/dist/playwright.d.ts

@@ -0,0 +1,27 @@
+import type { Locator, Page } from '@playwright/test';
+import type { PaintLayer, PresentationAlignmentReading, PresentationFocus, PresentationHierarchyReading, PresentationReport, PresentationSpacingReading } from './model.js';
+export interface SensePresentationOptions {
+    readonly subjectId?: string;
+    readonly title?: string;
+    readonly fonts?: readonly string[];
+    readonly suspense?: {
+        readonly timeoutMs?: number;
+    };
+    /** Override stabilization ids; use `[]` only when the caller owns a static document. */
+    readonly stabilize?: readonly string[];
+    /** `true` paints every layer; a layer list paints only those measurements. */
+    readonly paint?: boolean | readonly PaintLayer[];
+}
+/** Sense and optionally paint one locator without creating a baseline or verdict. */
+export declare function sensePresentation(page: Page, locator: Locator, options?: SensePresentationOptions): Promise<PresentationReport>;
+/** Remove diagnostic paint without changing the sensed application. */
+export declare function clearPresentationPaint(page: Page): Promise<void>;
+/** Paint one already-focused structural reading without acquiring the page again. */
+export declare function paintPresentationFocus(page: Page, focus: PresentationFocus, layers?: readonly PaintLayer[]): Promise<number>;
+/** Paint one explicit alignment reading without acquiring the page again. */
+export declare function paintPresentationAlignment(page: Page, reading: PresentationAlignmentReading): Promise<number>;
+/** Paint one explicit spacing reading without acquiring the page again. */
+export declare function paintPresentationSpacing(page: Page, reading: PresentationSpacingReading): Promise<number>;
+/** Paint one product-declared hierarchy reading without acquiring the page again. */
+export declare function paintPresentationHierarchy(page: Page, reading: PresentationHierarchyReading): Promise<number>;
+//# sourceMappingURL=playwright.d.ts.map

package/dist/playwright.js

@@ -0,0 +1,108 @@
+import { accessibilitySnapshot } from '@variance-authority/core';
+import { analyzePresentation } from './analyze.js';
+import { PRESENTATION_AGENT, PRESENTATION_ROOT_ATTRIBUTE, } from './browser-agent.js';
+import { bundlePresentationAgent } from './bundle.js';
+/** Sense and optionally paint one locator without creating a baseline or verdict. */
+export async function sensePresentation(page, locator, options = {}) {
+    await install(page);
+    const viewport = page.viewportSize() ?? (await page.evaluate(() => ({ width: innerWidth, height: innerHeight })));
+    const environment = await page.evaluate(() => ({
+        deviceScaleFactor: devicePixelRatio,
+        colorScheme: matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light',
+    }));
+    const browser = page.context().browser();
+    const request = {
+        subject: {
+            id: options.subjectId ?? 'presentation',
+            kind: 'fixture',
+            ...(options.title === undefined ? {} : { title: options.title }),
+        },
+        viewport: { ...viewport, ...environment },
+        engine: browser === null ? 'browser@unknown' : `${browser.browserType().name()}@${browser.version()}`,
+        ...(options.fonts === undefined ? {} : { fonts: options.fonts }),
+        ...(options.suspense === undefined ? {} : { suspense: options.suspense }),
+        ...(options.stabilize === undefined ? {} : { stabilize: options.stabilize }),
+    };
+    const raw = await locator.evaluate((element, [global, sent]) => {
+        const agent = globalThis[global];
+        if (agent === undefined)
+            throw new Error(`the presentation sensing agent is not installed at ${global}`);
+        return agent.acquire(element, sent);
+    }, [PRESENTATION_AGENT, request]);
+    const acquired = JSON.parse(raw);
+    try {
+        const roots = [await locator.ariaSnapshot()];
+        for (const portal of acquired.portals) {
+            roots.push(await page.locator(`[${PRESENTATION_ROOT_ATTRIBUTE}="${portal.marker}"]`).ariaSnapshot());
+        }
+        const report = analyzePresentation(acquired.capture, {
+            accessibility: accessibilitySnapshot(request.engine, roots),
+        });
+        if (options.paint !== undefined && options.paint !== false) {
+            const layers = options.paint === true ? undefined : options.paint;
+            await page.evaluate(([global, instructions, selected]) => {
+                const agent = globalThis[global];
+                if (agent === undefined)
+                    throw new Error(`the presentation sensing agent is not installed at ${global}`);
+                return agent.paint(instructions, selected);
+            }, [PRESENTATION_AGENT, report.paint ?? [], layers]);
+        }
+        return report;
+    }
+    finally {
+        await restorePortals(page, acquired);
+    }
+}
+/** Remove diagnostic paint without changing the sensed application. */
+export async function clearPresentationPaint(page) {
+    await page.evaluate((global) => {
+        const agent = globalThis[global];
+        agent?.clear();
+    }, PRESENTATION_AGENT);
+}
+/** Paint one already-focused structural reading without acquiring the page again. */
+export async function paintPresentationFocus(page, focus, layers) {
+    return paintPresentationInstructions(page, focus.paint, layers);
+}
+/** Paint one explicit alignment reading without acquiring the page again. */
+export async function paintPresentationAlignment(page, reading) {
+    return paintPresentationInstructions(page, reading.paint, ['axes']);
+}
+/** Paint one explicit spacing reading without acquiring the page again. */
+export async function paintPresentationSpacing(page, reading) {
+    return paintPresentationInstructions(page, reading.paint, ['spacing']);
+}
+/** Paint one product-declared hierarchy reading without acquiring the page again. */
+export async function paintPresentationHierarchy(page, reading) {
+    return paintPresentationInstructions(page, reading.paint, ['findings']);
+}
+async function paintPresentationInstructions(page, instructions, layers) {
+    await install(page);
+    return page.evaluate(([global, instructions, selected]) => {
+        const agent = globalThis[global];
+        if (agent === undefined)
+            throw new Error(`the presentation sensing agent is not installed at ${global}`);
+        return agent.paint(instructions, selected);
+    }, [PRESENTATION_AGENT, instructions, layers]);
+}
+async function install(page) {
+    const bundle = await bundlePresentationAgent();
+    await page.addInitScript(bundle);
+    const installed = await page.evaluate((global) => typeof globalThis[global] === 'object', PRESENTATION_AGENT);
+    if (!installed)
+        await page.evaluate(bundle);
+}
+async function restorePortals(page, acquired) {
+    await page.evaluate(([attribute, portals]) => {
+        for (const portal of portals) {
+            const element = document.querySelector(`[${attribute}="${portal.marker}"]`);
+            if (element === null)
+                continue;
+            if (portal.previous === undefined)
+                element.removeAttribute(attribute);
+            else
+                element.setAttribute(attribute, portal.previous);
+        }
+    }, [PRESENTATION_ROOT_ATTRIBUTE, acquired.portals]);
+}
+//# sourceMappingURL=playwright.js.map

package/dist/playwright.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright.js","sourceRoot":"","sources":["../src/playwright.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Locator, Page } from '@playwright/test';\nimport { accessibilitySnapshot } from '@variance-authority/core';\nimport type {\n  PaintInstruction,\n  PaintLayer,\n  PresentationAlignmentReading,\n  PresentationFocus,\n  PresentationHierarchyReading,\n  PresentationReport,\n  PresentationSpacingReading,\n} from './model.js';\nimport { analyzePresentation } from './analyze.js';\nimport {\n  PRESENTATION_AGENT,\n  PRESENTATION_ROOT_ATTRIBUTE,\n  type InstalledPresentationAgent,\n  type PresentationAcquireRequest,\n  type PresentationAcquired,\n} from './browser-agent.js';\nimport { bundlePresentationAgent } from './bundle.js';\n\nexport interface SensePresentationOptions {\n  readonly subjectId?: string;\n  readonly title?: string;\n  readonly fonts?: readonly string[];\n  readonly suspense?: { readonly timeoutMs?: number };\n  /** Override stabilization ids; use `[]` only when the caller owns a static document. */\n  readonly stabilize?: readonly string[];\n  /** `true` paints every layer; a layer list paints only those measurements. */\n  readonly paint?: boolean | readonly PaintLayer[];\n}\n\n/** Sense and optionally paint one locator without creating a baseline or verdict. */\nexport async function sensePresentation(\n  page: Page,\n  locator: Locator,\n  options: SensePresentationOptions = {},\n): Promise<PresentationReport> {\n  await install(page);\n  const viewport = page.viewportSize() ?? (await page.evaluate(() => ({ width: innerWidth, height: innerHeight })));\n  const environment = await page.evaluate(() => ({\n    deviceScaleFactor: devicePixelRatio,\n    colorScheme: matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' as const : 'light' as const,\n  }));\n  const browser = page.context().browser();\n  const request: PresentationAcquireRequest = {\n    subject: {\n      id: options.subjectId ?? 'presentation',\n      kind: 'fixture',\n      ...(options.title === undefined ? {} : { title: options.title }),\n    },\n    viewport: { ...viewport, ...environment },\n    engine: browser === null ? 'browser@unknown' : `${browser.browserType().name()}@${browser.version()}`,\n    ...(options.fonts === undefined ? {} : { fonts: options.fonts }),\n    ...(options.suspense === undefined ? {} : { suspense: options.suspense }),\n    ...(options.stabilize === undefined ? {} : { stabilize: options.stabilize }),\n  };\n  const raw = await locator.evaluate(\n    (element, [global, sent]: readonly [string, PresentationAcquireRequest]) => {\n      const agent = (globalThis as unknown as Record<string, InstalledPresentationAgent | undefined>)[global];\n      if (agent === undefined) throw new Error(`the presentation sensing agent is not installed at ${global}`);\n      return agent.acquire(element, sent);\n    },\n    [PRESENTATION_AGENT, request] as const,\n  );\n  const acquired = JSON.parse(raw) as PresentationAcquired;\n  try {\n    const roots = [await locator.ariaSnapshot()];\n    for (const portal of acquired.portals) {\n      roots.push(await page.locator(`[${PRESENTATION_ROOT_ATTRIBUTE}=\"${portal.marker}\"]`).ariaSnapshot());\n    }\n    const report = analyzePresentation(acquired.capture, {\n      accessibility: accessibilitySnapshot(request.engine, roots),\n    });\n    if (options.paint !== undefined && options.paint !== false) {\n      const layers = options.paint === true ? undefined : options.paint;\n      await page.evaluate(\n        ([global, instructions, selected]) => {\n          const agent = (globalThis as unknown as Record<string, InstalledPresentationAgent | undefined>)[global];\n          if (agent === undefined) throw new Error(`the presentation sensing agent is not installed at ${global}`);\n          return agent.paint(instructions, selected);\n        },\n        [PRESENTATION_AGENT, report.paint ?? [], layers] as const,\n      );\n    }\n    return report;\n  } finally {\n    await restorePortals(page, acquired);\n  }\n}\n\n/** Remove diagnostic paint without changing the sensed application. */\nexport async function clearPresentationPaint(page: Page): Promise<void> {\n  await page.evaluate((global) => {\n    const agent = (globalThis as unknown as Record<string, InstalledPresentationAgent | undefined>)[global];\n    agent?.clear();\n  }, PRESENTATION_AGENT);\n}\n\n/** Paint one already-focused structural reading without acquiring the page again. */\nexport async function paintPresentationFocus(\n  page: Page,\n  focus: PresentationFocus,\n  layers?: readonly PaintLayer[],\n): Promise<number> {\n  return paintPresentationInstructions(page, focus.paint, layers);\n}\n\n/** Paint one explicit alignment reading without acquiring the page again. */\nexport async function paintPresentationAlignment(\n  page: Page,\n  reading: PresentationAlignmentReading,\n): Promise<number> {\n  return paintPresentationInstructions(page, reading.paint, ['axes']);\n}\n\n/** Paint one explicit spacing reading without acquiring the page again. */\nexport async function paintPresentationSpacing(\n  page: Page,\n  reading: PresentationSpacingReading,\n): Promise<number> {\n  return paintPresentationInstructions(page, reading.paint, ['spacing']);\n}\n\n/** Paint one product-declared hierarchy reading without acquiring the page again. */\nexport async function paintPresentationHierarchy(\n  page: Page,\n  reading: PresentationHierarchyReading,\n): Promise<number> {\n  return paintPresentationInstructions(page, reading.paint, ['findings']);\n}\n\nasync function paintPresentationInstructions(\n  page: Page,\n  instructions: readonly PaintInstruction[],\n  layers?: readonly PaintLayer[],\n): Promise<number> {\n  await install(page);\n  return page.evaluate(\n    ([global, instructions, selected]) => {\n      const agent = (globalThis as unknown as Record<string, InstalledPresentationAgent | undefined>)[global];\n      if (agent === undefined) throw new Error(`the presentation sensing agent is not installed at ${global}`);\n      return agent.paint(instructions, selected);\n    },\n    [PRESENTATION_AGENT, instructions, layers] as const,\n  );\n}\n\nasync function install(page: Page): Promise<void> {\n  const bundle = await bundlePresentationAgent();\n  await page.addInitScript(bundle);\n  const installed = await page.evaluate(\n    (global) => typeof (globalThis as unknown as Record<string, unknown>)[global] === 'object',\n    PRESENTATION_AGENT,\n  );\n  if (!installed) await page.evaluate(bundle);\n}\n\nasync function restorePortals(page: Page, acquired: PresentationAcquired): Promise<void> {\n  await page.evaluate(\n    ([attribute, portals]) => {\n      for (const portal of portals) {\n        const element = document.querySelector(`[${attribute}=\"${portal.marker}\"]`);\n        if (element === null) continue;\n        if (portal.previous === undefined) element.removeAttribute(attribute);\n        else element.setAttribute(attribute, portal.previous);\n      }\n    },\n    [PRESENTATION_ROOT_ATTRIBUTE, acquired.portals] as const,\n  );\n}\n"]}

package/dist/report.d.ts

@@ -0,0 +1,17 @@
+import type { PresentationSignalRecord } from '@variance-authority/report';
+import type { PresentationHierarchyReading, PresentationReport } from './model.js';
+export interface PresentationSignalOptions {
+    /** Product-owned hierarchy readings evaluated against the before report. */
+    readonly beforeHierarchy?: readonly PresentationHierarchyReading[];
+    /** Product-owned hierarchy readings evaluated against the after report. */
+    readonly afterHierarchy?: readonly PresentationHierarchyReading[];
+}
+/**
+ * Project presentation evidence into the durable regression-report signal.
+ *
+ * Missing reports or layout findings are incomparable, never clean. The result
+ * records consequences without changing the regression verdict or prescribing
+ * a design response.
+ */
+export declare function presentationSignal(before: PresentationReport | undefined, after: PresentationReport | undefined, options?: PresentationSignalOptions): PresentationSignalRecord;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.js

@@ -0,0 +1,126 @@
+import { digestValue } from '@variance-authority/core';
+import { comparePresentation } from './compare.js';
+import { codeUnitCompare } from './math.js';
+/**
+ * Project presentation evidence into the durable regression-report signal.
+ *
+ * Missing reports or layout findings are incomparable, never clean. The result
+ * records consequences without changing the regression verdict or prescribing
+ * a design response.
+ */
+export function presentationSignal(before, after, options = {}) {
+    if (before === undefined || after === undefined) {
+        return {
+            verdict: 'incomparable',
+            because: before === undefined && after === undefined
+                ? 'neither side supplied a presentation reading'
+                : `${before === undefined ? 'the baseline' : 'the candidate'} supplied no presentation reading`,
+            ...(before === undefined ? {} : { before: before.digest }),
+            ...(after === undefined ? {} : { after: after.digest }),
+        };
+    }
+    const beforeFindings = findingsOf(before, options.beforeHierarchy ?? []);
+    const afterFindings = findingsOf(after, options.afterHierarchy ?? []);
+    if (beforeFindings === undefined || afterFindings === undefined) {
+        return {
+            verdict: 'incomparable',
+            because: beforeFindings === undefined && afterFindings === undefined
+                ? 'neither presentation reading contained layout findings'
+                : `${beforeFindings === undefined ? 'the baseline' : 'the candidate'} contained no layout findings`,
+            before: before.digest,
+            after: after.digest,
+        };
+    }
+    const comparison = comparePresentation(before, after);
+    const information = {
+        contentPreserved: comparison.information.content.preserved,
+        characters: difference(comparison.information.characters),
+        elements: difference(comparison.information.elements),
+        repeatedObjects: difference(comparison.information.repeatedObjects),
+    };
+    const effects = effectsOf(beforeFindings, afterFindings);
+    const informationChanged = !information.contentPreserved ||
+        information.characters.delta !== 0 ||
+        information.elements.delta !== 0 ||
+        information.repeatedObjects.delta !== 0;
+    return {
+        verdict: effects.length > 0 || informationChanged ? 'changed' : 'unchanged',
+        before: before.digest,
+        after: after.digest,
+        information,
+        effects,
+    };
+}
+function findingsOf(report, hierarchy) {
+    for (const reading of hierarchy) {
+        if (reading.report !== report.digest) {
+            throw new Error(`presentation hierarchy ${reading.contract.id} reads ${reading.report}, not ${report.digest}`);
+        }
+    }
+    if (report.findings === undefined && hierarchy.length === 0)
+        return undefined;
+    return [...(report.findings ?? []), ...hierarchy.flatMap((reading) => reading.findings)];
+}
+function effectsOf(before, after) {
+    const left = indexFindings(before, 'baseline');
+    const right = indexFindings(after, 'candidate');
+    const identities = [...new Set([...left.keys(), ...right.keys()])].sort(codeUnitCompare);
+    const effects = [];
+    for (const identity of identities) {
+        const previous = left.get(identity);
+        const current = right.get(identity);
+        const finding = current ?? previous;
+        const common = {
+            rule: finding.rule,
+            owner: finding.owner,
+            nodes: [...finding.nodes].sort(codeUnitCompare),
+            ...(finding.pattern === undefined ? {} : { pattern: finding.pattern }),
+            ...(finding.contract === undefined ? {} : { contract: finding.contract }),
+        };
+        if (previous === undefined) {
+            effects.push({ ...common, transition: 'introduced', after: evidence(current) });
+            continue;
+        }
+        if (current === undefined) {
+            effects.push({ ...common, transition: 'resolved', before: evidence(previous) });
+            continue;
+        }
+        if (digestValue(previous.measurements) === digestValue(current.measurements)) {
+            continue;
+        }
+        effects.push({
+            ...common,
+            transition: 'persisted',
+            before: evidence(previous),
+            after: evidence(current),
+        });
+    }
+    return effects;
+}
+function indexFindings(findings, side) {
+    const result = new Map();
+    for (const finding of findings) {
+        const identity = identityOf(finding);
+        if (result.has(identity)) {
+            throw new Error(`${side} presentation has duplicate finding identity ${identity}`);
+        }
+        result.set(identity, finding);
+    }
+    return result;
+}
+function identityOf(finding) {
+    return [
+        finding.rule,
+        finding.owner,
+        finding.pattern ?? '',
+        finding.contract ?? '',
+        [...finding.nodes].sort(codeUnitCompare).join(','),
+    ].join('\0');
+}
+function evidence(finding) {
+    return { finding: finding.id, measurements: finding.measurements };
+}
+function difference(value) {
+    return { ...value, delta: value.after - value.before };
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAOvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAc5C;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAsC,EACtC,KAAqC,EACrC,OAAO,GAA8B,EAAE;IAEvC,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAChD,OAAO;YACL,OAAO,EAAE,cAAc;YACvB,OAAO,EACL,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;gBACzC,CAAC,CAAC,8CAA8C;gBAChD,CAAC,CAAC,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,mCAAmC;YACnG,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;YAC1D,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;SACxD,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IACzE,MAAM,aAAa,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;IACtE,IAAI,cAAc,KAAK,SAAS,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChE,OAAO;YACL,OAAO,EAAE,cAAc;YACvB,OAAO,EACL,cAAc,KAAK,SAAS,IAAI,aAAa,KAAK,SAAS;gBACzD,CAAC,CAAC,wDAAwD;gBAC1D,CAAC,CAAC,GAAG,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,+BAA+B;YACvG,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,KAAK,CAAC,MAAM;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtD,MAAM,WAAW,GAAkC;QACjD,gBAAgB,EAAE,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC,SAAS;QAC1D,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC;QACzD,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC;QACrD,eAAe,EAAE,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,eAAe,CAAC;KACpE,CAAC;IACF,MAAM,OAAO,GAAG,SAAS,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,kBAAkB,GACtB,CAAC,WAAW,CAAC,gBAAgB;QAC7B,WAAW,CAAC,UAAU,CAAC,KAAK,KAAK,CAAC;QAClC,WAAW,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC;QAChC,WAAW,CAAC,eAAe,CAAC,KAAK,KAAK,CAAC,CAAC;IAE1C,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;QAC3E,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,WAAW;QACX,OAAO;KACR,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,MAA0B,EAC1B,SAAkD;IAElD,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CACb,0BAA0B,OAAO,CAAC,QAAQ,CAAC,EAAE,UAAU,OAAO,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,CAC9F,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9E,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,SAAS,CAChB,MAAsC,EACtC,KAAqC;IAErC,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAEzF,MAAM,OAAO,GAA+B,EAAE,CAAC;IAC/C,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,OAAO,IAAI,QAAS,CAAC;QACrC,MAAM,MAAM,GAAG;YACb,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC;YAC/C,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YACtE,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;SAC1E,CAAC;QACF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAQ,CAAC,EAAE,CAAC,CAAC;YACjF,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAChF,SAAS;QACX,CAAC;QACD,IAAI,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7E,SAAS;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACX,GAAG,MAAM;YACT,UAAU,EAAE,WAAW;YACvB,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;YAC1B,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC;SACzB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,aAAa,CACpB,QAAwC,EACxC,IAA8B;IAE9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IACtD,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,gDAAgD,QAAQ,EAAE,CAAC,CAAC;QACrF,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,OAA4B;IAC9C,OAAO;QACL,OAAO,CAAC,IAAI;QACZ,OAAO,CAAC,KAAK;QACb,OAAO,CAAC,OAAO,IAAI,EAAE;QACrB,OAAO,CAAC,QAAQ,IAAI,EAAE;QACtB,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;KACnD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,QAAQ,CAAC,OAA4B;IAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;AACrE,CAAC;AAED,SAAS,UAAU,CAAC,KAA0D;IAK5E,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;AACzD,CAAC","sourcesContent":["import { digestValue } from '@variance-authority/core';\nimport type {\n  PresentationEffectEvidence,\n  PresentationEffectRecord,\n  PresentationInformationRecord,\n  PresentationSignalRecord,\n} from '@variance-authority/report';\nimport { comparePresentation } from './compare.js';\nimport { codeUnitCompare } from './math.js';\nimport type {\n  PresentationFinding,\n  PresentationHierarchyReading,\n  PresentationReport,\n} from './model.js';\n\nexport interface PresentationSignalOptions {\n  /** Product-owned hierarchy readings evaluated against the before report. */\n  readonly beforeHierarchy?: readonly PresentationHierarchyReading[];\n  /** Product-owned hierarchy readings evaluated against the after report. */\n  readonly afterHierarchy?: readonly PresentationHierarchyReading[];\n}\n\n/**\n * Project presentation evidence into the durable regression-report signal.\n *\n * Missing reports or layout findings are incomparable, never clean. The result\n * records consequences without changing the regression verdict or prescribing\n * a design response.\n */\nexport function presentationSignal(\n  before: PresentationReport | undefined,\n  after: PresentationReport | undefined,\n  options: PresentationSignalOptions = {},\n): PresentationSignalRecord {\n  if (before === undefined || after === undefined) {\n    return {\n      verdict: 'incomparable',\n      because:\n        before === undefined && after === undefined\n          ? 'neither side supplied a presentation reading'\n          : `${before === undefined ? 'the baseline' : 'the candidate'} supplied no presentation reading`,\n      ...(before === undefined ? {} : { before: before.digest }),\n      ...(after === undefined ? {} : { after: after.digest }),\n    };\n  }\n\n  const beforeFindings = findingsOf(before, options.beforeHierarchy ?? []);\n  const afterFindings = findingsOf(after, options.afterHierarchy ?? []);\n  if (beforeFindings === undefined || afterFindings === undefined) {\n    return {\n      verdict: 'incomparable',\n      because:\n        beforeFindings === undefined && afterFindings === undefined\n          ? 'neither presentation reading contained layout findings'\n          : `${beforeFindings === undefined ? 'the baseline' : 'the candidate'} contained no layout findings`,\n      before: before.digest,\n      after: after.digest,\n    };\n  }\n\n  const comparison = comparePresentation(before, after);\n  const information: PresentationInformationRecord = {\n    contentPreserved: comparison.information.content.preserved,\n    characters: difference(comparison.information.characters),\n    elements: difference(comparison.information.elements),\n    repeatedObjects: difference(comparison.information.repeatedObjects),\n  };\n  const effects = effectsOf(beforeFindings, afterFindings);\n  const informationChanged =\n    !information.contentPreserved ||\n    information.characters.delta !== 0 ||\n    information.elements.delta !== 0 ||\n    information.repeatedObjects.delta !== 0;\n\n  return {\n    verdict: effects.length > 0 || informationChanged ? 'changed' : 'unchanged',\n    before: before.digest,\n    after: after.digest,\n    information,\n    effects,\n  };\n}\n\nfunction findingsOf(\n  report: PresentationReport,\n  hierarchy: readonly PresentationHierarchyReading[],\n): readonly PresentationFinding[] | undefined {\n  for (const reading of hierarchy) {\n    if (reading.report !== report.digest) {\n      throw new Error(\n        `presentation hierarchy ${reading.contract.id} reads ${reading.report}, not ${report.digest}`,\n      );\n    }\n  }\n  if (report.findings === undefined && hierarchy.length === 0) return undefined;\n  return [...(report.findings ?? []), ...hierarchy.flatMap((reading) => reading.findings)];\n}\n\nfunction effectsOf(\n  before: readonly PresentationFinding[],\n  after: readonly PresentationFinding[],\n): PresentationEffectRecord[] {\n  const left = indexFindings(before, 'baseline');\n  const right = indexFindings(after, 'candidate');\n  const identities = [...new Set([...left.keys(), ...right.keys()])].sort(codeUnitCompare);\n\n  const effects: PresentationEffectRecord[] = [];\n  for (const identity of identities) {\n    const previous = left.get(identity);\n    const current = right.get(identity);\n    const finding = current ?? previous!;\n    const common = {\n      rule: finding.rule,\n      owner: finding.owner,\n      nodes: [...finding.nodes].sort(codeUnitCompare),\n      ...(finding.pattern === undefined ? {} : { pattern: finding.pattern }),\n      ...(finding.contract === undefined ? {} : { contract: finding.contract }),\n    };\n    if (previous === undefined) {\n      effects.push({ ...common, transition: 'introduced', after: evidence(current!) });\n      continue;\n    }\n    if (current === undefined) {\n      effects.push({ ...common, transition: 'resolved', before: evidence(previous) });\n      continue;\n    }\n    if (digestValue(previous.measurements) === digestValue(current.measurements)) {\n      continue;\n    }\n    effects.push({\n      ...common,\n      transition: 'persisted',\n      before: evidence(previous),\n      after: evidence(current),\n    });\n  }\n  return effects;\n}\n\nfunction indexFindings(\n  findings: readonly PresentationFinding[],\n  side: 'baseline' | 'candidate',\n): ReadonlyMap<string, PresentationFinding> {\n  const result = new Map<string, PresentationFinding>();\n  for (const finding of findings) {\n    const identity = identityOf(finding);\n    if (result.has(identity)) {\n      throw new Error(`${side} presentation has duplicate finding identity ${identity}`);\n    }\n    result.set(identity, finding);\n  }\n  return result;\n}\n\nfunction identityOf(finding: PresentationFinding): string {\n  return [\n    finding.rule,\n    finding.owner,\n    finding.pattern ?? '',\n    finding.contract ?? '',\n    [...finding.nodes].sort(codeUnitCompare).join(','),\n  ].join('\\0');\n}\n\nfunction evidence(finding: PresentationFinding): PresentationEffectEvidence {\n  return { finding: finding.id, measurements: finding.measurements };\n}\n\nfunction difference(value: { readonly before: number; readonly after: number }): {\n  readonly before: number;\n  readonly after: number;\n  readonly delta: number;\n} {\n  return { ...value, delta: value.after - value.before };\n}\n"]}

package/dist/spacing.d.ts

@@ -0,0 +1,4 @@
+import type { PresentationReport, PresentationSpacingAxis, PresentationSpacingReading } from './model.js';
+/** Measure spacing across consecutive immediate children of one box or composition. */
+export declare function inspectPresentationSpacing(report: PresentationReport, ownerId: string, members: readonly string[], axis: PresentationSpacingAxis): PresentationSpacingReading;
+//# sourceMappingURL=spacing.d.ts.map

package/dist/spacing.js

@@ -0,0 +1,112 @@
+import { median, round } from './math.js';
+/** Measure spacing across consecutive immediate children of one box or composition. */
+export function inspectPresentationSpacing(report, ownerId, members, axis) {
+    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)];
+    if (uniqueMembers.length < 2)
+        throw new Error('presentation spacing needs at least two distinct members');
+    const selected = uniqueMembers.map((id) => {
+        const node = byId.get(id);
+        if (node === undefined)
+            throw new Error(`presentation spacing member ${id} is not in report ${report.digest}`);
+        if (node.parent !== ownerId) {
+            throw new Error(`presentation spacing member ${id} is not an immediate child of owner ${ownerId}`);
+        }
+        return node;
+    });
+    const positions = uniqueMembers.map((id) => owner.children.indexOf(id));
+    const ordered = positions.every((position, index) => index === 0 || position === positions[index - 1] + 1);
+    if (!ordered)
+        throw new Error('presentation spacing members must be consecutive in owner child order');
+    const separations = selected.slice(0, -1).map((from, index) => {
+        const to = selected[index + 1];
+        const relation = report.graph.relations.find((candidate) => candidate.kind === 'separates' && candidate.from === from.id && candidate.to === to.id);
+        if (relation === undefined)
+            throw new Error(`presentation spacing has no separation ${from.id} → ${to.id}`);
+        const orderedOverlap = relation.axis === 'overlap' && (axis === 'vertical'
+            ? to.rect.y >= from.rect.y
+            : to.rect.x >= from.rect.x);
+        if (relation.axis !== axis && !orderedOverlap) {
+            throw new Error(`presentation spacing separation ${from.id} → ${to.id} is ${relation.axis}, not ${axis}`);
+        }
+        if (relation.distancePx === undefined || relation.boundaryStrength === undefined) {
+            throw new Error(`presentation spacing separation ${from.id} → ${to.id} is incomplete`);
+        }
+        return {
+            from,
+            to,
+            distancePx: relation.distancePx,
+            boundaryStrength: relation.boundaryStrength,
+            ...(relation.spacingCluster === undefined ? {} : { spacingCluster: relation.spacingCluster }),
+        };
+    });
+    const distances = separations.map((separation) => separation.distancePx);
+    const boundaries = separations.map((separation) => separation.boundaryStrength);
+    return {
+        formatVersion: 1,
+        report: report.digest,
+        owner,
+        axis,
+        members: selected,
+        separations,
+        distance: pixelRange(distances),
+        boundary: scalarRange(boundaries),
+        paint: separations.map((separation) => paint(ownerId, axis, separation)),
+    };
+}
+function pixelRange(values) {
+    return {
+        minPx: round(Math.min(...values), 2),
+        medianPx: round(median(values), 2),
+        maxPx: round(Math.max(...values), 2),
+    };
+}
+function scalarRange(values) {
+    return {
+        min: round(Math.min(...values)),
+        median: round(median(values)),
+        max: round(Math.max(...values)),
+    };
+}
+function paint(owner, axis, separation) {
+    const label = `${separation.distancePx}px · boundary ${separation.boundaryStrength}`;
+    const id = `spacing:${separation.from.id}:${separation.to.id}`;
+    if (axis === 'vertical') {
+        const coordinate = round((separation.from.rect.y + separation.from.rect.height + separation.to.rect.y) / 2, 2);
+        return {
+            id,
+            owner,
+            nodes: [separation.from.id, separation.to.id],
+            layer: 'spacing',
+            shape: 'line',
+            color: '#ffca55',
+            label,
+            line: {
+                x1: Math.min(separation.from.rect.x, separation.to.rect.x),
+                y1: coordinate,
+                x2: Math.max(separation.from.rect.x + separation.from.rect.width, separation.to.rect.x + separation.to.rect.width),
+                y2: coordinate,
+            },
+        };
+    }
+    const coordinate = round((separation.from.rect.x + separation.from.rect.width + separation.to.rect.x) / 2, 2);
+    return {
+        id,
+        owner,
+        nodes: [separation.from.id, separation.to.id],
+        layer: 'spacing',
+        shape: 'line',
+        color: '#ffca55',
+        label,
+        line: {
+            x1: coordinate,
+            y1: Math.min(separation.from.rect.y, separation.to.rect.y),
+            x2: coordinate,
+            y2: Math.max(separation.from.rect.y + separation.from.rect.height, separation.to.rect.y + separation.to.rect.height),
+        },
+    };
+}
+//# sourceMappingURL=spacing.js.map