my-frontend-observer 0.2.0 → 0.3.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.
@@ -72,15 +72,32 @@ 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
+```
+
+Unlike `scripts/ci/runPackedObservationSmoke.mjs`, neither of these 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.

package/docs/PROJECT_OVERVIEW.md

@@ -15,15 +15,18 @@ 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
+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 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.
+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
+future and unimplemented.
 
 The revised dependency path reaches practical coding-agent use before graphical
 interaction:

package/docs/QUICKSTART.md

@@ -22,7 +22,8 @@ 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.
 
 To validate the repository itself instead:
 

package/docs/RELEASE.md

@@ -1,11 +1,16 @@
 # Release
 
-`v0.2.0` is published to npm as `my-frontend-observer`, validated on
+`v0.3.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, and the bounded
+`--scroll-scenario-file` `window-scroll-by`/`target-scroll-by` runtime
+scroll scenario path). 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
+version is `0.3.0`; observation schema is `1.2.0` and does not change
 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`.

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,

package/docs/SECURITY.md

@@ -29,7 +29,7 @@ tests:
 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.3.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,38 +11,56 @@ 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.3.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.3.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.
 
 The future dependency order after observation is:
 

package/package.json

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