my-frontend-observer 0.1.0 → 0.3.0

package/docs/SECURITY.md

@@ -29,5 +29,9 @@ 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 v0.1 scope. Package publication and any hosted-CI/release-pipeline
-security gate are separate, later decisions - not addressed here.
+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
+browsing, certificate handling, and permission-prompt handling remain
+separate, unimplemented concerns.

package/docs/WORKFLOWS.md

@@ -11,29 +11,56 @@ install dependencies (npm install; npx playwright install chromium)
 → validate documentation (npm run check:docs)
 ```
 
-## Current v0.1 observation workflow
+## Current observation workflow (published as 0.3.0)
 
-The real, source-checkout `observe` workflow is:
+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, --target, --output, --timeout)
-→ request construction
-→ existing Batch 1 request validation/normalization
+CLI arguments (--url, --viewport, --output, --timeout, exactly one of:
+  one-or-more --target <id=css-selector>
+  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 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)
-→ existing Chromium capture (launch, safe navigation, readiness, screenshot,
-  page/target evidence) - exactly once
-→ existing atomic artifact persistence (manifest.json + screenshot.png) -
-  exactly once, only on a successful capture
+→ 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.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)
 ```
 
-This is exercised by `runCli()`-level tests, by a built
-`node dist/cli.js observe ...` run against the deterministic local fixture,
-and by the real `npm pack` tarball installed and run from a clean temporary
-consumer directory outside the repository - the same workflow, independent
-of the source checkout. It has not been published to a registry.
+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`, `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.1.0",
+  "version": "0.3.0",
   "description": "Local-first browser runtime evidence producer",
   "type": "module",
   "repository": {