my-frontend-observer 0.3.0 → 0.4.0

package/docs/COMMANDS.md

@@ -225,6 +225,143 @@ 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

package/docs/CONTRACTS.md

@@ -2,7 +2,7 @@
 
 ## Current contracts
 
-The observation artifact contract is published as `my-frontend-observer@0.3.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.2.0` (see "v0.2
 target contract" and "v0.3 scroll scenario contract" below):
@@ -81,9 +81,13 @@ 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)
 
@@ -158,6 +162,94 @@ public entry point is `my-frontend-observer observe --scroll-scenario-file
 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
 
 The historical greenfield scaffold plan recorded these v0.1 design decisions:

package/docs/CURRENT_STATE.md

@@ -1,7 +1,8 @@
 # Current State
 
-The project is published at package version `0.3.0` (roadmap v0.3, Runtime
-Scrolling, Overflow, and Visibility Behavior; observation schema `1.2.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
 
@@ -221,15 +222,107 @@ consumer environment on Windows, Linux, and macOS before release.
   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
 
-- Layout/spatial relationship engine, before/after comparison, frontend
-  contracts/change scope, source ownership, my-dev-kit runtime/static
-  integration, orchestrator/lab product integration, viewer, and annotation
-  all remain unimplemented (v0.4+).
+- 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.1, v0.2, and v0.3 are implemented, validated, and released (`0.1.0`,
-`0.2.0`, `0.3.0`). v0.4 (Layout Relationships, Dependency Evidence, and
-Before/After Comparison) 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.

package/docs/DEVELOPMENT.md

@@ -62,10 +62,11 @@ It is what `.github/workflows/pre-release-readiness.yml` runs identically on
 Windows, Linux, and macOS against one shared candidate tarball (see
 `docs/CI_CD.md`); it can also be run locally the same way the workflow runs
 it. It is readiness/CI infrastructure only, not part of the published
-package and never imported by production code. It exercises both the
-legacy CSS-shorthand `--target` packed-observation shape and the
-structured semantic `--targets-file` shape in the same run - see
-`docs/CI_CD.md` for the current v0.2 readiness coverage.
+package and never imported by production code. In the same run it
+exercises the legacy CSS-shorthand `--target` packed-observation shape,
+the structured semantic `--targets-file` shape, a `window-scroll-by`
+scroll scenario, and a `target-scroll-by` scroll scenario - see
+`docs/CI_CD.md` for the current readiness coverage.
 
 `scripts/dev/builtCliTargetsFileSmoke.mjs` is a separate, narrower v0.2
 development smoke, added alongside the `--targets-file` implementation: it
@@ -93,11 +94,33 @@ locally after `npm run build`:
 node scripts/dev/builtCliScrollScenarioSmoke.mjs
 ```
 
-Unlike `scripts/ci/runPackedObservationSmoke.mjs`, neither of these dev
+`scripts/dev/builtCliCompareSmoke.mjs` is the v0.4 equivalent, added
+alongside the `compare` command implementation (shipped as part of the
+published `0.4.0` package - see `docs/CURRENT_STATE.md`): it runs the built
+`dist/cli.js` twice as
+`observe` against an inline disposable local HTTP fixture whose served
+content changes deterministically between the two runs (a real moved/
+resized target, and a page-width transition from fitting to exceeding the
+viewport), then runs the built `dist/cli.js compare` against the two
+resulting persisted observation artifacts. It validates artifact kind/
+schema `1.0.0`, `comparability: "comparable"`, source observation
+references, at least one real `moved` difference and one real page-width
+relationship change, that the comparison directory contains `manifest.json`
+only, that no operational filesystem path leaked into the persisted
+manifest, and that both source observation manifests are byte-identical
+before and after the comparison ran. Run it locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliCompareSmoke.mjs
+```
+
+Unlike `scripts/ci/runPackedObservationSmoke.mjs`, none of these three dev
 smokes is wired into any CI workflow or is a release gate - they are
 source-checkout development evidence only, proving the built CLI's
-`--targets-file`/`--scroll-scenario-file` behavior without installing a
-packed tarball or requiring cross-platform infrastructure. Neither is part
-of the published package. Cross-platform packed validation of the v0.3
-scroll-scenario behavior is `scripts/ci/runPackedObservationSmoke.mjs`'s
-responsibility (see `docs/CI_CD.md`), and has been completed.
+`--targets-file`/`--scroll-scenario-file`/`compare` behavior without
+installing a packed tarball or requiring cross-platform infrastructure.
+None is part of the published package. Cross-platform packed validation of
+both the v0.1-v0.3 observation behavior and the v0.4 `compare` command is
+`scripts/ci/runPackedObservationSmoke.mjs`'s responsibility (see
+`docs/CI_CD.md`) - the same script, against the same single candidate
+tarball per platform.

package/docs/PROJECT_OVERVIEW.md

@@ -16,16 +16,20 @@ The responsibility split is stable:
 ## Current repository state
 
 v0.1, Runtime Observation Foundation; v0.2, Stable Semantic Targets and
-Region Identity; and v0.3, Runtime Scrolling, Overflow, and Visibility
-Behavior, are released, published to npm (current version `0.3.0`,
-observation schema `1.2.0`) and validated as a packed npm tarball in a
-clean consumer environment across Windows, Linux, and macOS: a real
-`observe` CLI command launches Chromium, enforces loopback-only safety,
-captures bounded page/target evidence via legacy CSS-shorthand targets,
-structured semantic `--targets-file` targets, or a bounded
-`--scroll-scenario-file` runtime scroll scenario (`window-scroll-by` or
-`target-scroll-by`), and persists one portable local artifact - see
-`docs/CURRENT_STATE.md` for the implementation summary. v0.4–v0.10 remain
+Region Identity; v0.3, Runtime Scrolling, Overflow, and Visibility Behavior;
+and v0.4, Layout Relationships, Dependency Evidence, and Before/After
+Comparison, are released, published to npm (current version `0.4.0`,
+observation schema `1.2.0`, comparison schema `1.0.0`) and validated as a
+packed npm tarball in a clean consumer environment across Windows, Linux,
+and macOS: a real `observe` CLI command launches Chromium, enforces
+loopback-only safety, captures bounded page/target evidence via legacy
+CSS-shorthand targets, structured semantic `--targets-file` targets, or a
+bounded `--scroll-scenario-file` runtime scroll scenario
+(`window-scroll-by` or `target-scroll-by`), and persists one portable local
+artifact; a real `compare` CLI command reads two already-persisted
+observation artifacts and derives before/after layout-relationship and
+difference evidence without launching a browser - see
+`docs/CURRENT_STATE.md` for the implementation summary. v0.5–v0.10 remain
 future and unimplemented.
 
 The revised dependency path reaches practical coding-agent use before graphical
@@ -52,8 +56,8 @@ Repository-local authorities and navigation:
   capability plan and cross-milestone rules.
 - [ROADMAP.md](ROADMAP.md) owns version-level direction without prewritten
   implementation batches.
-- [CURRENT_STATE.md](CURRENT_STATE.md) records only current scaffold and release
-  state.
+- [CURRENT_STATE.md](CURRENT_STATE.md) records current implementation and
+  release state.
 
 Historical greenfield artifacts and reports are retained as evidence that an
 earlier run overreached into v0.1; they are not current-state authority.

package/docs/QUICKSTART.md

@@ -25,6 +25,11 @@ See [COMMANDS.md](COMMANDS.md) for the full flag reference, including the
 `--targets-file` structured semantic-target input and the
 `--scroll-scenario-file` bounded runtime scroll scenario input.
 
+Once you have two such artifacts, `node dist/cli.js compare --before
+<root> --after <root> --output comparisons` derives before/after evidence
+between them without launching a browser again - see
+[COMMANDS.md](COMMANDS.md#compare) for details.
+
 To validate the repository itself instead:
 
 ```powershell

package/docs/RELEASE.md

@@ -1,16 +1,18 @@
 # Release
 
-`v0.3.0` is published to npm as `my-frontend-observer`, validated on
+`v0.4.0` is published to npm as `my-frontend-observer`, validated on
 Windows, Linux, and macOS as an installed packed-tarball consumer prior to
 publication (covering the legacy CSS-shorthand `--target` path, the
-structured semantic `--targets-file` path, and the bounded
+structured semantic `--targets-file` path, the bounded
 `--scroll-scenario-file` `window-scroll-by`/`target-scroll-by` runtime
-scroll scenario path). No project license has been declared yet; that
+scroll scenario path, and the installed `compare` command's comparable and
+incomparable cases). No project license has been declared yet; that
 decision remains open for a later explicit task.
 
-Observation schema version and package version remain separate: package
-version is `0.3.0`; observation schema is `1.2.0` and does not change
-automatically with the package version.
+Observation, comparison, and package version remain separate: package
+version is `0.4.0`; observation schema is `1.2.0` and comparison schema is
+`1.0.0`, neither of which changes automatically with the package version.
 
-Prior releases: `v0.2.0` (Stable Semantic Targets and Region Identity),
-`v0.1.0` (Runtime Observation Foundation) - see `CHANGELOG.md`.
+Prior releases: `v0.3.0` (Runtime Scrolling, Overflow, and Visibility
+Behavior), `v0.2.0` (Stable Semantic Targets and Region Identity), `v0.1.0`
+(Runtime Observation Foundation) - see `CHANGELOG.md`.

package/docs/ROADMAP.md

@@ -77,6 +77,10 @@ syntax, stabilization, and visibility thresholds.
 
 ## v0.4 — Layout Relationships, Dependency Evidence, and Before/After Comparison
 
+Current status: released as `0.4.0`, published to npm and validated as a
+packed npm tarball in a clean consumer environment on Windows, Linux, and
+macOS. See `docs/CURRENT_STATE.md` for the implementation summary.
+
 Objective/problem: explain whole-layout consequences rather than isolated
 numbers. Required capabilities are containment/order/overlap/fit relationships,
 comparable observation identity, before/after differences, appearance and

package/docs/SECURITY.md

@@ -24,12 +24,25 @@ tests:
   unexpected internal error);
 - the observed target's own content/source is never modified by observation.
 
+## Comparison (`compare`, shipped as part of the published `0.4.0` package)
+
+`my-frontend-observer compare` introduces no new network or browser
+surface: it never
+launches Chromium, never navigates, and never re-observes a target - it only
+reads two local, already-persisted observation-artifact `manifest.json`
+files (`src/artifacts/artifactReader.ts`) through the same structural
+validator the observation writer uses, computes a pure in-memory
+comparison, and writes one local comparison `manifest.json`
+(`src/artifacts/comparisonArtifactWriter.ts`). Manifest content is parsed
+as JSON only and is never executed (no `eval`, no dynamic code loading from
+a manifest).
+
 ## Not yet addressed
 
 Certificate-failure-specific handling, permission-prompt-specific handling
 (Chromium's default deny-all applies; no permission is ever explicitly
 granted), and any non-loopback/remote browsing mode remain unimplemented and
-out of scope. `my-frontend-observer@0.3.0` is published to npm, and a
+out of scope. `my-frontend-observer@0.4.0` is published to npm, and a
 pre-release readiness CI workflow (Windows/Linux/macOS packed-candidate
 validation) already exists (see `docs/CI_CD.md`); these are no longer future
 decisions. Those facts do not expand the security scope above: remote