my-frontend-observer 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,107 @@
 # Changelog
 
+## 0.4.0 - 2026-08-12
+
+Layout Relationships, Dependency Evidence, and Before/After Comparison.
+
+- New comparison artifact kind `my-frontend-observer/comparison`, schema
+  `1.0.0` - independent of and never reused for the observation schema.
+- Canonical layout-relationship derivation from a single observation:
+  horizontal order (`left-of`/`right-of`/`horizontally-overlapping`),
+  vertical order (`above`/`below`/`vertically-overlapping`), area overlap,
+  relative width, geometric fit (kept explicitly distinct from DOM
+  containment), vertical sequencing (`follows-vertically`), and document-
+  width fit/exceeds-viewport - bounded to configured targets, with explicit
+  evidence-path provenance and honest unresolved-target handling.
+- Comparability analysis, evaluated before any rendered difference:
+  `comparable` / `comparable-with-warnings` / `incomparable`, with
+  structured reasons (hard mismatches on page URL, viewport, browser
+  engine, or scroll-scenario configuration; warnings for producer/browser
+  version and target-configuration differences; theme/authenticated-state/
+  application-state recorded as unassessed, never silently equal).
+- Before/after target and page differences: appeared/disappeared (never
+  confused with a target added/removed from configuration), moved, resized,
+  visibility changes, clipping changes (reusing one canonical clipping
+  derivation), actual horizontal/vertical dimensional-overflow changes, DOM
+  containment changes, page-size changes, and scroll-owner changes - each a
+  structured record with before/after values, deltas where meaningful, and
+  supporting evidence references.
+- Relationship-change detection between two observations, matched by
+  relationship family and subject/related target (never array position),
+  including a `relative-position-changed` distinction from plain absolute
+  target movement.
+- Explicit, non-causal expected-dependency evidence: a caller may declare an
+  expected relationship between two targets' `x`/`y`/`width`/`height`
+  properties and `increase`/`decrease`/`change`/`unchanged` directions; each
+  declaration evaluates independently to `consistent` / `not-observed` /
+  `contradictory-to-declaration` / `unavailable`. The observer never infers
+  a dependency from observed co-change and never produces a causal claim.
+- Deterministic, direction-sensitive comparison identity
+  (`comparisonRequestId`) plus a fresh `comparisonId` per execution;
+  operational filesystem paths never affect identity and are never written
+  into the persisted manifest.
+- Atomic comparison-artifact persistence: `<outputLocation>/<comparisonId>/
+  manifest.json` only - no screenshot bytes are copied; the manifest
+  retains logical references to the source observations' own
+  `screenshot.path`. Source observations are never modified.
+- New public `compare` command: `my-frontend-observer compare --before
+  <observation-artifact-root> --after <observation-artifact-root> --output
+  <directory> [--config-file <json-file>]`. Reads two already-persisted
+  observation artifacts and never launches a browser. `comparable`,
+  `comparable-with-warnings`, and `incomparable` all persist successfully
+  and exit `0`; only invalid syntax, an unreadable/invalid source artifact,
+  invalid configuration, or a failed write exits nonzero.
+
+## 0.3.0 - 2026-08-12
+
+Runtime Scrolling, Overflow, and Visibility Behavior.
+
+- Bounded runtime scroll scenarios: an observation may configure zero or
+  one scroll action, `window-scroll-by` or `target-scroll-by` (signed
+  integer `deltaX`/`deltaY`, bounded to `[-20000, 20000]`, at least one
+  non-zero). Not a generic interaction recorder or browser automation
+  framework - exactly one bounded action per observation.
+- Real `window-scroll-by` execution: vertical and horizontal document
+  scrolling, with browser-authoritative (not calculated) final position,
+  including natural boundary clamping and valid no-movement scenarios.
+- Real `target-scroll-by` execution against the existing stable configured
+  target identity and the same canonical target-resolution path every
+  locator kind already uses: real nested vertical/horizontal element
+  scrolling, boundary clamping, and non-scrollable/no-movement targets. An
+  action target that cannot be uniquely resolved at runtime is never
+  scrolled and never fabricated as moved - the existing target-missing/
+  target-ambiguous/target-hidden diagnostics explain it honestly.
+- Initial/final bounded runtime snapshots (window scroll position, the
+  browser's own scrolling-root/`documentElement`/`body` metrics, and
+  per-configured-target scroll metrics) around an immediate, non-smooth
+  scroll action and an exact two-`requestAnimationFrame` stabilization
+  wait.
+- Actual dimensional overflow (`scrollWidth`/`scrollHeight` vs.
+  `clientWidth`/`clientHeight`) kept explicitly distinct from the computed
+  `overflow-x`/`overflow-y` CSS declaration.
+- Real viewport-relation evidence (`above`/`intersecting`/`below`,
+  `intersectsViewport`, `fullyWithinViewport`) and `enteredViewport`/
+  `leftViewport` scenario transitions; a hidden/non-rendered target's
+  viewport relation is honestly `not-applicable`, never fabricated
+  geometry - hidden and offscreen remain distinct.
+- Bounded before/after scenario transition evidence for window and
+  per-target scroll position, geometry, and viewport relation - not a
+  generic comparison/diff engine.
+- Derived scroll-owner interpretation (`document` /
+  `target:<stable-target-name>` / `none` / `indeterminate`), always
+  traceable (`derivedFrom`) to the underlying observed scroll-position
+  measurements only - never from CSS overflow, bounding-rectangle movement
+  alone, target name, or DOM hierarchy.
+- New `--scroll-scenario-file <json-file>` CLI input, usable together with
+  either `--target` or `--targets-file`; the file path is operational input
+  only, never persisted and never part of request identity, exactly like
+  `--targets-file`'s path.
+- Observation schema `1.2.0` (additive over `1.1.0`).
+- Cross-platform packed-candidate validation: one hash-verified npm
+  candidate tarball proven on Windows, Linux, and macOS, covering the
+  legacy `--target` CSS shorthand, the structured `--targets-file`
+  semantic-target path, and both `--scroll-scenario-file` action kinds.
+
 ## 0.2.0 - 2026-08-11
 
 Stable Semantic Targets and Region Identity.

package/README.md

@@ -6,12 +6,15 @@ in [docs/PROJECT_DESCRIPTION.md](docs/PROJECT_DESCRIPTION.md).
 
 ## Current status
 
-`v0.2.0`, Stable Semantic Targets and Region Identity, is the current
-published release: `my-frontend-observer observe` launches a real,
-sandboxed Chromium browser, enforces a loopback-only safety policy,
-captures a viewport screenshot plus bounded page/target evidence, and
-persists it as one portable `manifest.json` + `screenshot.png` artifact
-(observation schema `1.1.0`).
+`v0.4.0`, Layout Relationships, Dependency Evidence, and Before/After
+Comparison, is the current published release: `my-frontend-observer observe`
+launches a real, sandboxed Chromium browser, enforces a loopback-only safety
+policy, captures a viewport screenshot plus bounded page/target evidence,
+and persists it as one portable `manifest.json` + `screenshot.png` artifact
+(observation schema `1.2.0`). `my-frontend-observer compare` reads two
+already-persisted observation artifacts and derives before/after evidence
+purely from their existing content, persisting a comparison artifact
+(comparison schema `1.0.0`).
 
 Install:
 
@@ -45,14 +48,49 @@ This prints a concise result (`Observation:`/`State:`/`Artifact:`/`Targets:`/
 `Diagnostics:`) and exits `0` on a successfully persisted observation. See
 [docs/COMMANDS.md](docs/COMMANDS.md) for the full flag reference.
 
-`--target <id=css-selector>` remains the simple CSS shorthand. A second,
-structured `--targets-file <json-file>` input mode ships as part of this
-release - supporting a role and accessible name, a stable `id`, a `data-*`
-attribute, a semantic landmark element, exact text, or an ordered fallback
-between several of those. See "Structured semantic targets" in
+`--target <id=css-selector>` remains the simple CSS shorthand. A structured
+`--targets-file <json-file>` input mode - supporting a role and accessible
+name, a stable `id`, a `data-*` attribute, a semantic landmark element,
+exact text, or an ordered fallback between several of those - ships
+alongside it. See "Structured semantic targets" in
 [docs/COMMANDS.md](docs/COMMANDS.md#structured-semantic-targets-targets-file)
 for the exact JSON format.
 
+### Runtime scroll scenarios
+
+`--scroll-scenario-file <json-file>` ships in this release: a real, bounded
+`window-scroll-by` or `target-scroll-by` action performs one immediate,
+non-smooth scroll and captures initial/final runtime evidence - window and
+configured-target scroll position, actual overflow, viewport relation,
+entered/left-viewport transitions, and a derived scroll-owner
+interpretation (`document`, `target:<stable-target-name>`, `none`, or
+`indeterminate`), all persisted in the same `manifest.json`. It may be
+combined with either `--target` or `--targets-file`. See "Scroll scenario"
+in
+[docs/COMMANDS.md](docs/COMMANDS.md#scroll-scenario---scroll-scenario-file)
+for the exact JSON format and flag reference.
+
+### Comparison
+
+`my-frontend-observer compare` reads two already-persisted observation
+artifacts and derives before/after evidence purely from their existing
+content - it never launches a browser:
+
+```powershell
+my-frontend-observer compare `
+  --before observations/<before-observation-id> `
+  --after observations/<after-observation-id> `
+  --output comparisons
+```
+
+(From a source checkout, use `node dist/cli.js compare ...` instead.)
+
+This prints a concise result (`Comparison:`/`State:`/`Artifact:`/
+`Differences:`/`Relationship changes:`/`Diagnostics:`) and exits `0` -
+including when the two observations turn out to be `incomparable`, which is
+itself a successful comparison outcome. See
+[docs/COMMANDS.md](docs/COMMANDS.md) for the full flag reference.
+
 Validation:
 
 ```powershell
@@ -70,8 +108,8 @@ Planning authorities:
   intent and responsibility boundaries.
 - [Project Milestones](docs/PROJECT_MILESTONES.md): complete ordered capability
   design and cross-milestone rules.
-- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1 and v0.2 are
-  released, v0.3 is next.
+- [ROADMAP](docs/ROADMAP.md): version-level requirements; v0.1-v0.4 are
+  released, v0.5 is next.
 - [Current State](docs/CURRENT_STATE.md): retained scaffold and release state.
 
 No sibling ecosystem repository is a runtime dependency of the retained

package/dist/application/comparisonService.d.ts

@@ -0,0 +1,56 @@
+import type { ObservationArtifact } from '../domain/schema.js';
+import type { ComparabilityState, ComparisonConfig } from '../domain/comparison.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { WriteComparisonArtifactOptions } from '../artifacts/comparisonArtifactWriter.js';
+export type { PersistedComparisonResult } from '../artifacts/comparisonArtifactWriter.js';
+/** Default comparison output location, mirroring `request.ts`'s `DEFAULT_OUTPUT_LOCATION` for observations - distinct directories so comparisons never collide with source observations. */
+export declare const DEFAULT_COMPARISON_OUTPUT_LOCATION = "comparisons";
+export interface CompareAndPersistOptions {
+    config?: Partial<ComparisonConfig>;
+    /** Portable, relative output location (validated the same way as an observation's `outputLocation`). Defaults to `DEFAULT_COMPARISON_OUTPUT_LOCATION`. */
+    outputLocation?: string;
+    cwd?: WriteComparisonArtifactOptions['cwd'];
+}
+/**
+ * Observer-owned summary of one full compare-and-persist attempt, with just
+ * enough information for a presentation layer (a future Batch 4 CLI) to
+ * report a result without seeing a raw filesystem exception or persistence
+ * implementation detail.
+ */
+export type ApplicationComparisonResult = {
+    ok: true;
+    comparisonId: string;
+    comparisonRequestId: string;
+    comparability: ComparabilityState;
+    artifactRoot: string;
+    manifestPath: string;
+    differenceCount: number;
+    relationshipChangeCount: number;
+    diagnosticsCount: number;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * The one canonical application-level comparison use case: takes two
+ * already-validated/in-memory `ObservationArtifact`s, runs the existing pure
+ * `compareObservations` exactly once, and - only for a structurally valid
+ * result - persists it exactly once through the existing comparison
+ * writer. Never launches Chromium, never re-resolves targets, never mutates
+ * either source observation.
+ */
+export declare function compareAndPersist(before: ObservationArtifact, after: ObservationArtifact, options?: CompareAndPersistOptions): Promise<ApplicationComparisonResult>;
+/**
+ * The canonical Batch 4 CLI-facing orchestration: reads two already-persisted
+ * observation artifacts by their root directory (each expected to contain
+ * `manifest.json`, mirroring `writeObservationArtifact`'s own layout) through
+ * the existing `readObservationArtifact` reader, then delegates to
+ * `compareAndPersist` exactly once. A thin wrapper only - artifact reading
+ * stays owned by `artifacts/artifactReader.ts`, comparison stays owned by
+ * `domain/comparisonEngine.ts`, and persistence stays owned by
+ * `artifacts/comparisonArtifactWriter.ts`. Kept in `application/` (not
+ * `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly - see `tests/unit/cli.test.ts`'s import-boundary
+ * assertion. Never launches a browser, never re-resolves targets.
+ */
+export declare function compareAndPersistFromArtifactRoots(beforeRoot: string, afterRoot: string, options?: CompareAndPersistOptions): Promise<ApplicationComparisonResult>;

package/dist/application/comparisonService.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { compareObservations } from '../domain/comparisonEngine.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writeComparisonArtifact } from '../artifacts/comparisonArtifactWriter.js';
+import { readObservationArtifact } from '../artifacts/artifactReader.js';
+import { MANIFEST_FILENAME as OBSERVATION_MANIFEST_FILENAME } from '../artifacts/artifactWriter.js';
+/** Default comparison output location, mirroring `request.ts`'s `DEFAULT_OUTPUT_LOCATION` for observations - distinct directories so comparisons never collide with source observations. */
+export const DEFAULT_COMPARISON_OUTPUT_LOCATION = 'comparisons';
+/**
+ * The one canonical application-level comparison use case: takes two
+ * already-validated/in-memory `ObservationArtifact`s, runs the existing pure
+ * `compareObservations` exactly once, and - only for a structurally valid
+ * result - persists it exactly once through the existing comparison
+ * writer. Never launches Chromium, never re-resolves targets, never mutates
+ * either source observation.
+ */
+export async function compareAndPersist(before, after, options = {}) {
+    const result = compareObservations(before, after, options.config ?? {});
+    if (!result.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: result.reason }],
+        };
+    }
+    const rawOutputLocation = options.outputLocation ?? DEFAULT_COMPARISON_OUTPUT_LOCATION;
+    const normalized = normalizeOutputLocation(rawOutputLocation);
+    if (!normalized.ok) {
+        return { ok: false, diagnostics: [normalized.diagnostic] };
+    }
+    const persisted = await writeComparisonArtifact(result.artifact, normalized.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok) {
+        return { ok: false, diagnostics: persisted.diagnostics };
+    }
+    return {
+        ok: true,
+        comparisonId: result.artifact.comparisonId,
+        comparisonRequestId: result.artifact.comparisonRequestId,
+        comparability: result.artifact.comparability.state,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        differenceCount: result.artifact.differences.length,
+        relationshipChangeCount: result.artifact.relationshipChanges.length,
+        diagnosticsCount: result.artifact.diagnostics.length,
+    };
+}
+/**
+ * The canonical Batch 4 CLI-facing orchestration: reads two already-persisted
+ * observation artifacts by their root directory (each expected to contain
+ * `manifest.json`, mirroring `writeObservationArtifact`'s own layout) through
+ * the existing `readObservationArtifact` reader, then delegates to
+ * `compareAndPersist` exactly once. A thin wrapper only - artifact reading
+ * stays owned by `artifacts/artifactReader.ts`, comparison stays owned by
+ * `domain/comparisonEngine.ts`, and persistence stays owned by
+ * `artifacts/comparisonArtifactWriter.ts`. Kept in `application/` (not
+ * `artifacts/`) so `src/cli.ts` can depend on it without importing the
+ * artifacts layer directly - see `tests/unit/cli.test.ts`'s import-boundary
+ * assertion. Never launches a browser, never re-resolves targets.
+ */
+export async function compareAndPersistFromArtifactRoots(beforeRoot, afterRoot, options = {}) {
+    const beforeRead = await readObservationArtifact(path.join(beforeRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!beforeRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--before observation artifact: ${beforeRead.reason}` }],
+        };
+    }
+    const afterRead = await readObservationArtifact(path.join(afterRoot, OBSERVATION_MANIFEST_FILENAME));
+    if (!afterRead.ok) {
+        return {
+            ok: false,
+            diagnostics: [{ code: 'invalid-request', severity: DIAGNOSTIC_SEVERITY['invalid-request'], message: `--after observation artifact: ${afterRead.reason}` }],
+        };
+    }
+    return compareAndPersist(beforeRead.artifact, afterRead.artifact, options);
+}
+//# sourceMappingURL=comparisonService.js.map

package/dist/application/comparisonService.js.map

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

package/dist/application/observationPersistence.js

@@ -26,6 +26,7 @@ export function buildObservationArtifact(capture, request) {
         provenance: { capturedAt: new Date().toISOString(), observationMethod: 'chromium-navigate-and-capture' },
         pageEvidence: capture.pageEvidence,
         targetEvidence: capture.targetEvidence,
+        ...(capture.scrollScenarioEvidence ? { scrollScenarioEvidence: capture.scrollScenarioEvidence } : {}),
         screenshot: { state: 'available', source: 'browser', value: { path: SCREENSHOT_FILENAME } },
         completion,
         diagnostics: capture.diagnostics,

package/dist/application/observationPersistence.js.map

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

package/dist/artifacts/artifactReader.d.ts

@@ -0,0 +1,19 @@
+import type { ObservationArtifact } from '../domain/schema.js';
+export type ReadObservationArtifactResult = {
+    ok: true;
+    artifact: ObservationArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Narrow canonical reader counterpart to `artifactWriter.ts#writeObservationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidObservationArtifact` structural gate the writer itself uses -
+ * never a second validator. Read-only: never mutates the file, never
+ * launches a browser, never resolves the sibling screenshot's bytes (the
+ * manifest's `screenshot.path` field is returned as-is for the caller to
+ * resolve if it needs to). Established here as the canonical reader ahead of
+ * the Batch 4 `compare` CLI's `--before`/`--after` path arguments.
+ */
+export declare function readObservationArtifact(manifestPath: string): Promise<ReadObservationArtifactResult>;

package/dist/artifacts/artifactReader.js

@@ -0,0 +1,36 @@
+import { readFile } from 'node:fs/promises';
+import { isValidObservationArtifact } from '../domain/schema.js';
+/**
+ * Narrow canonical reader counterpart to `artifactWriter.ts#writeObservationArtifact`:
+ * reads one `manifest.json`, parses it, and validates it through the same
+ * `isValidObservationArtifact` structural gate the writer itself uses -
+ * never a second validator. Read-only: never mutates the file, never
+ * launches a browser, never resolves the sibling screenshot's bytes (the
+ * manifest's `screenshot.path` field is returned as-is for the caller to
+ * resolve if it needs to). Established here as the canonical reader ahead of
+ * the Batch 4 `compare` CLI's `--before`/`--after` path arguments.
+ */
+export async function readObservationArtifact(manifestPath) {
+    let raw;
+    try {
+        raw = await readFile(manifestPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `failed to read observation artifact manifest at "${manifestPath}": ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `observation artifact manifest at "${manifestPath}" is not valid JSON: ${message}` };
+    }
+    const validation = isValidObservationArtifact(parsed);
+    if (!validation.valid) {
+        return { ok: false, reason: `observation artifact manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    return { ok: true, artifact: parsed };
+}
+//# sourceMappingURL=artifactReader.js.map

package/dist/artifacts/artifactReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactReader.js","sourceRoot":"","sources":["../../src/artifacts/artifactReader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAIjE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,YAAoB;IAChE,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oDAAoD,YAAY,MAAM,OAAO,EAAE,EAAE,CAAC;IAChH,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,YAAY,wBAAwB,OAAO,EAAE,EAAE,CAAC;IACnH,CAAC;IAED,MAAM,UAAU,GAAG,0BAA0B,CAAC,MAAM,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qCAAqC,YAAY,mCAAmC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;IACxI,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAA6B,EAAE,CAAC;AAC/D,CAAC"}

package/dist/artifacts/comparisonArtifactWriter.d.ts

@@ -0,0 +1,41 @@
+import type { ComparisonArtifact } from '../domain/comparison.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export declare const COMPARISON_MANIFEST_FILENAME = "manifest.json";
+/**
+ * Observer-owned result of persisting one ComparisonArtifact. Mirrors
+ * `PersistedObservationResult`'s shape/semantics but is its own type: a
+ * comparison directory has no screenshot file, and this writer never touches
+ * `src/artifacts/artifactWriter.ts` or its observation-persistence
+ * guarantees.
+ */
+export type PersistedComparisonResult = {
+    ok: true;
+    artifactRoot: string;
+    manifestPath: string;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export interface WriteComparisonArtifactOptions {
+    /** Base directory that `outputLocation` is resolved against. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * Persists one already-assembled, already-validated `ComparisonArtifact` as
+ * one portable artifact directory: `<outputLocation>/<comparisonId>/manifest.json`
+ * only - no screenshot is copied (the manifest's `before`/`after.screenshot`
+ * fields already point back to the source observations; see
+ * `domain/comparisonEngine.ts#sourceReference`), and no `relationships.json`/
+ * `differences.json`/`diff.png` side files are produced.
+ *
+ * Follows the same atomic-write discipline as
+ * `artifacts/artifactWriter.ts#writeObservationArtifact` (sibling temporary
+ * directory, then one atomic rename onto the final name) without sharing its
+ * implementation - a comparison directory has a different, smaller content
+ * shape, and this function never touches observation persistence. A fresh
+ * `comparisonId` per execution normally prevents collisions; an existing
+ * directory at the final path is treated as a genuine collision and
+ * rejected rather than overwritten, so prior comparison evidence is never
+ * destructively replaced.
+ */
+export declare function writeComparisonArtifact(artifact: ComparisonArtifact, outputLocation: string, options?: WriteComparisonArtifactOptions): Promise<PersistedComparisonResult>;

package/dist/artifacts/comparisonArtifactWriter.js

@@ -0,0 +1,67 @@
+import { mkdir, writeFile, rename, rm, access } from 'node:fs/promises';
+import path from 'node:path';
+import { isValidComparisonArtifact } from '../domain/comparison.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+export const COMPARISON_MANIFEST_FILENAME = 'manifest.json';
+function writeFailure(message, details) {
+    const diagnostic = {
+        code: 'artifact-write-failure',
+        severity: DIAGNOSTIC_SEVERITY['artifact-write-failure'],
+        message,
+        ...(details === undefined ? {} : { details }),
+    };
+    return { ok: false, diagnostics: [diagnostic] };
+}
+async function pathExists(candidate) {
+    return access(candidate).then(() => true, () => false);
+}
+/**
+ * Persists one already-assembled, already-validated `ComparisonArtifact` as
+ * one portable artifact directory: `<outputLocation>/<comparisonId>/manifest.json`
+ * only - no screenshot is copied (the manifest's `before`/`after.screenshot`
+ * fields already point back to the source observations; see
+ * `domain/comparisonEngine.ts#sourceReference`), and no `relationships.json`/
+ * `differences.json`/`diff.png` side files are produced.
+ *
+ * Follows the same atomic-write discipline as
+ * `artifacts/artifactWriter.ts#writeObservationArtifact` (sibling temporary
+ * directory, then one atomic rename onto the final name) without sharing its
+ * implementation - a comparison directory has a different, smaller content
+ * shape, and this function never touches observation persistence. A fresh
+ * `comparisonId` per execution normally prevents collisions; an existing
+ * directory at the final path is treated as a genuine collision and
+ * rejected rather than overwritten, so prior comparison evidence is never
+ * destructively replaced.
+ */
+export async function writeComparisonArtifact(artifact, outputLocation, options = {}) {
+    const validation = isValidComparisonArtifact(artifact);
+    if (!validation.valid) {
+        return writeFailure(`refusing to persist an invalid ComparisonArtifact: ${validation.reason}`);
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const outputRoot = path.resolve(cwd, outputLocation);
+    const finalRoot = path.join(outputRoot, artifact.comparisonId);
+    const tempRoot = path.join(outputRoot, `.tmp-${artifact.comparisonId}`);
+    if (await pathExists(finalRoot)) {
+        return writeFailure(`a comparison artifact already exists at "${artifact.comparisonId}"; refusing to overwrite it`, {
+            artifactRoot: finalRoot,
+        });
+    }
+    try {
+        await rm(tempRoot, { recursive: true, force: true });
+        await mkdir(tempRoot, { recursive: true });
+        await writeFile(path.join(tempRoot, COMPARISON_MANIFEST_FILENAME), JSON.stringify(artifact, null, 2), 'utf8');
+        await rename(tempRoot, finalRoot);
+        return {
+            ok: true,
+            artifactRoot: finalRoot,
+            manifestPath: path.join(finalRoot, COMPARISON_MANIFEST_FILENAME),
+        };
+    }
+    catch (err) {
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+        const message = err instanceof Error ? err.message : String(err);
+        return writeFailure(`failed to persist comparison artifact: ${message}`);
+    }
+}
+//# sourceMappingURL=comparisonArtifactWriter.js.map

package/dist/artifacts/comparisonArtifactWriter.js.map

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

package/dist/browser/chromiumAdapter.js

@@ -1,7 +1,9 @@
 import { chromium } from 'playwright';
 import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
 import { classifyUrl, classifyRedirect, classifySubresource, classifyPopup, classifyDownload } from '../safety/policy.js';
-import { capturePageEvidence, captureTargetEvidence } from './evidenceCapture.js';
+import { capturePageEvidence, captureTargetEvidence, resolveConfiguredTargets, findResolvedTarget } from './evidenceCapture.js';
+import { captureScrollRuntimeSnapshot, performWindowScrollBy, performTargetScrollBy, waitTwoAnimationFrames } from './scrollCapture.js';
+import { deriveScrollScenarioTransition, deriveScrollOwner } from '../domain/scrollEvidence.js';
 function diagnostic(code, message) {
     return { code, severity: DIAGNOSTIC_SEVERITY[code], message };
 }
@@ -104,8 +106,52 @@ export async function captureViewportInternal(request) {
             result = { ok: false, diagnostics: [...diagnostics, classifyNavigationError(navigationError, request.readiness.timeoutMs)] };
         }
         else {
-            // Captured from the same live page, after the same readiness point, as
-            // required by Batch 3: no second browser/page is ever opened.
+            // v0.3 Batch 2/3: for a scenario request, resolve configured targets
+            // exactly once (reusing the same canonical resolveConfiguredTargets
+            // algorithm captureTargetEvidence uses below), capture the initial
+            // runtime snapshot, perform the one immediate scroll action (window or
+            // the uniquely-resolved action target - same two-animation-frame
+            // stabilization either way), and capture the final runtime snapshot -
+            // all before the screenshot and ordinary page/target evidence below,
+            // so every one of those downstream captures describes only the final
+            // post-action state. No second navigation, page, or observation ever
+            // happens.
+            let scrollScenarioEvidence;
+            if (request.scrollScenario) {
+                const action = request.scrollScenario.action;
+                const resolvedForScenario = await resolveConfiguredTargets(page, request.targets);
+                try {
+                    const initial = await captureScrollRuntimeSnapshot(page, resolvedForScenario, request.viewport);
+                    if (action.kind === 'window-scroll-by') {
+                        await performWindowScrollBy(page, action.deltaX, action.deltaY);
+                    }
+                    else {
+                        const actionTarget = findResolvedTarget(resolvedForScenario, action.target);
+                        if (actionTarget?.status === 'matched' && actionTarget.handle) {
+                            await performTargetScrollBy(actionTarget.handle, action.deltaX, action.deltaY);
+                        }
+                        // else: the configured action target could not be uniquely
+                        // resolved at runtime (not-found/ambiguous/unavailable) - no
+                        // scroll is performed and no movement is fabricated. The
+                        // existing target-missing/target-ambiguous/target-hidden/
+                        // browser-evidence-unavailable diagnostic for this same target
+                        // name still surfaces below from the ordinary
+                        // captureTargetEvidence pass, so the unresolved action target
+                        // remains honestly explained rather than silently ignored.
+                    }
+                    await waitTwoAnimationFrames(page);
+                    const final = await captureScrollRuntimeSnapshot(page, resolvedForScenario, request.viewport);
+                    const transition = deriveScrollScenarioTransition(initial, final);
+                    const scrollOwner = deriveScrollOwner(transition);
+                    scrollScenarioEvidence = { initial, final, transition, scrollOwner };
+                }
+                finally {
+                    await Promise.all(resolvedForScenario.filter((info) => info.handle).map((info) => info.handle.dispose()));
+                }
+            }
+            // Captured from the same live page, after the same readiness point (and,
+            // for a scenario request, after the scroll action above), as required by
+            // Batch 3/v0.3 Batch 2: no second browser/page is ever opened.
             const screenshotBuffer = await page.screenshot({ type: 'png' });
             const provenance = { engine: 'chromium', version: browser.version() };
             let pageEvidence;
@@ -128,7 +174,15 @@ export async function captureViewportInternal(request) {
                 diagnostics.push(diagnostic('browser-evidence-unavailable', `target evidence collection failed: ${message}`));
                 targetEvidence = {};
             }
-            result = { ok: true, provenance, screenshot: new Uint8Array(screenshotBuffer), pageEvidence, targetEvidence, diagnostics };
+            result = {
+                ok: true,
+                provenance,
+                screenshot: new Uint8Array(screenshotBuffer),
+                pageEvidence,
+                targetEvidence,
+                diagnostics,
+                ...(scrollScenarioEvidence ? { scrollScenarioEvidence } : {}),
+            };
         }
     }
     catch (err) {