my-frontend-observer 0.1.0 → 0.2.0

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.2.0` (roadmap v0.2, Stable
+Semantic Targets and Region Identity; observation schema `1.1.0`).
 
 ## Greenfield foundation established
 
@@ -102,12 +102,89 @@ 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.
+
 ## 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.
+- No controlled-scroll behavior, layout/spatial relationship engine,
+  before/after comparison, frontend contracts/change scope, source
+  ownership, my-dev-kit runtime/static integration, orchestrator/lab
+  product integration, viewer, or annotation - all remain v0.3+ and
+  unimplemented.
+- No v0.3–v0.10 capability is implemented.
 
 ## Next target
 
-v0.1.0 is released. The next allowed workflow is v0.2 planning.
+v0.2 is implemented, validated, and released as `0.2.0`. v0.3 (Controlled
+Scroll and Overflow Scenarios) 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 106
 passing tests). `npm run test:browser` runs the real-Chromium integration
-suite (`tests/browser/`, currently 16 passing tests) against deterministic
+suite (`tests/browser/`, currently 69 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,25 @@ 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.1.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.

package/docs/PROJECT_OVERVIEW.md

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

package/docs/QUICKSTART.md

@@ -21,7 +21,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.
+See [COMMANDS.md](COMMANDS.md) for the full flag reference, including the
+`--targets-file` structured semantic-target input.
 
 To validate the repository itself instead:
 

package/docs/RELEASE.md

@@ -1,9 +1,11 @@
 # Release
 
-`v0.1.0` is published to npm as `my-frontend-observer`, validated on
+`v0.2.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 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.
 
-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.2.0`; observation schema is `1.1.0` and does not change
+automatically with the package version.

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

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.2.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,38 @@ 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.2.0)
 
-The real, source-checkout `observe` workflow is:
+The real `observe` workflow, part of the published `my-frontend-observer@0.2.0`
+package, accepts target configuration through either of two input paths:
 
 ```text
-CLI arguments (--url, --viewport, --target, --output, --timeout)
-→ request construction
-→ existing Batch 1 request validation/normalization
+CLI arguments (--url, --viewport, --output, --timeout, and exactly one of:
+  one-or-more --target <id=css-selector>
+  or --targets-file <json-file>)
+→ (--targets-file only: read + validate the local JSON root wrapper)
+→ request construction (same RawObservationRequest either way)
+→ normalizeRequest() - producing canonical {name, locators} targets
 → 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, 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
+→ atomic artifact persistence (manifest.json + screenshot.png), schema
+  1.1.0 - exactly once, only on a successful capture
 → 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.
+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.
 
 The future dependency order after observation is:
 

package/package.json

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