my-frontend-observer 0.3.0 → 0.4.0

package/dist/domain/relationships.js

@@ -0,0 +1,343 @@
+import { isValidObservationArtifact } from './schema.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// --- Geometry tolerance -------------------------------------------------------
+/** Suppresses insignificant geometry noise only - never a design contract, never permission for changes. */
+export const GEOMETRY_TOLERANCE_DEFAULT_PX = 0.5;
+export const GEOMETRY_TOLERANCE_MIN_PX = 0;
+export const GEOMETRY_TOLERANCE_MAX_PX = 10;
+export function isValidGeometryTolerancePx(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= GEOMETRY_TOLERANCE_MIN_PX && value <= GEOMETRY_TOLERANCE_MAX_PX;
+}
+export const HORIZONTAL_ORDER_RELATIONSHIPS = ['left-of', 'right-of', 'horizontally-overlapping'];
+export const VERTICAL_ORDER_RELATIONSHIPS = ['above', 'below', 'vertically-overlapping'];
+export const AREA_OVERLAP_RELATIONSHIPS = ['overlaps', 'does-not-overlap'];
+export const RELATIVE_WIDTH_RELATIONSHIPS = ['wider-than', 'narrower-than', 'equal-width-within-tolerance'];
+export const GEOMETRIC_FIT_RELATIONSHIPS = ['fits-inside', 'does-not-fit-inside'];
+/** Rendered-geometry sequencing only - never source DOM order (see docs/CONTRACTS.md target containment discussion). */
+export const VERTICAL_SEQUENCE_RELATIONSHIPS = ['follows-vertically'];
+export const PAGE_WIDTH_RELATIONSHIPS = ['document-width-fits-viewport', 'document-width-exceeds-viewport'];
+/** Every pairwise (two-target) relationship kind this batch freezes. Deliberately bounded - not a general-purpose spatial language. */
+export const PAIRWISE_RELATIONSHIP_KINDS = [
+    ...HORIZONTAL_ORDER_RELATIONSHIPS,
+    ...VERTICAL_ORDER_RELATIONSHIPS,
+    ...AREA_OVERLAP_RELATIONSHIPS,
+    ...RELATIVE_WIDTH_RELATIONSHIPS,
+    ...GEOMETRIC_FIT_RELATIONSHIPS,
+    ...VERTICAL_SEQUENCE_RELATIONSHIPS,
+];
+/** Every page-level (no target pair) relationship kind this batch freezes. */
+export const PAGE_LEVEL_RELATIONSHIP_KINDS = [...PAGE_WIDTH_RELATIONSHIPS];
+export function isValidEvidenceReference(value) {
+    return isPlainObject(value) && typeof value.path === 'string' && value.path.length > 0;
+}
+function isEvidenceReferenceArray(value) {
+    return Array.isArray(value) && value.every((entry) => isValidEvidenceReference(entry));
+}
+export function isValidPairwiseLayoutRelationship(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.kind !== 'string' || !PAIRWISE_RELATIONSHIP_KINDS.includes(value.kind))
+        return false;
+    if (typeof value.subjectTarget !== 'string' || value.subjectTarget.length === 0)
+        return false;
+    if (typeof value.relatedTarget !== 'string' || value.relatedTarget.length === 0)
+        return false;
+    if (value.subjectTarget === value.relatedTarget)
+        return false;
+    return isEvidenceReferenceArray(value.evidence);
+}
+export function isValidPageLevelLayoutRelationship(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.kind !== 'string' || !PAGE_LEVEL_RELATIONSHIP_KINDS.includes(value.kind))
+        return false;
+    return isEvidenceReferenceArray(value.evidence);
+}
+/** A configured target excluded from relationship derivation because it lacks usable geometry - never a fabricated zero-sized rectangle. */
+export const UNRESOLVED_TARGET_REASONS = ['not-found', 'ambiguous', 'unavailable', 'hidden'];
+export function isValidUnresolvedRelationshipTarget(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.target !== 'string' || value.target.length === 0)
+        return false;
+    return typeof value.reason === 'string' && UNRESOLVED_TARGET_REASONS.includes(value.reason);
+}
+export const MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS = 20;
+export const MAX_PAIRWISE_RELATIONSHIP_PAIRS = (MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS * (MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS - 1)) / 2;
+/**
+ * A single unordered pair can carry up to one record per independent
+ * pairwise relationship family (horizontal-order, vertical-order,
+ * area-overlap, relative-width, geometric-fit, vertical-sequence - see
+ * `deriveLayoutRelationships` below), never more than one per family per
+ * pair. This is the resulting bound on `pairwiseRelationships.length`, not a
+ * second target-count configuration.
+ */
+export const PAIRWISE_RELATIONSHIP_FAMILY_COUNT = 6;
+export const MAX_PAIRWISE_RELATIONSHIP_RECORDS = MAX_PAIRWISE_RELATIONSHIP_PAIRS * PAIRWISE_RELATIONSHIP_FAMILY_COUNT;
+export function isValidLayoutRelationshipGraph(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.observationId !== 'string' || value.observationId.length === 0)
+        return false;
+    if (typeof value.requestId !== 'string' || value.requestId.length === 0)
+        return false;
+    if (typeof value.geometryTolerancePx !== 'number' || !Number.isFinite(value.geometryTolerancePx))
+        return false;
+    if (!Array.isArray(value.targets) || !value.targets.every((t) => typeof t === 'string' && t.length > 0))
+        return false;
+    if (new Set(value.targets).size !== value.targets.length)
+        return false;
+    if (!Array.isArray(value.unresolvedTargets) || !value.unresolvedTargets.every((t) => isValidUnresolvedRelationshipTarget(t)))
+        return false;
+    const targetSet = new Set(value.targets);
+    if (value.unresolvedTargets.some((t) => targetSet.has(t.target)))
+        return false;
+    if (!Array.isArray(value.pairwiseRelationships) || !value.pairwiseRelationships.every((r) => isValidPairwiseLayoutRelationship(r)))
+        return false;
+    if (value.pairwiseRelationships.length > MAX_PAIRWISE_RELATIONSHIP_RECORDS)
+        return false;
+    for (const relationship of value.pairwiseRelationships) {
+        if (!targetSet.has(relationship.subjectTarget) || !targetSet.has(relationship.relatedTarget))
+            return false;
+    }
+    if (!Array.isArray(value.pageRelationships) || !value.pageRelationships.every((r) => isValidPageLevelLayoutRelationship(r)))
+        return false;
+    return true;
+}
+/**
+ * Bounded derived clipping concept (docs/PROJECT_MILESTONES.md Milestone 4).
+ * `clipped` requires both actual dimensional overflow on that axis AND a
+ * computed `overflow` value of `hidden`/`clip` on that axis - `auto`,
+ * `scroll`, and `visible` never classify as clipped solely from dimensional
+ * overflow. `unavailable` when the underlying overflow/geometry evidence
+ * cannot support a conclusion - never guessed.
+ */
+export const CLIPPING_STATES = ['clipped', 'not-clipped', 'unavailable'];
+export const CLIPPING_OVERFLOW_STYLES = ['hidden', 'clip'];
+export function isValidTargetClippingEvidence(value) {
+    if (!isPlainObject(value))
+        return false;
+    return (typeof value.horizontal === 'string' &&
+        CLIPPING_STATES.includes(value.horizontal) &&
+        typeof value.vertical === 'string' &&
+        CLIPPING_STATES.includes(value.vertical));
+}
+/**
+ * Pure per-target clipping derivation from one target's own existing
+ * `layout`/`style` evidence (never a scroll scenario - normal target
+ * evidence already carries `scrollWidth`/`scrollHeight`/`clientWidth`/
+ * `clientHeight`/`overflowX`/`overflowY`). `TargetClippingEvidence` has no
+ * slot in `LayoutRelationshipGraph` (that graph is spatial/page-level only,
+ * per the frozen Batch 1 vocabulary) - this is a standalone per-target
+ * derivation for callers (e.g. a later comparison engine) that need it
+ * directly from an `ObservationArtifact`'s `targetEvidence`, one target at a
+ * time. `unavailable` (never guessed) when the underlying layout/style
+ * evidence is not itself available - this naturally covers an unresolved
+ * target without any special-casing. A resolved-but-`display:none` target
+ * naturally computes `not-clipped` too: its `scrollWidth`/`clientWidth` are
+ * both `0`, so `scrollWidth > clientWidth` is false - clipping is never
+ * inferred from hidden-ness itself.
+ */
+export function deriveTargetClipping(record) {
+    const layoutField = record.layout;
+    const styleField = record.style;
+    if (layoutField.state !== 'available' || styleField.state !== 'available') {
+        return { horizontal: 'unavailable', vertical: 'unavailable' };
+    }
+    const layout = layoutField.value;
+    const style = styleField.value;
+    const isClippingOverflowStyle = (value) => CLIPPING_OVERFLOW_STYLES.includes(value);
+    const horizontalOverflow = layout.scrollWidth > layout.clientWidth;
+    const verticalOverflow = layout.scrollHeight > layout.clientHeight;
+    return {
+        horizontal: horizontalOverflow && isClippingOverflowStyle(style.overflowX) ? 'clipped' : 'not-clipped',
+        vertical: verticalOverflow && isClippingOverflowStyle(style.overflowY) ? 'clipped' : 'not-clipped',
+    };
+}
+// --- deriveLayoutRelationships (v0.4 Batch 2 canonical derivation engine) ----
+/**
+ * Pure tolerance-aware geometry predicates (Batch 1's frozen rules,
+ * verbatim). Every predicate is a total function over exactly one relation
+ * family, so it can never itself produce a contradictory pair of values
+ * (e.g. `left-of` and `right-of` for the same call) - the caller decides
+ * `subject`/`related` once per pair and each family is evaluated exactly
+ * once for that fixed direction.
+ */
+function horizontalOrderOf(a, b, tolerance) {
+    if (a.right <= b.x + tolerance)
+        return 'left-of';
+    if (b.right <= a.x + tolerance)
+        return 'right-of';
+    return 'horizontally-overlapping';
+}
+function verticalOrderOf(a, b, tolerance) {
+    if (a.bottom <= b.y + tolerance)
+        return 'above';
+    if (b.bottom <= a.y + tolerance)
+        return 'below';
+    return 'vertically-overlapping';
+}
+function areaOverlapOf(a, b, tolerance) {
+    const overlapWidth = Math.min(a.right, b.right) - Math.max(a.x, b.x);
+    const overlapHeight = Math.min(a.bottom, b.bottom) - Math.max(a.y, b.y);
+    return overlapWidth > tolerance && overlapHeight > tolerance ? 'overlaps' : 'does-not-overlap';
+}
+function relativeWidthOf(a, b, tolerance) {
+    if (a.width > b.width + tolerance)
+        return 'wider-than';
+    if (a.width < b.width - tolerance)
+        return 'narrower-than';
+    return 'equal-width-within-tolerance';
+}
+function geometricFitOf(a, b, tolerance) {
+    const fits = a.x >= b.x - tolerance && a.y >= b.y - tolerance && a.right <= b.right + tolerance && a.bottom <= b.bottom + tolerance;
+    return fits ? 'fits-inside' : 'does-not-fit-inside';
+}
+/**
+ * `follows-vertically` is the one family whose vocabulary has a single
+ * value (not a total 3-way partition like the others), so it is emitted
+ * only when one target's geometry actually precedes the other's - never for
+ * both directions, never when they vertically overlap. The direction is
+ * decided by actual rendered geometry, not configured target order:
+ * `above(x, y)` and "y follows x" share the same tolerance-relative
+ * condition, so whichever of the pair is algebraically "above" the other
+ * becomes `relatedTarget` and the one that follows becomes `subjectTarget`.
+ */
+function verticalSequenceOf(x, y, tolerance) {
+    if (x.geometry.bottom <= y.geometry.y + tolerance)
+        return { subjectTarget: y.name, relatedTarget: x.name };
+    if (y.geometry.bottom <= x.geometry.y + tolerance)
+        return { subjectTarget: x.name, relatedTarget: y.name };
+    return undefined;
+}
+function geometryEvidence(a, b) {
+    return [{ path: `targetEvidence.${a}.geometry` }, { path: `targetEvidence.${b}.geometry` }];
+}
+/** Maps a configured target's resolution/visibility evidence to the frozen unresolved-target reason vocabulary - never a fabricated relationship for a target that cannot honestly carry one. */
+function classifyUnresolvedTarget(record) {
+    if (!record)
+        return 'unavailable';
+    const resolutionField = record.resolution;
+    if (resolutionField.state === 'available' || resolutionField.state === 'partial') {
+        const status = resolutionField.value.selectionStatus;
+        if (status === 'not-found')
+            return 'not-found';
+        if (status === 'ambiguous')
+            return 'ambiguous';
+        if (status === 'unavailable')
+            return 'unavailable';
+    }
+    return 'unavailable';
+}
+/**
+ * The one canonical pure derivation from an already-captured
+ * `ObservationArtifact` to a `LayoutRelationshipGraph` (real Chromium ->
+ * ObservationArtifact -> **relationship derivation** -> comparability ->
+ * comparison -> ComparisonArtifact, see docs/ARCHITECTURE.md). Deterministic
+ * and synchronous: same `observation`/`geometryTolerancePx` in, same graph
+ * out, every time - no Chromium, target re-resolution, DOM access, randomness,
+ * clock, filesystem, or network involved, and `observation` is never
+ * mutated.
+ *
+ * Scope, by construction:
+ * - only targets present in `observation.requestConfig.targets` are ever
+ *   considered (bounded at the existing 20-target/190-pair request limit -
+ *   never arbitrary DOM/accessibility-tree traversal);
+ * - a configured target missing usable geometry (never resolved, or
+ *   resolved but reported not-visible) becomes an `unresolvedTargets` entry
+ *   with an honest reason, never a fabricated zero-sized relation;
+ * - for each unordered pair of geometry-eligible targets, exactly one
+ *   record per relationship family is derived, with `subjectTarget`/
+ *   `relatedTarget` fixed to that pair's configured order (earlier
+ *   configured target is always `subjectTarget`) for every family except
+ *   `follows-vertically` (see `verticalSequenceOf`) - so
+ *   `pairwiseRelationships.length` never exceeds
+ *   `MAX_PAIRWISE_RELATIONSHIP_RECORDS`;
+ * - DOM containment is deliberately not re-derived here: it already exists
+ *   as `targetEvidence.<name>.containment` on the observation itself (see
+ *   `TargetContainment` in domain/schema.ts, explicitly documented there as
+ *   "never a layout/relationship graph") and stays separate from
+ *   `fits-inside`/`does-not-fit-inside`, which is geometry-only;
+ * - the page-width relationship is derived only when both
+ *   `pageEvidence.documentWidth` and `pageEvidence.viewportWidth` are
+ *   themselves available - never defaulted to "fits" when evidence is
+ *   missing.
+ */
+export function deriveLayoutRelationships(observation, options = {}) {
+    const validation = isValidObservationArtifact(observation);
+    if (!validation.valid) {
+        return { ok: false, reason: `cannot derive relationships from an invalid ObservationArtifact: ${validation.reason}` };
+    }
+    const geometryTolerancePx = options.geometryTolerancePx ?? GEOMETRY_TOLERANCE_DEFAULT_PX;
+    if (!isValidGeometryTolerancePx(geometryTolerancePx)) {
+        return {
+            ok: false,
+            reason: `geometryTolerancePx must be a finite number in [${GEOMETRY_TOLERANCE_MIN_PX}, ${GEOMETRY_TOLERANCE_MAX_PX}]`,
+        };
+    }
+    const configuredNames = observation.requestConfig.targets.map((target) => target.name);
+    if (configuredNames.length > MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS) {
+        return {
+            ok: false,
+            reason: `observation.requestConfig.targets has ${configuredNames.length} entries, exceeding the ${MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS}-target relationship-derivation bound`,
+        };
+    }
+    const eligible = [];
+    const unresolvedTargets = [];
+    for (const name of configuredNames) {
+        const record = observation.targetEvidence[name];
+        const geometryField = record?.geometry;
+        if (!record || geometryField?.state !== 'available') {
+            unresolvedTargets.push({ target: name, reason: classifyUnresolvedTarget(record) });
+            continue;
+        }
+        const visibilityField = record.visibility;
+        if ((visibilityField.state === 'available' || visibilityField.state === 'partial') && visibilityField.value.visible === false) {
+            unresolvedTargets.push({ target: name, reason: 'hidden' });
+            continue;
+        }
+        eligible.push({ name, geometry: geometryField.value });
+    }
+    const pairwiseRelationships = [];
+    for (let i = 0; i < eligible.length; i += 1) {
+        const subject = eligible[i];
+        for (let j = i + 1; j < eligible.length; j += 1) {
+            const related = eligible[j];
+            const evidence = geometryEvidence(subject.name, related.name);
+            pairwiseRelationships.push({ kind: horizontalOrderOf(subject.geometry, related.geometry, geometryTolerancePx), subjectTarget: subject.name, relatedTarget: related.name, evidence }, { kind: verticalOrderOf(subject.geometry, related.geometry, geometryTolerancePx), subjectTarget: subject.name, relatedTarget: related.name, evidence }, { kind: areaOverlapOf(subject.geometry, related.geometry, geometryTolerancePx), subjectTarget: subject.name, relatedTarget: related.name, evidence }, { kind: relativeWidthOf(subject.geometry, related.geometry, geometryTolerancePx), subjectTarget: subject.name, relatedTarget: related.name, evidence }, { kind: geometricFitOf(subject.geometry, related.geometry, geometryTolerancePx), subjectTarget: subject.name, relatedTarget: related.name, evidence });
+            const sequence = verticalSequenceOf(subject, related, geometryTolerancePx);
+            if (sequence) {
+                pairwiseRelationships.push({
+                    kind: 'follows-vertically',
+                    subjectTarget: sequence.subjectTarget,
+                    relatedTarget: sequence.relatedTarget,
+                    evidence: geometryEvidence(sequence.subjectTarget, sequence.relatedTarget),
+                });
+            }
+        }
+    }
+    const pageRelationships = [];
+    const documentWidthField = observation.pageEvidence.documentWidth;
+    const viewportWidthField = observation.pageEvidence.viewportWidth;
+    const documentWidth = documentWidthField?.state === 'available' && typeof documentWidthField.value === 'number' ? documentWidthField.value : undefined;
+    const viewportWidth = viewportWidthField?.state === 'available' && typeof viewportWidthField.value === 'number' ? viewportWidthField.value : undefined;
+    if (documentWidth !== undefined && viewportWidth !== undefined) {
+        pageRelationships.push({
+            kind: documentWidth <= viewportWidth + geometryTolerancePx ? 'document-width-fits-viewport' : 'document-width-exceeds-viewport',
+            evidence: [{ path: 'pageEvidence.documentWidth' }, { path: 'pageEvidence.viewportWidth' }],
+        });
+    }
+    const graph = {
+        observationId: observation.observationId,
+        requestId: observation.requestId,
+        geometryTolerancePx,
+        targets: eligible.map((entry) => entry.name),
+        unresolvedTargets,
+        pairwiseRelationships,
+        pageRelationships,
+    };
+    return { ok: true, graph };
+}
+//# sourceMappingURL=relationships.js.map

package/dist/domain/relationships.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.js","sourceRoot":"","sources":["../../src/domain/relationships.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { EvidenceState, EvidenceSource, EvidenceField } from './domain/evidence.js';
-export { isValidEvidenceField } from './domain/evidence.js';
+export { isValidEvidenceField, evidenceValue } from './domain/evidence.js';
 export type { DiagnosticCode, DiagnosticSeverity, Diagnostic } from './domain/diagnostics.js';
 export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
 export type { CompletionState, RequestPhase } from './domain/completion.js';
@@ -19,3 +19,16 @@ export type { PersistedObservationResult } from './artifacts/types.js';
 export { MANIFEST_FILENAME, SCREENSHOT_FILENAME } from './artifacts/artifactWriter.js';
 export type { ApplicationObservationResult } from './application/observationPersistence.js';
 export { buildObservationArtifact, persistBrowserCapture, observe } from './application/observationPersistence.js';
+export type { HorizontalOrderRelationship, VerticalOrderRelationship, AreaOverlapRelationship, RelativeWidthRelationship, GeometricFitRelationship, VerticalSequenceRelationship, PageWidthRelationship, PairwiseRelationshipKind, PageLevelRelationshipKind, EvidenceReference, PairwiseLayoutRelationship, PageLevelLayoutRelationship, UnresolvedTargetReason, UnresolvedRelationshipTarget, LayoutRelationshipGraph, ClippingState, ClippingOverflowStyle, TargetClippingEvidence, DeriveLayoutRelationshipsOptions, DeriveLayoutRelationshipsResult, } from './domain/relationships.js';
+export { HORIZONTAL_ORDER_RELATIONSHIPS, VERTICAL_ORDER_RELATIONSHIPS, AREA_OVERLAP_RELATIONSHIPS, RELATIVE_WIDTH_RELATIONSHIPS, GEOMETRIC_FIT_RELATIONSHIPS, VERTICAL_SEQUENCE_RELATIONSHIPS, PAGE_WIDTH_RELATIONSHIPS, PAIRWISE_RELATIONSHIP_KINDS, PAGE_LEVEL_RELATIONSHIP_KINDS, MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS, MAX_PAIRWISE_RELATIONSHIP_PAIRS, PAIRWISE_RELATIONSHIP_FAMILY_COUNT, MAX_PAIRWISE_RELATIONSHIP_RECORDS, CLIPPING_STATES, CLIPPING_OVERFLOW_STYLES, isValidEvidenceReference, isValidPairwiseLayoutRelationship, isValidPageLevelLayoutRelationship, isValidUnresolvedRelationshipTarget, isValidLayoutRelationshipGraph, isValidTargetClippingEvidence, deriveTargetClipping, deriveLayoutRelationships, } from './domain/relationships.js';
+export type { DependencyProperty, DependencyDirection, ExpectedDependencySource, DependencyTermDeclaration, ExpectedDependencyDeclaration, DependencyEvidenceOutcome, ExpectedDependencyEvidence, ComparisonConfig, ComparabilityState, ComparabilityReasonCode, ComparabilityReasonSeverity, ComparabilityReason, ComparabilityResult, TargetConfigurationChangeKind, TargetConfigurationChange, DifferenceKind, ComparisonDifferenceSubject, ComparisonDifference, RelationshipChangeRecord, ComparisonSourceObservationReference, ComparisonArtifact, ComparisonSchemaValidationResult, } from './domain/comparison.js';
+export { COMPARISON_ARTIFACT_KIND, COMPARISON_SCHEMA_VERSION, GEOMETRY_TOLERANCE_DEFAULT_PX, GEOMETRY_TOLERANCE_MIN_PX, GEOMETRY_TOLERANCE_MAX_PX, isValidGeometryTolerancePx, DEPENDENCY_PROPERTIES, DEPENDENCY_DIRECTIONS, EXPECTED_DEPENDENCY_SOURCES, isValidExpectedDependencyDeclaration, DEPENDENCY_EVIDENCE_OUTCOMES, isValidExpectedDependencyEvidence, isValidComparisonConfig, COMPARABILITY_STATES, COMPARABILITY_REASON_CODES, COMPARABILITY_REASON_SEVERITY, isValidComparabilityResult, TARGET_CONFIGURATION_CHANGE_KINDS, isValidTargetConfigurationChange, DIFFERENCE_KINDS, isValidComparisonDifference, isValidComparisonSourceObservationReference, isValidComparisonArtifact, } from './domain/comparison.js';
+export { buildComparisonRequestIdentity, buildComparisonIdentity } from './domain/comparisonIdentity.js';
+export type { CompareObservationsResult } from './domain/comparisonEngine.js';
+export { compareObservations, evaluateComparability, evaluateExpectedDependencies, compareTargetConfiguration } from './domain/comparisonEngine.js';
+export type { PersistedComparisonResult, WriteComparisonArtifactOptions } from './artifacts/comparisonArtifactWriter.js';
+export { COMPARISON_MANIFEST_FILENAME, writeComparisonArtifact } from './artifacts/comparisonArtifactWriter.js';
+export type { ReadObservationArtifactResult } from './artifacts/artifactReader.js';
+export { readObservationArtifact } from './artifacts/artifactReader.js';
+export type { CompareAndPersistOptions, ApplicationComparisonResult } from './application/comparisonService.js';
+export { DEFAULT_COMPARISON_OUTPUT_LOCATION, compareAndPersist, compareAndPersistFromArtifactRoots } from './application/comparisonService.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { isValidEvidenceField } from './domain/evidence.js';
+export { isValidEvidenceField, evidenceValue } from './domain/evidence.js';
 export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
 export { deriveCompletion } from './domain/completion.js';
 export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, TARGET_LANDMARK_ROLES, getProducerInfo, isValidObservationArtifact, } from './domain/schema.js';
@@ -9,4 +9,11 @@ export { classifyUrl, classifyRedirect, classifySubresource, classifyPopup, clas
 export { runBrowserCapture } from './application/browserCaptureService.js';
 export { MANIFEST_FILENAME, SCREENSHOT_FILENAME } from './artifacts/artifactWriter.js';
 export { buildObservationArtifact, persistBrowserCapture, observe } from './application/observationPersistence.js';
+export { HORIZONTAL_ORDER_RELATIONSHIPS, VERTICAL_ORDER_RELATIONSHIPS, AREA_OVERLAP_RELATIONSHIPS, RELATIVE_WIDTH_RELATIONSHIPS, GEOMETRIC_FIT_RELATIONSHIPS, VERTICAL_SEQUENCE_RELATIONSHIPS, PAGE_WIDTH_RELATIONSHIPS, PAIRWISE_RELATIONSHIP_KINDS, PAGE_LEVEL_RELATIONSHIP_KINDS, MAX_CONFIGURED_TARGETS_FOR_RELATIONSHIPS, MAX_PAIRWISE_RELATIONSHIP_PAIRS, PAIRWISE_RELATIONSHIP_FAMILY_COUNT, MAX_PAIRWISE_RELATIONSHIP_RECORDS, CLIPPING_STATES, CLIPPING_OVERFLOW_STYLES, isValidEvidenceReference, isValidPairwiseLayoutRelationship, isValidPageLevelLayoutRelationship, isValidUnresolvedRelationshipTarget, isValidLayoutRelationshipGraph, isValidTargetClippingEvidence, deriveTargetClipping, deriveLayoutRelationships, } from './domain/relationships.js';
+export { COMPARISON_ARTIFACT_KIND, COMPARISON_SCHEMA_VERSION, GEOMETRY_TOLERANCE_DEFAULT_PX, GEOMETRY_TOLERANCE_MIN_PX, GEOMETRY_TOLERANCE_MAX_PX, isValidGeometryTolerancePx, DEPENDENCY_PROPERTIES, DEPENDENCY_DIRECTIONS, EXPECTED_DEPENDENCY_SOURCES, isValidExpectedDependencyDeclaration, DEPENDENCY_EVIDENCE_OUTCOMES, isValidExpectedDependencyEvidence, isValidComparisonConfig, COMPARABILITY_STATES, COMPARABILITY_REASON_CODES, COMPARABILITY_REASON_SEVERITY, isValidComparabilityResult, TARGET_CONFIGURATION_CHANGE_KINDS, isValidTargetConfigurationChange, DIFFERENCE_KINDS, isValidComparisonDifference, isValidComparisonSourceObservationReference, isValidComparisonArtifact, } from './domain/comparison.js';
+export { buildComparisonRequestIdentity, buildComparisonIdentity } from './domain/comparisonIdentity.js';
+export { compareObservations, evaluateComparability, evaluateExpectedDependencies, compareTargetConfiguration } from './domain/comparisonEngine.js';
+export { COMPARISON_MANIFEST_FILENAME, writeComparisonArtifact } from './artifacts/comparisonArtifactWriter.js';
+export { readObservationArtifact } from './artifacts/artifactReader.js';
+export { DEFAULT_COMPARISON_OUTPUT_LOCATION, compareAndPersist, compareAndPersistFromArtifactRoots } from './application/comparisonService.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAmC1D,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAetF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGzH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEvF,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG3E,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAmC1D,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAetF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGzH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEvF,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAwBnH,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,EAC3B,+BAA+B,EAC/B,wBAAwB,EACxB,2BAA2B,EAC3B,6BAA6B,EAC7B,wCAAwC,EACxC,+BAA+B,EAC/B,kCAAkC,EAClC,iCAAiC,EACjC,eAAe,EACf,wBAAwB,EACxB,wBAAwB,EACxB,iCAAiC,EACjC,kCAAkC,EAClC,mCAAmC,EACnC,8BAA8B,EAC9B,6BAA6B,EAC7B,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AA0BnC,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACrB,2BAA2B,EAC3B,oCAAoC,EACpC,4BAA4B,EAC5B,iCAAiC,EACjC,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,0BAA0B,EAC1B,iCAAiC,EACjC,gCAAgC,EAChC,gBAAgB,EAChB,2BAA2B,EAC3B,2CAA2C,EAC3C,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAGzG,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAGpJ,OAAO,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAGhH,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,kCAAkC,EAAE,iBAAiB,EAAE,kCAAkC,EAAE,MAAM,oCAAoC,CAAC"}

package/docs/ARCHITECTURE.md

@@ -3,7 +3,7 @@
 ## Current scaffold architecture
 
 The current repository is one published TypeScript ESM package
-(`my-frontend-observer@0.3.0`):
+(`my-frontend-observer@0.4.0`):
 
 - `src/cli.ts` is the real, thin `observe` command entry point (argument
   parsing/output only).
@@ -45,8 +45,8 @@ Playwright or the filesystem-write path directly. Batch 6 closed the
 remaining real-Chromium coverage gap (a genuine navigation failure, distinct
 from a readiness timeout or a pre-launch safety rejection) and validated the
 packed npm tarball end to end in a clean consumer environment, independent
-of the source checkout. There is still no controlled-scroll/comparison
-behavior.
+of the source checkout. At the end of the v0.1 implementation there was no
+controlled-scroll or comparison behavior.
 
 ## Current v0.2 architecture (released/current architecture)
 
@@ -108,6 +108,79 @@ is still one canonical `observe()` application use case and one artifact
 writer; `scrollScenarioEvidence` is simply one more optional field on the
 same `ObservationArtifact`.
 
+## Current v0.4 architecture (released/current architecture)
+
+v0.4 adds one new downstream pipeline that consumes `ObservationArtifact`
+values rather than producing them - it never adds a second browser lifecycle,
+target resolver, or observation engine:
+
+```text
+ObservationArtifact before  ObservationArtifact after
+        \                          /
+         `--------.       .-------'
+                    \     /
+              artifact reader (src/artifacts/artifactReader.ts)
+                       ↓
+              comparability evaluation (src/domain/comparisonEngine.ts)
+                       ↓
+    canonical relationship derivation, called for each side independently
+              (src/domain/relationships.ts#deriveLayoutRelationships)
+                       ↓
+              canonical comparison derivation
+              (src/domain/comparisonEngine.ts#compareObservations)
+                       ↓
+                ComparisonArtifact
+                       ↓
+    atomic comparison writer (src/artifacts/comparisonArtifactWriter.ts)
+
+CLI `compare`
+        ↓
+application service only (src/application/comparisonService.ts)
+        ↓
+[reader → domain comparison → writer, as above]
+```
+
+`src/domain/relationships.ts` froze the layout-relationship contract and
+implements the one canonical pure derivation,
+`deriveLayoutRelationships(observation, options?)`: horizontal/vertical
+order, area overlap, relative width, geometric fit, vertical sequencing,
+page-width fit/exceeds, and a standalone `deriveTargetClipping(record)` -
+all computed only from an already-captured `ObservationArtifact`'s own
+`targetEvidence`/`pageEvidence`, never from a second browser query. DOM
+containment is read directly from the existing v0.2 `TargetContainment`
+evidence rather than re-derived, and stays a distinct concept from
+geometric fit.
+
+`src/domain/comparisonEngine.ts` implements the one canonical pure
+before/after engine, `compareObservations(before, after, config?)`:
+validates both source artifacts, evaluates comparability *before* any
+rendered difference is calculated, calls `deriveLayoutRelationships` once
+per side with the same tolerance, and derives target/page differences and
+relationship changes. `src/artifacts/comparisonArtifactWriter.ts` persists
+the result atomically (sibling temp directory, then one rename) as
+`<outputLocation>/<comparisonId>/manifest.json` only - no screenshot is
+copied; the manifest's `before`/`after` references point back to the
+source observations' own `screenshot.path`. `src/application/
+comparisonService.ts` is the one application-layer seam: `compareAndPersist`
+takes two in-memory `ObservationArtifact`s and does exactly one comparison
+plus exactly one persist; `compareAndPersistFromArtifactRoots` is a thin
+wrapper that additionally reads both sides from disk via the existing
+`src/artifacts/artifactReader.ts#readObservationArtifact` reader (itself
+just a `manifest.json` parse plus the same `isValidObservationArtifact`
+structural gate the writer uses).
+
+`src/cli.ts` gained one new top-level command, `compare`
+(`--before`/`--after`/`--output`/`--config-file`), implemented with the same
+thin-CLI-boundary discipline as `observe`: `parseCompareArgs` handles only
+argument shape/duplication, an optional `loadComparisonConfigFile` reads and
+validates only file readability/JSON-validity/non-array-object-root (exactly
+like `--targets-file`/`--scroll-scenario-file`), and the command body calls
+`compareAndPersistFromArtifactRoots` exactly once. **The CLI's comparison
+path never launches Chromium** - `src/cli.ts` imports nothing from
+`src/browser/` or `src/artifacts/` (it only reaches persistence and artifact
+reading indirectly, through the application-layer seam above), matching the
+same import-boundary discipline already enforced for `observe`.
+
 ## Planned v0.1 architecture constraints
 
 v0.1 planning must preserve these approved boundaries without treating module

package/docs/CI_CD.md

@@ -67,3 +67,32 @@ observations. This was proven on `validation/v0.3-pre-release`
 hash-verified candidate tarball (SHA-256
 `da6cbc18a98d005b84a2f12c06f5c01d390006b53c02176a6c9cdc6d9b9d24d0`) - the
 release candidate for `v0.3.0`.
+
+## v0.4 readiness coverage
+
+The packed-candidate readiness gap that previously existed for the v0.4
+`compare` public command - identified during the v0.4 implementation/
+documentation audit as `V0_4_READINESS_VALIDATION_GAP_EXISTS` - has been
+closed: `scripts/ci/runPackedObservationSmoke.mjs` now also installs the
+candidate tarball, observes a deterministic before/after fixture through
+the installed `observe`, and runs the installed `compare` against both
+resulting artifacts, asserting (through the *installed package's own*
+exported `isValidComparisonArtifact`/`isValidObservationArtifact`, resolved
+from the consumer's own `node_modules` rather than the source checkout):
+comparison artifact kind/schema `1.0.0`, a `comparable` result with a real
+`moved`+`resized` target difference and a real relationship-family
+transition (`does-not-overlap`→`overlaps` and `left-of`→
+`horizontally-overlapping` simultaneously - the same pair the v0.4
+relationship-family matching regression concerns), an explicit
+`--config-file` non-causal dependency-evidence result, an `incomparable`
+result (differing viewport) with the expected blocking comparability
+reason and no fabricated ordinary differences, comparison-manifest path
+privacy (no absolute operational path leakage), retained (never copied)
+before/after screenshot references, a `manifest.json`-only comparison
+directory, and byte-identical source-observation manifests/screenshots
+before and after comparing - on every platform in the matrix, using the
+same single hash-verified candidate tarball as the legacy/semantic/scroll
+observations. This preserves every pre-existing v0.1-v0.3 packed
+observation proof unchanged and adds the v0.4 proof additively, in the same
+script and the same candidate, per the established same-candidate
+architecture (no second `npm pack`, no per-platform rebuild).