my-frontend-observer 0.2.0 → 0.4.0

package/docs/DEVELOPMENT.md

@@ -21,9 +21,9 @@ npm run check:docs
 npm pack --dry-run
 ```
 
-`npm test` runs the fast unit suite only (`tests/unit/`, currently 106
+`npm test` runs the fast unit suite only (`tests/unit/`, currently 176
 passing tests). `npm run test:browser` runs the real-Chromium integration
-suite (`tests/browser/`, currently 69 passing tests) against deterministic
+suite (`tests/browser/`, currently 88 passing tests) against deterministic
 local fixtures under `tests/fixtures/` and requires the Chromium binary
 above to be installed first; it is kept out of `npm test` because it
 launches a real browser and is slower.
@@ -62,25 +62,65 @@ 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
 runs the built `dist/cli.js` directly (`node dist/cli.js observe
 --targets-file ...`) against an inline disposable local HTTP fixture and a
 temporary JSON target file, proving a real semantic observation persists a
-valid schema-`1.1.0` artifact with no packed-tarball step involved. Run it
+valid schema-`1.2.0` artifact with no packed-tarball step involved. Run it
 locally after `npm run build`:
 
 ```powershell
 node scripts/dev/builtCliTargetsFileSmoke.mjs
 ```
 
-Unlike `scripts/ci/runPackedObservationSmoke.mjs`, it is not wired into any
-CI workflow and is not a release gate - it is source-checkout development
-evidence only, proving the built CLI's `--targets-file` behavior without
-installing a packed tarball or requiring cross-platform infrastructure. It
-is not part of the published package.
+`scripts/dev/builtCliScrollScenarioSmoke.mjs` is the v0.3 equivalent, added
+alongside the `--scroll-scenario-file` implementation: it runs the built
+`dist/cli.js` directly against an inline disposable local HTTP fixture,
+once with a temporary `window-scroll-by` scenario file and once with a
+temporary structured `--targets-file` plus a `target-scroll-by` scenario
+file, proving both real runtime scroll actions persist a valid
+schema-`1.2.0` artifact with populated `scrollScenarioEvidence`,
+scenario-file path privacy, and target-application immutability. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliScrollScenarioSmoke.mjs
+```
+
+`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`/`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

@@ -15,15 +15,22 @@ The responsibility split is stable:
 
 ## Current repository state
 
-v0.1, Runtime Observation Foundation, and v0.2, Stable Semantic Targets and
-Region Identity, are released, published to npm (current version `0.2.0`,
-observation schema `1.1.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 either legacy CSS-shorthand
-targets or structured semantic `--targets-file` targets, and persists one
-portable local artifact - see `docs/CURRENT_STATE.md` for the
-implementation summary. v0.3–v0.10 remain future and unimplemented.
+v0.1, Runtime Observation Foundation; v0.2, Stable Semantic Targets and
+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
 interaction:
@@ -49,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

@@ -22,7 +22,13 @@ node dist/cli.js observe `
 This launches Chromium, captures a screenshot plus bounded page/target
 evidence, and writes one portable artifact under `observations/<observation-id>/`.
 See [COMMANDS.md](COMMANDS.md) for the full flag reference, including the
-`--targets-file` structured semantic-target input.
+`--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:
 

package/docs/RELEASE.md

@@ -1,11 +1,18 @@
 # Release
 
-`v0.2.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 both the legacy CSS-shorthand `--target` path and the
-structured semantic `--targets-file` path). No project license has been
-declared yet; that decision remains open for a later explicit task.
+publication (covering the legacy CSS-shorthand `--target` path, the
+structured semantic `--targets-file` path, the bounded
+`--scroll-scenario-file` `window-scroll-by`/`target-scroll-by` runtime
+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.2.0`; observation schema is `1.1.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.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

@@ -60,6 +60,11 @@ identity persistence rules from current evidence.
 
 ## v0.3 — Runtime Scrolling, Overflow, and Visibility Behavior
 
+Current status: released as `0.3.0`, published to npm and validated as a
+packed npm tarball in a clean consumer environment on Windows, Linux, and
+macOS (observation schema `1.2.0`). See `docs/CURRENT_STATE.md` for the
+implementation summary.
+
 Objective/problem: show which container actually scrolls and what becomes
 visible, clipped, or overflowing after controlled actions. Required capabilities
 are bounded action scenarios, before/after window and target scroll positions,
@@ -72,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.2.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

package/docs/WORKFLOWS.md

@@ -11,44 +11,111 @@ install dependencies (npm install; npx playwright install chromium)
 → validate documentation (npm run check:docs)
 ```
 
-## Current observation workflow (published as 0.2.0)
+## Current observation workflow (published as 0.4.0)
 
-The real `observe` workflow, part of the published `my-frontend-observer@0.2.0`
-package, accepts target configuration through either of two input paths:
+The real `observe` workflow, part of the published `my-frontend-observer@0.4.0`
+package, accepts target configuration through either of two input paths,
+plus one optional runtime scroll scenario:
 
 ```text
-CLI arguments (--url, --viewport, --output, --timeout, and exactly one of:
+CLI arguments (--url, --viewport, --output, --timeout, exactly one of:
   one-or-more --target <id=css-selector>
-  or --targets-file <json-file>)
+  or --targets-file <json-file>,
+  plus optionally --scroll-scenario-file <json-file>)
 → (--targets-file only: read + validate the local JSON root wrapper)
+→ (--scroll-scenario-file only: read + validate the local JSON root shape -
+  a non-array object; the file supplies RawObservationRequest.scrollScenario
+  directly, with no wrapper field)
 → request construction (same RawObservationRequest either way)
-→ normalizeRequest() - producing canonical {name, locators} targets
+→ normalizeRequest() - producing canonical {name, locators} targets and
+  validating the optional scrollScenario (supported action kind, delta
+  bounds/both-zero rule, stable target-name reference)
 → application observation use case (src/application/observationPersistence.ts#observe)
-→ Chromium capture (launch, safe navigation, readiness, screenshot,
-  page/target evidence), resolving all six locator kinds through the single
-  canonical resolver, plus semantic state/landmark/containment evidence,
-  from the same live page - exactly once
+→ Chromium capture: launch, safe navigation, readiness, then - only if a
+  scenario was configured - resolve configured targets once, capture an
+  initial ScrollRuntimeSnapshot, perform the one immediate scroll
+  (window.scrollBy/element.scrollBy, behavior: "instant"), wait exactly two
+  requestAnimationFrame cycles, capture a final ScrollRuntimeSnapshot and
+  derive transition/scroll-owner evidence; then screenshot and page/target
+  evidence (resolving all six locator kinds through the single canonical
+  resolver, plus semantic state/landmark/containment evidence), from the
+  same live page - exactly once, always describing the final state
 → atomic artifact persistence (manifest.json + screenshot.png), schema
-  1.1.0 - exactly once, only on a successful capture
+  1.2.0 - exactly once, only on a successful capture; scrollScenarioEvidence
+  is simply one more optional manifest field, never a separate file
 → concise CLI result (Observation/State/Artifact/Targets/Diagnostics)
 → process exit status (0 for a persisted observation, including one whose
   state honestly reports "partial"; nonzero otherwise)
 ```
 
+A request with no scroll scenario is unaffected: no extra snapshots, no
+scroll, no extra animation-frame wait, unchanged request identity.
+
 This is exercised by `runCli()`-level tests, real-Chromium end-to-end tests
-(`tests/browser/cliObserve.test.ts`), a built
-`node dist/cli.js observe ...` run against the deterministic local fixture
-(including `scripts/dev/builtCliTargetsFileSmoke.mjs` for the semantic
-`--targets-file` path), and the real `npm pack` tarball installed and run
-from a clean temporary consumer directory outside the repository, on
-Windows, Linux, and macOS - the same workflow, independent of the source
-checkout.
+(`tests/browser/cliObserve.test.ts`, `tests/browser/windowScrollScenario.test.ts`,
+`tests/browser/targetScrollScenario.test.ts`), built `node dist/cli.js
+observe ...` runs against the deterministic local fixture
+(`scripts/dev/builtCliTargetsFileSmoke.mjs` for the semantic `--targets-file`
+path, `scripts/dev/builtCliScrollScenarioSmoke.mjs` for the scroll-scenario
+path), and the real `npm pack` tarball installed and run from a clean
+temporary consumer directory outside the repository, on Windows, Linux, and
+macOS (`scripts/ci/runPackedObservationSmoke.mjs`) - the same workflow,
+independent of the source checkout.
+
+## Current comparison workflow (published as 0.4.0)
+
+**Current status: shipped as part of the published `my-frontend-observer@0.4.0`
+package.** This is a separate workflow from the observation workflow above -
+it consumes two already-persisted observation artifacts rather than
+producing one, and it never launches a browser:
+
+```text
+two prior real "observe" invocations, each producing its own persisted
+  ObservationArtifact (before, after) - unrelated to this workflow itself
+→ CLI arguments (--before <root>, --after <root>, --output <directory>,
+  optionally --config-file <json-file>)
+→ (--config-file only: read + validate the local JSON root shape - a
+  non-array object; the file supplies ComparisonConfig directly, with no
+  wrapper field)
+→ read + validate both observation artifacts (src/artifacts/artifactReader.ts,
+  the same isValidObservationArtifact structural gate the writer uses)
+→ application comparison use case
+  (src/application/comparisonService.ts#compareAndPersistFromArtifactRoots
+  → compareAndPersist)
+→ pure comparison derivation (src/domain/comparisonEngine.ts#compareObservations):
+  comparability first, then - only if comparable/comparable-with-warnings -
+  deriveLayoutRelationships for each side plus target/page differences,
+  relationship changes, and explicit non-causal dependency evidence
+→ atomic comparison-artifact persistence (manifest.json only, no copied
+  screenshots), schema 1.0.0 - exactly once, for every comparability
+  outcome including "incomparable"
+→ concise CLI result (Comparison/State/Artifact/Differences/Relationship
+  changes/Diagnostics)
+→ process exit status (0 for any successfully computed and persisted
+  comparison, including "incomparable"; nonzero only for invalid
+  syntax/unreadable or invalid source artifacts/invalid configuration/a
+  failed write)
+```
+
+Source observations are never modified by this workflow. Operational paths
+(`--before`/`--after`/`--config-file`/`--output`) never affect
+`comparisonRequestId` and are never written into the persisted manifest.
+
+This is exercised by `runCli()`-level tests
+(`tests/unit/cli.test.ts`, `tests/unit/cliCompareOrchestration.test.ts`,
+`tests/unit/cliCompareEndToEnd.test.ts`), a real-Chromium end-to-end test
+(`tests/browser/cliCompare.test.ts`), built `node dist/cli.js compare ...`
+runs against real persisted observations from the deterministic local
+fixture (`scripts/dev/builtCliCompareSmoke.mjs`), and packed-tarball
+validation of the installed `compare` command
+(`scripts/ci/runPackedObservationSmoke.mjs` - see `docs/CI_CD.md`).
 
-The future dependency order after observation is:
+## Future workflows
 
 ```text
 stable targets and bounded runtime behavior
-→ relationships, comparison, and safe-change contracts
+→ relationships and before/after comparison (released - see above)
+→ safe-change contracts
 → bounded agent context plus runtime/static ecosystem integration
 → text/config-driven coding-agent change review
 → interactive viewer
@@ -56,5 +123,6 @@ stable targets and bounded runtime behavior
 → full visual human–LLM workflow
 ```
 
-None of these later workflows is implemented. The v0.7 coding-agent workflow
-must work without the v0.8 viewer or v0.9 annotation system.
+Safe-change contracts (v0.5+) and everything after remain unimplemented. The
+v0.7 coding-agent workflow must work without the v0.8 viewer or v0.9
+annotation system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-frontend-observer",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Local-first browser runtime evidence producer",
   "type": "module",
   "repository": {