my-frontend-observer 0.2.0 → 0.4.0

package/docs/COMMANDS.md

@@ -29,6 +29,10 @@ Options:
 - `--targets-file <json-file>` — loads structured semantic observation
   targets from a local JSON file instead of `--target`. Cannot be combined
   with `--target`. See "Structured semantic targets" below.
+- `--scroll-scenario-file <json-file>` — loads one bounded runtime scroll
+  scenario from a local JSON file. May be combined with either `--target` or
+  `--targets-file` (it is independent of target configuration). See "Scroll
+  scenario (`--scroll-scenario-file`)" below.
 - `--output <directory>` — portable, relative output location for the
   observation artifact (same contract as the request's `outputLocation`; no
   drive letter, no leading `/`, no `..` segments).
@@ -59,7 +63,7 @@ diagnostics print one per line as `[code] message`.
 
 ### Structured semantic targets (`--targets-file`)
 
-**Current status: shipped as part of the published `my-frontend-observer@0.2.0`
+**Current status: shipped as part of the published `my-frontend-observer@0.3.0`
 package.** `--target` (CSS shorthand) remains fully supported alongside it.
 
 `--targets-file <json-file>` is the public entry point to the v0.2 canonical
@@ -124,6 +128,240 @@ my-frontend-observer observe `
   --output observations
 ```
 
+### Scroll scenario (`--scroll-scenario-file`)
+
+**Current status: shipped as part of the published `my-frontend-observer@0.3.0`
+package.** Observation schema is `1.2.0`.
+
+`--scroll-scenario-file <json-file>` is the public entry point to the v0.3
+runtime scroll-scenario contract established in `src/request/request.ts`
+(`ScrollScenario`/`ScrollAction`) and executed in `src/browser/`. It supplies
+exactly the value of the normalized request's `scrollScenario` field - the
+file root *is* the scenario object itself, with no wrapper field (unlike
+`--targets-file`'s `{ "targets": [...] }` root).
+
+A request supports **zero or one** scroll scenario. There are exactly two
+supported action kinds:
+
+Window scrolling:
+
+```json
+{
+  "action": {
+    "kind": "window-scroll-by",
+    "deltaX": 0,
+    "deltaY": 600
+  }
+}
+```
+
+Target scrolling (the `target` value must be the stable `name` of one of the
+observation's own configured targets - never a CSS selector, DOM id, or
+source symbol):
+
+```json
+{
+  "action": {
+    "kind": "target-scroll-by",
+    "target": "tool-workspace",
+    "deltaX": 0,
+    "deltaY": 400
+  }
+}
+```
+
+`deltaX`/`deltaY` are signed integers bounded to `[-20000, 20000]`; at least
+one must be non-zero (both zero is rejected). Every scroll/action rule -
+supported action kind, required fields, delta types/bounds, the both-zero
+rule, and the stable-target-name reference for `target-scroll-by` - is
+enforced by the same `normalizeRequest()` validator used everywhere else, not
+duplicated in CLI code; `--scroll-scenario-file` itself only validates that
+the file is readable, is valid JSON, and has a non-array object root.
+
+The observer performs the requested scroll immediately (no smooth-scroll
+animation), waits exactly two `requestAnimationFrame` cycles, and captures a
+final runtime snapshot - the same final state that the observation's ordinary
+`pageEvidence`, `targetEvidence`, and `screenshot.png` describe. The actual
+resulting scroll position is browser-authoritative and may be clamped by
+document/element boundaries; a scenario that produces no movement (already at
+a boundary, or a non-scrollable target) is still a valid, successfully
+persisted observation, never a fabricated failure.
+
+Usable with either target input mode:
+
+```powershell
+my-frontend-observer observe `
+  --url http://localhost:3000/ `
+  --target workspace=.workspace `
+  --scroll-scenario-file .\scroll.json `
+  --output observations
+```
+
+```powershell
+my-frontend-observer observe `
+  --url http://localhost:3000/ `
+  --targets-file .\targets.json `
+  --scroll-scenario-file .\scroll.json `
+  --output observations
+```
+
+`--target` and `--targets-file` remain mutually exclusive with each other,
+exactly as before; `--scroll-scenario-file` is independent of both and is
+never itself a third mutually-exclusive target mode. `window-scroll-by`
+requires no configured target at all.
+
+The path may be relative (resolved from the current working directory) or
+absolute; it is operational input only - like `--targets-file`'s path, it
+never affects the observation's request identity and is never written into
+`manifest.json`. Two different scenario files with identical content produce
+the same `requestId`; only the requested scenario *configuration*
+participates in identity, never the runtime outcome (actual scroll
+distance, clamping, or scroll-owner result).
+
+If a `target-scroll-by` scenario's configured action target cannot be
+uniquely resolved at runtime (missing, ambiguous, or otherwise unavailable),
+the scroll is not performed, no movement is fabricated, and the observation
+persists honestly - typically as `partial` - carrying the same
+`target-missing`/`target-ambiguous`/`browser-evidence-unavailable` diagnostic
+that any other unresolved configured target would produce.
+
+## `compare`
+
+**Current status: shipped as part of the published `my-frontend-observer@0.4.0`
+package.** Comparison schema is `1.0.0`, independent of and never reused for
+the observation schema (`1.2.0`).
+
+`my-frontend-observer compare` (or `node dist/cli.js compare` from a source
+checkout) reads two already-persisted observation artifacts and derives
+before/after evidence purely from their existing content:
+
+```text
+my-frontend-observer compare --before <observation-artifact-root> --after <observation-artifact-root> --output <directory> [options]
+```
+
+Required:
+
+- `--before <path>` — root directory of the "before" persisted observation
+  artifact (the directory containing its `manifest.json`, as produced by
+  `observe`).
+- `--after <path>` — root directory of the "after" persisted observation
+  artifact.
+- `--output <directory>` — portable, relative output location for the
+  comparison artifact (same contract as `observe --output`).
+
+Options:
+
+- `--config-file <json-file>` — loads a comparison configuration directly
+  (no wrapper field): `{ "geometryTolerancePx": <0-10>,
+  "expectedDependencies": [...] }`. Without it, `geometryTolerancePx`
+  defaults to `0.5` CSS px with no declared dependencies. As with
+  `--targets-file`/`--scroll-scenario-file`, `--config-file` only validates
+  file readability, JSON validity, and a non-array object root; every
+  semantic rule (tolerance bounds, dependency property/direction
+  vocabulary, dependency source marker) is enforced by the same domain
+  validator the comparison engine itself uses.
+- `--help` — show `compare` usage.
+
+**Comparison never launches a browser.** It reads two manifests through the
+existing observation-artifact reader, runs the pure comparison engine, and
+persists a portable `manifest.json` — no navigation, no target
+re-resolution, no Chromium process.
+
+On success the command prints exactly:
+
+```text
+Comparison: <comparison-id>
+State: <comparable|comparable-with-warnings|incomparable>
+Artifact: <comparison-artifact-root>
+Differences: <count>
+Relationship changes: <count>
+Diagnostics: <count>
+```
+
+and exits `0` — **including when `State` is `incomparable`**: comparison
+determining that two observations should not be treated as equivalent
+frontend states is itself a successful outcome, not a failure. The command
+exits nonzero only for invalid CLI syntax, an unreadable/malformed/
+structurally-invalid source artifact, invalid comparison configuration, or
+a failed artifact write.
+
+### Comparability
+
+Before any rendered difference is calculated, the engine evaluates whether
+the two observations are comparable at all:
+
+- **Hard incompatibilities** (force `incomparable`): different logical page
+  URL, different viewport, different browser engine, or a mismatched scroll
+  scenario configuration (no scenario vs. a scenario, or two different
+  scenario configurations).
+- **Warnings** (still `comparable-with-warnings`, comparison proceeds):
+  different producer package version, different browser version, or a
+  changed/added/removed configured target.
+- **Unassessed dimensions** the observer does not yet model (theme,
+  authenticated state, application state) are always recorded, never
+  silently claimed identical.
+
+An `incomparable` result still persists a structurally valid
+`ComparisonArtifact`: the comparability reasons are recorded, and ordinary
+rendered differences/relationship changes stay empty rather than fabricated.
+
+### Difference and relationship evidence
+
+For a `comparable`/`comparable-with-warnings` result, the manifest's
+`differences` and `relationshipChanges` arrays carry structured before/
+after evidence: appeared/disappeared targets (only for a stable target name
+configured on both sides — a target added/removed from configuration is
+recorded separately as a `configurationChanges` entry, never fabricated as
+appeared/disappeared), moved/resized targets, visibility changes, clipping
+changes, actual dimensional overflow changes, DOM containment changes,
+page-size changes, scroll-owner changes, and layout-relationship
+transitions (e.g. `does-not-overlap` → `overlaps`, or
+`document-width-fits-viewport` → `document-width-exceeds-viewport`) reused
+verbatim from the same canonical relationship engine `observe` output feeds
+Batch 2's `deriveLayoutRelationships`.
+
+### Explicit dependency evidence (non-causal)
+
+`--config-file`'s `expectedDependencies` lets you declare an expected
+layout relationship such as "`navigation.width` decreases →
+`workspace.width` increases" using only the frozen `x`/`y`/`width`/`height`
+property vocabulary and `increase`/`decrease`/`change`/`unchanged`
+direction vocabulary. Each declaration is evaluated independently against
+the two observations and persists exactly one outcome: `consistent`,
+`not-observed`, `contradictory-to-declaration`, or `unavailable`. **The
+observer never infers a dependency from co-change, and never emits a
+causal claim, a PASS/FAIL verdict, or a change-contract decision** — v0.4
+produces comparison evidence; whether that evidence satisfies some
+contract is v0.5+ scope.
+
+### Path privacy
+
+`--before`, `--after`, `--config-file`, and `--output` are operational
+filesystem input only. None of them affect `comparisonRequestId`, and none
+of them are written into the persisted manifest — the manifest instead
+retains logical source references (`observationId`, `requestId`,
+`producer`, `observationSchemaVersion`, and the source `screenshot.path`).
+Two semantically identical observation/config pairs read from different
+filesystem locations produce the same `comparisonRequestId`; each execution
+still gets a fresh `comparisonId`.
+
+### Source observations remain immutable
+
+Comparison is read-only with respect to its inputs: it never modifies
+either source observation's `manifest.json` or `screenshot.png`, and it
+never copies screenshot bytes into the comparison directory — the
+comparison artifact directory contains `manifest.json` only.
+
+Example:
+
+```powershell
+node dist/cli.js compare `
+  --before observations/<before-id> `
+  --after observations/<after-id> `
+  --output comparisons `
+  --config-file .\comparison-config.json
+```
+
 ## Foundation commands
 
 - `npm install` — install dependencies (includes the `playwright` runtime
@@ -146,8 +384,11 @@ my-frontend-observer observe `
 - `npm run build` — clean and compile `src/` (including `src/cli.ts`) to
   `dist/`.
 - `npm run check:docs` — validate canonical documents and roadmap structure.
-- `npm pack --dry-run` — inspect the private package inventory without
-  publishing. The real tarball has been installed and exercised in a clean
-  temporary consumer directory (real Chromium install, real `observe` run,
-  real artifact) as part of v0.1 validation; this is local package
-  validation, not a release/publication step.
+- `npm pack --dry-run` — inspect the public package's tarball inventory
+  before publishing. The real tarball has been installed and exercised in a
+  clean temporary consumer directory (real Chromium install, real `observe`
+  run, real artifact) on Windows, Linux, and macOS as part of v0.1
+  validation, again for v0.2's packed semantic `--targets-file` behavior,
+  and again for v0.3's packed `--scroll-scenario-file` window/target scroll
+  behavior (`scripts/ci/runPackedObservationSmoke.mjs`); this is local
+  package validation, not a release/publication step.

package/docs/CONTRACTS.md

@@ -2,12 +2,12 @@
 
 ## Current contracts
 
-The observation artifact contract is published as `my-frontend-observer@0.2.0`
+The observation artifact contract is published as `my-frontend-observer@0.4.0`
 and proven both from the source checkout and from the packed npm tarball,
-on Windows, Linux, and macOS. The observation schema is `1.1.0` (see "v0.2
-target contract" below, shipped as part of this release):
+on Windows, Linux, and macOS. The observation schema is `1.2.0` (see "v0.2
+target contract" and "v0.3 scroll scenario contract" below):
 
-- artifact kind `my-frontend-observer/observation`, schema version `1.1.0`
+- artifact kind `my-frontend-observer/observation`, schema version `1.2.0`
   (independent of the package version);
 - one artifact root per observation, `<outputLocation>/<observationId>/`,
   containing exactly `manifest.json` (the full `ObservationArtifact`, with
@@ -81,9 +81,174 @@ supplies the structured `{ "targets": [...] }` collection (see
 existing `--target id=css-selector` shorthand - the two are mutually
 exclusive per invocation, and both converge on the same
 `normalizeRequest()`/browser-resolver/artifact path, so a semantic
-observation produces exactly the same `manifest.json` shape (schema `1.1.0`)
-as a CSS-shorthand one. `--targets-file`'s local input path is never part of
-the persisted request identity or artifact.
+observation produces exactly the same `manifest.json` shape as a
+CSS-shorthand one. Schema `1.1.0` was the v0.2 published artifact schema;
+the current v0.4 package emits schema `1.2.0` for both target-input modes
+(target semantics are unchanged from v0.2 - see the v0.3 scroll scenario
+contract below for what schema `1.2.0` actually adds). `--targets-file`'s
+local input path is never part of the persisted request identity or
+artifact.
+
+## v0.3 scroll scenario contract (shipped as part of this release)
+
+v0.3 introduces one optional, additive request/evidence concern: a bounded
+runtime scroll scenario, schema `1.2.0`.
+
+A normalized request may carry `scrollScenario: { action }` with exactly one
+of two frozen action kinds:
+
+- `{ "kind": "window-scroll-by", "deltaX": <int>, "deltaY": <int> }`
+- `{ "kind": "target-scroll-by", "target": "<stable target name>", "deltaX": <int>, "deltaY": <int> }`
+
+`deltaX`/`deltaY` are signed integers bounded to `[-20000, 20000]`; at least
+one must be non-zero. `target-scroll-by.target` refers only to an existing
+stable configured target `name` (never a selector) and resolves through the
+same canonical `resolveConfiguredTargets` algorithm every v0.2 locator kind
+already uses - there is no second target-resolution path. A request with no
+scenario normalizes and identifies exactly as it did before v0.3.
+
+Execution (both action kinds share one code path): perform the immediate,
+non-smooth scroll (`window.scrollBy`/`element.scrollBy`, `behavior:
+'instant'`) on the already-navigated, already-ready page; wait exactly two
+`requestAnimationFrame` cycles; capture a final runtime snapshot. No second
+browser, page, or navigation is ever created. The resulting scroll position
+is browser-authoritative and may be clamped by document/element boundaries;
+a scenario producing no movement is still a valid, successfully persisted
+observation.
+
+The scenario evidence lives entirely inside the existing `manifest.json` as
+one additional optional `scrollScenarioEvidence` field on `ObservationArtifact`
+- there is no separate `scroll.json`/`scenario.json`. It contains:
+
+- `initial`/`final`: bounded `ScrollRuntimeSnapshot`s (window `scrollX`/
+  `scrollY`; the browser's own scrolling-root/`documentElement`/`body`
+  metrics; per-configured-target `scrollTop`/`scrollLeft`/`scrollWidth`/
+  `scrollHeight`/`clientWidth`/`clientHeight`, actual overflow, bounding
+  rectangle, and viewport relation);
+- `transition`: bounded before/after change evidence (window scroll deltas;
+  per-target `scrollTop`/`scrollLeft`/bounding-position/viewport-relation
+  changes; `enteredViewport`/`leftViewport`) - never a generic recursive
+  diff, and a target is simply omitted when either side's evidence isn't
+  itself usable (e.g. it never resolved);
+- `scrollOwner`: one derived `EvidenceField<ScrollOwnerInterpretation>`
+  (`document` | `target:<stable-name>` | `none` | `indeterminate`), always
+  `source: "derived"` with non-empty `derivedFrom` naming the exact
+  contributing scroll-position measurements. Ownership is derived only from
+  observed `scrollTop`/`scrollLeft`/`window.scrollX`/`window.scrollY`
+  changes - never from bounding-rectangle movement (which moves for every
+  configured target whenever the document scrolls), computed overflow,
+  `position: fixed`/`sticky`, or DOM hierarchy.
+
+Actual dimensional overflow (`scrollWidth > clientWidth` /
+`scrollHeight > clientHeight`) is always reported separately from the
+computed `overflow-x`/`overflow-y` CSS declaration; a declared
+`overflow: auto` container with content that fits produces
+`horizontalOverflow`/`verticalOverflow: false`. Viewport relation
+(`above`/`intersecting`/`below`, `intersectsViewport`, `fullyWithinViewport`)
+is derived only from bounding geometry plus viewport size, relative to the
+browser viewport; a hidden/non-rendered target's viewport relation is
+`not-applicable`, never a fabricated geometry claim - hidden and offscreen
+remain distinct evidence concepts, and the existing `target-hidden`
+diagnostic is unaffected.
+
+The ordinary, already-existing `pageEvidence`/`targetEvidence`/
+`screenshot.png` for a scenario observation always describe this same final
+post-action state, never the pre-action state.
+
+The scenario request participates in `requestId`; the runtime result
+(actual scroll distance, clamping, or scroll-owner outcome) never does. The
+public entry point is `my-frontend-observer observe --scroll-scenario-file
+<json-file>` (see `docs/COMMANDS.md`); the file supplies the scenario value
+directly, and its local path is operational input only, exactly like
+`--targets-file`'s path - never persisted, never part of request identity.
+
+## v0.4 comparison contract (shipped as part of this release)
+
+**Current status: shipped as part of the published `my-frontend-observer@0.4.0`
+package.** Observation schema remains `1.2.0`. Comparison is a distinct
+artifact kind and schema, never a bump to the observation schema:
+
+- artifact kind: `my-frontend-observer/comparison`;
+- comparison schema: `1.0.0`.
+
+**Geometry tolerance**: `ComparisonConfig.geometryTolerancePx`, default
+`0.5` CSS px, bounded `[0, 10]`. Suppresses insignificant subpixel noise
+only - never a design contract, never permission for a change.
+
+**Layout relationship graph**: `deriveLayoutRelationships(observation,
+options?)` derives, per observation, a bounded `LayoutRelationshipGraph`
+among configured targets only (≤20 targets, ≤190 unordered pairs):
+horizontal order (`left-of`/`right-of`/`horizontally-overlapping`),
+vertical order (`above`/`below`/`vertically-overlapping`), area overlap
+(`overlaps`/`does-not-overlap`), relative width (`wider-than`/
+`narrower-than`/`equal-width-within-tolerance`), geometric fit
+(`fits-inside`/`does-not-fit-inside` - geometry-only, deliberately distinct
+from DOM containment), vertical sequencing (`follows-vertically`), and one
+page-level relationship (`document-width-fits-viewport`/
+`document-width-exceeds-viewport`). Every relationship carries explicit
+evidence-path provenance back to the source observation. A configured
+target lacking usable geometry is listed as honestly unresolved
+(`not-found`/`ambiguous`/`unavailable`/`hidden`), never fabricated as a
+zero-sized region.
+
+**Comparability**: evaluated before any rendered difference, using exactly
+three states (`comparable`/`comparable-with-warnings`/`incomparable`) with
+structured reasons, never a bare boolean. Hard incompatibilities (page URL,
+viewport, browser engine, scroll-scenario configuration mismatch) force
+`incomparable`; producer-version, browser-version, and target-configuration
+differences are warning-only; theme/authenticated-state/application-state
+identity are recorded as `unassessed` dimensions the observer does not yet
+model - never silently claimed identical. An `incomparable` result still
+persists a structurally valid `ComparisonArtifact` with empty rendered
+differences, not a fabricated comparison.
+
+**Difference categories**: `appeared`/`disappeared` (only for a stable
+target name configured on both sides, transitioning between a definite
+`not-found` and `matched` resolution status - never for a target merely
+added/removed from configuration, which is its own separate
+`configurationChanges` entry), `moved`/`resized` (tolerance-aware, a target
+may be both), `visibility-changed`, `clipping-changed` (reusing the
+canonical `deriveTargetClipping` helper, never re-derived), `horizontal-
+overflow-changed`/`vertical-overflow-changed` (actual dimensional overflow,
+reusing the existing `deriveOverflowEvidence` helper - never inferred from
+a CSS declaration alone), `containment-changed` (reusing existing v0.2
+`TargetContainment` evidence), `page-size-changed`, `scroll-owner-changed`
+(comparing `scrollScenarioEvidence.scrollOwner` only when scenario
+*configuration* already matched), `relative-position-changed` (a relation
+in the horizontal-order/vertical-order/area-overlap families changed - kept
+distinct from plain absolute target movement) and `relationship-changed`
+(every other relationship-family transition). Relationship changes are
+matched by structural identity (family + subject/related target, or the
+page-level key), never by array position.
+
+**Explicit dependency evidence**: `ComparisonConfig.expectedDependencies`
+lets a caller declare an expected relationship between two targets' numeric
+properties (`x`/`y`/`width`/`height`) and directions (`increase`/
+`decrease`/`change`/`unchanged`), always carrying `source:
+"explicit-config"`. The observer never synthesizes a declaration from
+observed co-change. Each declaration evaluates independently to exactly one
+of `consistent`/`not-observed`/`contradictory-to-declaration`/
+`unavailable` - never a causal claim (no `causedBy`/`causalConfidence`/
+`causalScore`/`dependencyStrength`) and never a PASS/FAIL/approval verdict.
+That distinction (evidence vs. contract verdict) is the boundary between
+v0.4 and v0.5+.
+
+**Comparison identity**: `comparisonRequestId` is a pure, deterministic
+function of `{beforeObservationId, afterObservationId, normalized
+ComparisonConfig}` - direction-sensitive (`compare(A, B) !==
+compare(B, A)`), and never includes an operational filesystem path.
+`comparisonId` is fresh per execution (same pattern as `observationId`).
+
+**Source references**: the comparison artifact retains enough logical
+identity to trace back to its authoritative source observations
+(`observationId`, `requestId`, `producer`, `observationSchemaVersion`, and
+the source `screenshot.path`) without embedding the full
+`ObservationArtifact` or copying screenshot bytes. The persisted comparison
+directory contains `manifest.json` only.
+
+The public entry point is `my-frontend-observer compare --before <root>
+--after <root> --output <directory> [--config-file <json-file>]` (see
+`docs/COMMANDS.md`) - comparison itself never launches a browser.
 
 ## Approved v0.1 design inputs
 

package/docs/CURRENT_STATE.md

@@ -1,7 +1,8 @@
 # Current State
 
-The project is published at package version `0.2.0` (roadmap v0.2, Stable
-Semantic Targets and Region Identity; observation schema `1.1.0`).
+The project is published at package version `0.4.0` (roadmap v0.4, Layout
+Relationships, Dependency Evidence, and Before/After Comparison; observation
+schema `1.2.0`; comparison schema `1.0.0`).
 
 ## Greenfield foundation established
 
@@ -175,16 +176,153 @@ schema `1.1.0`.
   `dist/cli.js` (not just the imported `runCli()` function) performs a real
   semantic `--targets-file` observation end to end.
 
+## v0.3 status (Runtime Scrolling, Overflow, and Visibility Behavior) - released as 0.3.0
+
+v0.3 is implemented and released as package version `0.3.0`, observation
+schema `1.2.0`. It was validated as a packed npm tarball in a clean
+consumer environment on Windows, Linux, and macOS before release.
+
+- **Batch 1** froze the `scrollScenario` request/identity/schema contract:
+  `ScrollScenario { action }` with exactly two action kinds
+  (`window-scroll-by`, `target-scroll-by`), signed-integer deltas bounded to
+  `[-20000, 20000]`, `target-scroll-by.target` referencing an existing stable
+  configured target name, scenario configuration participating in
+  `requestId` (runtime results never do), and the full bounded runtime
+  evidence model (`ScrollRuntimeSnapshot`, `ViewportRelationEvidence`,
+  `OverflowEvidence`, scenario transitions, `ScrollOwnerInterpretation`) in
+  schema `1.2.0` (up from `1.1.0`).
+- **Batch 2** implemented real `window-scroll-by` execution
+  (`src/browser/scrollCapture.ts`, `src/domain/scrollEvidence.ts`): initial/
+  final runtime snapshots around an immediate `window.scrollBy({behavior:
+  'instant'})` and exactly two `requestAnimationFrame` cycles, real vertical/
+  horizontal document scrolling, actual-vs-computed overflow, real viewport
+  relation, `enteredViewport`/`leftViewport`, and `document`/`none`
+  scroll-owner evidence - with ordinary final `pageEvidence`/`targetEvidence`
+  and the screenshot always describing the same final post-action state.
+- **Batch 3** implemented real `target-scroll-by` execution against the same
+  canonical `resolveConfiguredTargets` resolution already used by every v0.2
+  locator kind: real nested vertical/horizontal element scrolling, boundary
+  clamping, non-scrollable/no-movement targets, and the completed
+  `document`/`target:<name>`/`none`/`indeterminate` scroll-owner derivation
+  (`src/domain/scrollEvidence.ts#deriveScrollOwner`) - proven never to
+  attribute ownership from bounding-rectangle movement alone in either
+  direction. An unresolved/ambiguous/hidden action target is never scrolled
+  and never fabricated as moved; the existing target diagnostics explain it
+  honestly and the observation still persists.
+- **Batch 4** exposed the existing contract through the real public CLI:
+  `my-frontend-observer observe --scroll-scenario-file <json-file>` (see
+  `docs/COMMANDS.md`). The file supplies the `scrollScenario` value directly
+  (no wrapper field); the CLI/input layer only validates file readability,
+  JSON validity, and a non-array object root - every scenario/action rule
+  stays owned by the existing `normalizeRequest()`. Usable with either
+  `--target` or `--targets-file` (independent of target configuration, never
+  a third mutually-exclusive mode); the scenario-file path is operational
+  input only, never persisted and never part of request identity, exactly
+  like `--targets-file`'s path. CLI output/exit-code semantics are
+  unchanged. Proven via real Chromium (`tests/browser/cliObserve.test.ts`)
+  and the built `dist/cli.js` (`scripts/dev/builtCliScrollScenarioSmoke.mjs`).
+
+## v0.4 status (Layout Relationships, Dependency Evidence, and Before/After Comparison) - released as 0.4.0
+
+v0.4 is implemented and released as package version `0.4.0`; observation
+schema remains `1.2.0`; comparison schema is `1.0.0`. It was validated as a
+packed npm tarball in a clean consumer environment on Windows, Linux, and
+macOS - covering the legacy CSS-shorthand `--target` path, the structured
+`--targets-file` path, both `--scroll-scenario-file` action kinds, and the
+installed `compare` command (comparable and incomparable cases) - before
+release.
+
+- **Batch 1** froze the `my-frontend-observer/comparison` artifact contract
+  (schema `1.0.0`, independent of and never reused for the observation
+  schema): `ComparisonConfig` (geometry tolerance, default `0.5`px, bounded
+  `[0, 10]`px), the bounded layout-relationship vocabulary (horizontal/
+  vertical order, area overlap, relative width, geometric fit, vertical
+  sequencing, page-width fit, clipping), comparability states, the
+  before/after difference vocabulary, and the non-causal explicit
+  dependency-evidence contract, plus `comparisonRequestId`/`comparisonId`
+  identity (`src/domain/relationships.ts`, `src/domain/comparison.ts`,
+  `src/domain/comparisonIdentity.ts`). No derivation, comparison, or
+  persistence.
+- **Batch 2** implemented the one canonical pure derivation engine,
+  `deriveLayoutRelationships(observation, options?)`
+  (`src/domain/relationships.ts`): consumes an existing `ObservationArtifact`
+  only (no Chromium, no re-resolution, no DOM access) and derives a bounded,
+  traceable `LayoutRelationshipGraph` among configured targets - stable
+  target identity, deterministic configured-target ordering, honest
+  unresolved-target handling (not-found/ambiguous/unavailable/hidden, never
+  a fabricated zero-sized region), and evidence-reference provenance for
+  every derived relationship. DOM containment is read directly from the
+  existing `TargetContainment` evidence rather than re-derived, and stays
+  distinct from geometric fit. A standalone `deriveTargetClipping(record)`
+  derives the frozen clipping concept per target from existing layout/style
+  evidence.
+- **Batch 3** implemented the pure before/after comparison engine,
+  `compareObservations(before, after, config?)`
+  (`src/domain/comparisonEngine.ts`): validates both source observations,
+  evaluates comparability before any rendered difference is calculated
+  (hard page-URL/viewport/browser-engine/scroll-scenario mismatches;
+  producer/browser-version and target-configuration warnings), reuses
+  `deriveLayoutRelationships` unchanged for both sides, and derives target/
+  page differences (appeared/disappeared, moved, resized, visibility,
+  clipping, actual overflow, DOM containment, page size, scroll-owner) and
+  relationship changes (matched by family + subject/related target, never
+  array position) - all without launching Chromium, re-resolving targets, or
+  mutating either input observation. Explicit `ComparisonConfig.
+  expectedDependencies` are evaluated into non-causal
+  consistent/not-observed/contradictory-to-declaration/unavailable outcomes
+  only; the observer never infers a dependency from co-change. Comparison
+  identity reuses the existing Batch 1 `buildComparisonRequestIdentity`/
+  `buildComparisonIdentity` verbatim. Persistence
+  (`src/artifacts/comparisonArtifactWriter.ts#writeComparisonArtifact`,
+  atomic, `<outputLocation>/<comparisonId>/manifest.json` only, no copied
+  screenshots) and the application-level `compareAndPersist` use case
+  (`src/application/comparisonService.ts`) are implemented; a narrow
+  `readObservationArtifact` reader
+  (`src/artifacts/artifactReader.ts`) is established ahead of the Batch 4
+  CLI.
+- **Batch 4** exposed the existing comparison workflow through the real
+  public CLI: `my-frontend-observer compare --before <observation-artifact-
+  root> --after <observation-artifact-root> --output <directory>
+  [--config-file <json-file>]` (see `docs/COMMANDS.md`). The CLI stays thin
+  - `src/cli.ts` parses arguments, optionally loads a config file (file
+  readability/JSON validity/object-root only, exactly like
+  `--targets-file`/`--scroll-scenario-file`), and delegates to one new
+  thin application-layer orchestration function,
+  `compareAndPersistFromArtifactRoots`
+  (`src/application/comparisonService.ts`), which reads both observation
+  roots through the existing `readObservationArtifact` reader and calls the
+  existing `compareAndPersist` exactly once - no comparability/geometry/
+  relationship/dependency logic lives in the CLI, and comparison itself
+  never launches Chromium (`src/cli.ts` still imports nothing from
+  `src/artifacts/` or `src/browser/`, matching the pre-existing observe-CLI
+  import-boundary test). `comparable`, `comparable-with-warnings`, and
+  `incomparable` all exit `0` - each is a successful comparison outcome;
+  only a genuine parse/read/domain/persistence failure exits nonzero.
+  Operational paths (`--before`/`--after`/`--config-file`/`--output`) never
+  affect `comparisonRequestId` and are never written into the persisted
+  manifest. Proven end-to-end via real Chromium
+  (`tests/browser/cliCompare.test.ts`) and the built `dist/cli.js`
+  (`scripts/dev/builtCliCompareSmoke.mjs`): unchanged/moved/resized/
+  appeared/disappeared/configuration-only-change/overlap/geometric-fit/
+  page-overflow/clipping/scroll-owner cases, plus an explicit
+  `--config-file` dependency-evidence case, all through the public command
+  surface.
+
+v0.4's canonical relationship derivation, before/after comparison,
+comparability, differences, relationship changes, explicit dependency
+evidence, comparison persistence, and public `compare` CLI are all
+implemented, exercised end-to-end, packed-validated cross-platform, and
+released.
+
 ## Not implemented
 
-- No controlled-scroll behavior, layout/spatial relationship engine,
-  before/after comparison, frontend contracts/change scope, source
-  ownership, my-dev-kit runtime/static integration, orchestrator/lab
-  product integration, viewer, or annotation - all remain v0.3+ and
-  unimplemented.
-- No v0.3–v0.10 capability is implemented.
+- v0.5+ frontend contracts/change scope (baseline approval, requested/
+  protected/preserved change scope, PASS/FAIL verdicts), source ownership,
+  my-dev-kit runtime/static integration, orchestrator/lab product
+  integration, viewer, and annotation all remain unimplemented.
 
 ## Next target
 
-v0.2 is implemented, validated, and released as `0.2.0`. v0.3 (Controlled
-Scroll and Overflow Scenarios) is the next planned version.
+v0.1-v0.4 are implemented, validated, and released (`0.1.0`, `0.2.0`,
+`0.3.0`, `0.4.0`). v0.5 (Executable Frontend Contracts and Explicit Change
+Scope) is next.