my-frontend-observer 0.1.0 → 0.3.0

package/docs/COMMANDS.md

@@ -21,10 +21,18 @@ Options:
 - `--viewport <WIDTHxHEIGHT>` — e.g. `1280x720`. Malformed syntax (missing
   `x`, non-numeric, empty side) is rejected before any browser launches;
   in-range bounds are enforced by the existing request validator.
-- `--target <id=css-selector>` — an explicit observation target. Repeatable;
-  order is preserved. Parsed on the *first* `=` only, so a selector
-  containing `=` survives intact, e.g.
-  `--target action=button[data-state="active"]`.
+- `--target <id=css-selector>` — an explicit CSS-shorthand observation
+  target. Repeatable; order is preserved. Parsed on the *first* `=` only, so
+  a selector containing `=` survives intact, e.g.
+  `--target action=button[data-state="active"]`. Cannot be combined with
+  `--targets-file`.
+- `--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).
@@ -53,6 +61,170 @@ capture. CLI-syntax errors (e.g. a missing `--url`) print as `error:
 <message>` followed by `observe` usage; request/capture/persistence
 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.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
+target/locator model established in `src/request/request.ts`. It supplies
+the same `targets` collection that `--target` supplies, just in structured
+form; both converge on the same `normalizeRequest()` validation and the same
+downstream browser resolver - there is no separate semantic observation path.
+
+File format (the exact, first frozen structure - the root object supports
+only the `targets` field; any other top-level field is rejected):
+
+```json
+{
+  "targets": [
+    {
+      "name": "primary-navigation",
+      "locators": [
+        { "kind": "role", "role": "navigation", "name": "Primary" },
+        { "kind": "id", "value": "nav" }
+      ]
+    },
+    {
+      "name": "workspace",
+      "locators": [
+        { "kind": "data-attribute", "attribute": "data-region", "value": "workspace" }
+      ]
+    }
+  ]
+}
+```
+
+Each target has a stable `name` and an ordered `locators` array (1-5
+entries; order is the fallback order - the first locator that resolves
+uniquely wins, an ambiguous or unevaluable locator stops immediately without
+trying the next one). Each locator is one of the six frozen kinds:
+
+- `{ "kind": "role", "role": "<string>", "name"?: "<string>" }`
+- `{ "kind": "id", "value": "<string>" }`
+- `{ "kind": "data-attribute", "attribute": "data-*", "value": "<string>" }`
+- `{ "kind": "semantic-element", "tag": "<one of the frozen structural tags>" }`
+- `{ "kind": "css", "selector": "<string>" }`
+- `{ "kind": "text", "text": "<exact string>" }`
+
+`--targets-file` itself only validates that the file is readable, is valid
+JSON, and has an object root containing exactly a `targets` field - every
+target/locator-internal rule (bounds, per-kind required fields, supported
+values) is enforced by the same `normalizeRequest()` validator `--target`
+already goes through, so both input modes produce identical diagnostics for
+equivalent mistakes.
+
+The path may be relative (resolved from the current working directory) or
+absolute; it is operational input only - it never affects the observation's
+request identity and is never written into `manifest.json`.
+
+Example:
+
+```powershell
+my-frontend-observer observe `
+  --url http://localhost:3000/ `
+  --viewport 1280x720 `
+  --targets-file .\targets.json `
+  --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.
+
 ## Foundation commands
 
 - `npm install` — install dependencies (includes the `playwright` runtime
@@ -75,8 +247,11 @@ diagnostics print one per line as `[code] message`.
 - `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,11 +2,13 @@
 
 ## Current contracts
 
-The v0.1 observation artifact contract is implemented (`src/domain/schema.ts`)
-and proven both from the source checkout and from the packed npm tarball:
+The observation artifact contract is published as `my-frontend-observer@0.3.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):
 
-- artifact kind `my-frontend-observer/observation`, schema version `1.0.0`
-  (independent of the package version, currently `0.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
   page/target evidence embedded inline) and `screenshot.png` - there is no
@@ -26,8 +28,135 @@ and proven both from the source checkout and from the packed npm tarball:
 - observation/request identity, producer/package identity, and browser
   provenance are all present in every persisted manifest.
 
-This contract is implemented; it is not yet published as a package, and no
-public programmatic-API compatibility promise has been made.
+This contract is implemented and published; no public programmatic-API
+compatibility promise has been made.
+
+## v0.2 target contract (shipped as part of this release)
+
+v0.2 introduces a canonical target-configuration model: each configured target has a stable
+observer-level `name` plus an ordered array of bounded `locators`
+(`role`, `id`, `data-attribute`, `semantic-element`, `css`, `text`). This
+identity is distinct from both the browser locator definition that resolves
+it and any source-code identity. The legacy `{name, selector}` shape remains
+accepted and normalizes to a one-item `css` locator, so every published
+`0.1.0` CLI invocation continues to work unchanged. Locator precedence is the
+configured array order; resolution stops on the first unique match, on any
+ambiguous match (never falling through to a later locator), or on an
+unevaluable locator - never silently. All six frozen locator kinds are now
+resolved against a real Chromium page (`role` via Playwright's accessibility-
+role/name locator with exact name matching, `id`/`data-attribute` via exact
+CSS attribute-equals matching that never reinterprets the configured value as
+selector syntax, `semantic-element` via the frozen tag set, `css` via the
+existing v0.1 behavior, `text` via exact-text matching only); every kind
+converges on the same measurement path, so locator strategy never changes the
+resulting target evidence shape.
+
+Each resolved target's evidence record additionally carries three bounded
+fields: `semanticState` (a first family of `disabled`/`expanded`/
+`checked`/`selected`/`pressed`/`current` values read from the element's own
+native form-control properties and explicit `aria-*` attributes - a key is
+present only when the browser exposes that state as applicable to this
+element, so an explicit `false` is always distinguishable from "not
+applicable"; `not-applicable` when no supported state applies at all);
+`landmark` (derived only from the already-captured browser-exposed
+role - never from locator kind or HTML tag - against the standard landmark
+role set `banner`/`navigation`/`main`/`complementary`/`contentinfo`/`form`/
+`region`/`search`); and `containment` (bounded DOM containment checked only
+among the other explicitly configured targets in the same observation, in
+configured order, never a layout/relationship graph - `available` when every
+other configured target was itself resolved and checked, `partial` when one
+or more could not be, `unavailable` when the target itself never resolved).
+Stable observer target identity is proven, not just declared: the same
+target configuration produces the same `requestId` across repeated
+observations (with a fresh `observationId` each time); changing a target's
+locator strategy while keeping its stable name changes `requestId` but not
+the `targetEvidence` key; and actual runtime disappearance of a
+still-configured target changes only its resolution status, never the
+`requestId`.
+
+The full canonical semantic target model above is reachable through the
+real public CLI: `my-frontend-observer observe --targets-file <json-file>`
+supplies the structured `{ "targets": [...] }` collection (see
+`docs/COMMANDS.md` "Structured semantic targets") as an alternative to the
+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.
+
+## 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.
 
 ## Approved v0.1 design inputs
 

package/docs/CURRENT_STATE.md

@@ -1,7 +1,7 @@
 # Current State
 
-The project is published at package version `0.1.0` (roadmap v0.1, Runtime
-Observation Foundation).
+The project is published at package version `0.3.0` (roadmap v0.3, Runtime
+Scrolling, Overflow, and Visibility Behavior; observation schema `1.2.0`).
 
 ## Greenfield foundation established
 
@@ -102,12 +102,134 @@ tarball/output fully cleaned up afterward. Documentation across the
 repository was reconciled to this implemented state as part of the same
 batch.
 
+## v0.1 status
+
+`v0.1.0` was the first published release (see `CHANGELOG.md` and
+`docs/RELEASE.md`). Everything above this section describes that released
+state, still present unchanged in `v0.2.0`.
+
+## v0.2 status (Stable Semantic Targets and Region Identity) - released as 0.2.0
+
+v0.2 is implemented and released as package version `0.2.0`, observation
+schema `1.1.0`.
+
+- **Canonical target/locator model.** Each configured target has a stable
+  observer-owned `name` plus an ordered, bounded `locators` array
+  (`src/request/request.ts#TargetLocator`, `NamedTarget`). This identity is
+  distinct from both the browser locator that resolves it and any
+  source-code symbol. The legacy `{name, selector}` shape remains accepted
+  and normalizes to a one-item `css` locator, so every v0.1 CLI invocation
+  continues to work unchanged. Bounds: 20 targets max, 5 locators per
+  target max (unchanged/new respectively from v0.1's target count bound).
+- **Six frozen locator kinds, all resolved against real Chromium**: `role`
+  (Playwright's accessibility role/name locator, exact name matching),
+  `id` and `data-attribute` (exact CSS attribute-equals matching that never
+  reinterprets the configured value as selector syntax), `semantic-element`
+  (a frozen structural tag set: `header`, `nav`, `main`, `footer`,
+  `article`, `section`, `aside`, `form`, `dialog`), `css` (unchanged v0.1
+  behavior), and `text` (exact match only, no substring/fuzzy matching).
+  Locator order is the fallback order: 0 matches tries the next locator; 1
+  match selects and stops; more than 1 match is ambiguous and stops (never
+  falls through); an unevaluable locator is unavailable and stops (never
+  falls through). All six kinds converge on one measurement path
+  (`src/browser/evidenceCapture.ts#captureResolvedTargetRecord`) - locator
+  strategy never changes the resulting evidence shape.
+- **Semantic region evidence**, added to every resolved target alongside
+  the existing v0.1 role/name capture: `semanticState` (a first bounded
+  family of `disabled`/`expanded`/`checked`/`selected`/`pressed`/`current`,
+  read from the element's own native/ARIA properties so an explicit `false`
+  is always distinguishable from "not applicable"; `checked`/`pressed` also
+  support the browser's `'mixed'` value); `landmark` (derived only from the
+  already-captured browser-exposed role - never from locator kind or HTML
+  tag - against the standard landmark role set `banner`/`navigation`/
+  `main`/`complementary`/`contentinfo`/`form`/`region`/`search`); and
+  `containment` (bounded DOM containment checked only among the other
+  explicitly configured targets in the same observation, in configured
+  order - `available`/`partial`/`unavailable`, never a layout/spatial-
+  relationship graph).
+- **Proven identity stability**: the same target configuration produces the
+  same `requestId` across repeated observations (with a fresh
+  `observationId` every time); changing a target's locator strategy while
+  keeping its stable name changes `requestId` but not the `targetEvidence`
+  key; actual runtime disappearance of a still-configured target changes
+  only its resolution status, never the `requestId`.
+- **Public CLI**: `my-frontend-observer observe --targets-file <json-file>`
+  supplies a structured `{ "targets": [...] }` collection as an alternative
+  to one or more `--target id=css-selector` flags; the two are mutually
+  exclusive per invocation. `--targets-file` only validates its own root
+  wrapper (readable file, valid JSON, object root with exactly a `targets`
+  field); all target/locator-internal validation stays owned by the
+  existing `normalizeRequest()`. The file path is operational input only -
+  never part of request identity, never persisted into `manifest.json`.
+- **Observation schema `1.1.0`** (`src/domain/schema.ts#SCHEMA_VERSION`):
+  additive over the published `1.0.0` - extends `TargetEvidenceRecord` with
+  `semanticState`/`landmark`/`containment` and extends `TargetResolution`
+  with `selectedLocatorKind`/`selectedLocatorIndex`/`usedFallback`/
+  `confidence`/`attempts`. Artifact kind, directory structure, atomic
+  persistence, and evidence-state/source vocabularies are unchanged.
+- **Validation on this branch**: `npm run typecheck`, `npm run lint`,
+  `npm test`, `npm run test:browser`, `npm run build`, and
+  `npm run check:docs` all pass (106 unit tests, 69 real-Chromium tests as
+  of this reconciliation; see `docs/DEVELOPMENT.md` for how to reproduce).
+  `scripts/dev/builtCliTargetsFileSmoke.mjs` additionally proves the built
+  `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`).
+
 ## Not implemented
 
-- There is no controlled-scroll behavior, target-source correlation, or
-  capability beyond the bounded page/target evidence Batches 3-5 established.
-- No v0.2–v0.10 capability is 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+).
 
 ## Next target
 
-v0.1.0 is released. The next allowed workflow is v0.2 planning.
+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.

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 70
+`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 16 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,4 +62,42 @@ 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.
+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.
+
+`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.2.0` artifact with no packed-tarball step involved. Run it
+locally after `npm run build`:
+
+```powershell
+node scripts/dev/builtCliTargetsFileSmoke.mjs
+```
+
+`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,12 +15,18 @@ The responsibility split is stable:
 
 ## Current repository state
 
-v0.1, Runtime Observation Foundation, is released as `0.1.0`, published to
-npm and validated as a packed npm tarball in a clean consumer environment: a
-real `observe` CLI command launches Chromium, enforces loopback-only safety,
-captures bounded page/target evidence and a viewport screenshot, and
-persists one portable local artifact. v0.2–v0.10 remain future and
-unimplemented.
+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
+future and unimplemented.
 
 The revised dependency path reaches practical coding-agent use before graphical
 interaction:

package/docs/QUICKSTART.md

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

package/docs/RELEASE.md

@@ -1,9 +1,16 @@
 # Release
 
-`v0.1.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. 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: schema
-`1.0.0` does not change automatically with the package version.
+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.
+
+Prior releases: `v0.2.0` (Stable Semantic Targets and Region Identity),
+`v0.1.0` (Runtime Observation Foundation) - see `CHANGELOG.md`.

package/docs/ROADMAP.md

@@ -43,6 +43,10 @@ and the concrete dependency/version set before implementation.
 
 ## v0.2 — Stable Semantic Targets and Region Identity
 
+Current status: released as `0.2.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: let humans and consumers refer reliably to conceptual
 rendered regions across observations without brittle selector-only identity.
 Required capabilities include semantic HTML, accessibility role/name, stable
@@ -56,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,