my-frontend-observer 0.1.0

package/dist/request/request.js

@@ -0,0 +1,174 @@
+import { orderDiagnostics } from '../domain/diagnostics.js';
+import { classifyUrl } from '../safety/policy.js';
+import { normalizeOutputLocation } from './paths.js';
+const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_READINESS_CONDITION = 'load';
+const DEFAULT_READINESS_TIMEOUT_MS = 10000;
+const DEFAULT_OUTPUT_LOCATION = 'observations';
+const VIEWPORT_MIN = 200;
+const VIEWPORT_MAX = 3840;
+const TIMEOUT_MIN_MS = 1000;
+const TIMEOUT_MAX_MS = 120000;
+const READINESS_TIMEOUT_MIN_MS = 500;
+const MAX_TARGETS = 20;
+const TARGET_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_SELECTOR_LENGTH = 500;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isInRange(value, min, max) {
+    return Number.isInteger(value) && value >= min && value <= max;
+}
+/**
+ * Total, never throws. Collects every applicable diagnostic before returning
+ * (does not short-circuit on the first violation) so callers see every
+ * problem at once, in deterministic order.
+ */
+export function normalizeRequest(raw) {
+    const diagnostics = [];
+    let targetUrl;
+    if (typeof raw.targetUrl !== 'string' || raw.targetUrl.length === 0) {
+        diagnostics.push({ code: 'invalid-request', severity: 'error', message: 'targetUrl is required and must be a non-empty string' });
+    }
+    else {
+        targetUrl = raw.targetUrl;
+        const decision = classifyUrl(targetUrl);
+        if (!decision.allowed)
+            diagnostics.push(decision.diagnostic);
+    }
+    let viewport = DEFAULT_VIEWPORT;
+    if (raw.viewport !== undefined) {
+        const candidate = raw.viewport;
+        if (!isPlainObject(candidate) ||
+            typeof candidate.width !== 'number' ||
+            typeof candidate.height !== 'number' ||
+            !isInRange(candidate.width, VIEWPORT_MIN, VIEWPORT_MAX) ||
+            !isInRange(candidate.height, VIEWPORT_MIN, VIEWPORT_MAX)) {
+            diagnostics.push({
+                code: 'invalid-request',
+                severity: 'error',
+                message: `viewport width/height must be integers in [${VIEWPORT_MIN}, ${VIEWPORT_MAX}]`,
+            });
+        }
+        else {
+            viewport = { width: candidate.width, height: candidate.height };
+        }
+    }
+    const targets = [];
+    if (raw.targets !== undefined) {
+        if (!Array.isArray(raw.targets)) {
+            diagnostics.push({ code: 'invalid-request', severity: 'error', message: 'targets must be an array' });
+        }
+        else if (raw.targets.length > MAX_TARGETS) {
+            diagnostics.push({ code: 'invalid-request', severity: 'error', message: `targets must contain at most ${MAX_TARGETS} entries` });
+        }
+        else {
+            const seenNames = new Set();
+            for (const rawTarget of raw.targets) {
+                if (!isPlainObject(rawTarget) || typeof rawTarget.name !== 'string' || typeof rawTarget.selector !== 'string') {
+                    diagnostics.push({ code: 'invalid-request', severity: 'error', message: 'each target requires a string name and string selector' });
+                    continue;
+                }
+                const name = rawTarget.name;
+                const selector = rawTarget.selector;
+                if (!TARGET_NAME_RE.test(name)) {
+                    diagnostics.push({ code: 'invalid-request', severity: 'error', message: 'target name must match ^[A-Za-z0-9_-]{1,64}$', targetName: name });
+                }
+                if (selector.length === 0 || selector.length > MAX_SELECTOR_LENGTH) {
+                    diagnostics.push({
+                        code: 'invalid-request',
+                        severity: 'error',
+                        message: `target selector must be 1-${MAX_SELECTOR_LENGTH} characters`,
+                        targetName: name,
+                    });
+                }
+                const normalizedName = name.toLowerCase();
+                if (seenNames.has(normalizedName)) {
+                    diagnostics.push({ code: 'invalid-request', severity: 'error', message: 'duplicate target name', targetName: name });
+                }
+                else {
+                    seenNames.add(normalizedName);
+                }
+                targets.push({ name, selector });
+            }
+        }
+    }
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    if (raw.timeoutMs !== undefined) {
+        if (typeof raw.timeoutMs !== 'number' || !isInRange(raw.timeoutMs, TIMEOUT_MIN_MS, TIMEOUT_MAX_MS)) {
+            diagnostics.push({
+                code: 'invalid-request',
+                severity: 'error',
+                message: `timeoutMs must be an integer in [${TIMEOUT_MIN_MS}, ${TIMEOUT_MAX_MS}]`,
+            });
+        }
+        else {
+            timeoutMs = raw.timeoutMs;
+        }
+    }
+    let readinessCondition = DEFAULT_READINESS_CONDITION;
+    let readinessTimeoutMs = Math.min(DEFAULT_READINESS_TIMEOUT_MS, timeoutMs);
+    if (raw.readiness !== undefined) {
+        if (!isPlainObject(raw.readiness)) {
+            diagnostics.push({ code: 'unsupported-configuration', severity: 'error', message: 'readiness must be an object' });
+        }
+        else {
+            const readinessRaw = raw.readiness;
+            if (readinessRaw.condition !== undefined) {
+                if (readinessRaw.condition === 'load' || readinessRaw.condition === 'domcontentloaded') {
+                    readinessCondition = readinessRaw.condition;
+                }
+                else {
+                    diagnostics.push({
+                        code: 'unsupported-configuration',
+                        severity: 'error',
+                        message: 'readiness.condition must be "load" or "domcontentloaded"',
+                    });
+                }
+            }
+            if (readinessRaw.timeoutMs !== undefined) {
+                if (typeof readinessRaw.timeoutMs !== 'number' || !isInRange(readinessRaw.timeoutMs, READINESS_TIMEOUT_MIN_MS, timeoutMs)) {
+                    diagnostics.push({
+                        code: 'unsupported-configuration',
+                        severity: 'error',
+                        message: `readiness.timeoutMs must be an integer in [${READINESS_TIMEOUT_MIN_MS}, timeoutMs]`,
+                    });
+                }
+                else {
+                    readinessTimeoutMs = readinessRaw.timeoutMs;
+                }
+            }
+        }
+    }
+    let outputLocation = DEFAULT_OUTPUT_LOCATION;
+    if (raw.outputLocation !== undefined) {
+        if (typeof raw.outputLocation !== 'string') {
+            diagnostics.push({ code: 'invalid-request', severity: 'error', message: 'outputLocation must be a string' });
+        }
+        else {
+            const result = normalizeOutputLocation(raw.outputLocation);
+            if (result.ok) {
+                outputLocation = result.value;
+            }
+            else {
+                diagnostics.push(result.diagnostic);
+            }
+        }
+    }
+    if (diagnostics.length > 0 || targetUrl === undefined) {
+        return { ok: false, diagnostics: orderDiagnostics(diagnostics) };
+    }
+    return {
+        ok: true,
+        request: {
+            targetUrl,
+            viewport,
+            targets,
+            outputLocation,
+            timeoutMs,
+            readiness: { condition: readinessCondition, timeoutMs: readinessTimeoutMs },
+        },
+    };
+}
+//# sourceMappingURL=request.js.map

package/dist/request/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/request/request.ts"],"names":[],"mappings":"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"}

package/dist/safety/policy.d.ts

@@ -0,0 +1,14 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+export type SafetyDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    diagnostic: Diagnostic;
+};
+/** Pure classification: scheme + loopback rules only. Never performs DNS resolution or network I/O. */
+export declare function classifyUrl(url: string): SafetyDecision;
+export declare function classifyRedirect(fromUrl: string, toUrl: string): SafetyDecision;
+export declare function classifySubresource(url: string): SafetyDecision;
+/** Popups and downloads are never followed/saved in v0.1; both are non-fatal (warning) notices, not errors. */
+export declare function classifyPopup(): Diagnostic;
+export declare function classifyDownload(): Diagnostic;

package/dist/safety/policy.js

@@ -0,0 +1,81 @@
+const ALLOWED_SCHEMES = ['http', 'https'];
+/**
+ * v0.1 loopback allowlist: literal localhost/127.0.0.1/::1 and any 127.x.x.x
+ * form only. No DNS resolution, no arbitrary named "local dev host" support -
+ * an explicit conservative reading recorded in behavior-model.txt.
+ */
+function isLoopbackHost(hostname) {
+    const normalized = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (normalized === 'localhost' || normalized === '127.0.0.1' || normalized === '::1')
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(normalized);
+}
+/** Pure classification: scheme + loopback rules only. Never performs DNS resolution or network I/O. */
+export function classifyUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return {
+            allowed: false,
+            diagnostic: { code: 'invalid-request', severity: 'error', message: `malformed URL: ${url}` },
+        };
+    }
+    const scheme = parsed.protocol.replace(/:$/, '');
+    if (!ALLOWED_SCHEMES.includes(scheme)) {
+        return {
+            allowed: false,
+            diagnostic: { code: 'unsafe-url', severity: 'error', message: `scheme "${scheme}" is not allowed`, details: { url } },
+        };
+    }
+    if (parsed.username.length > 0 || parsed.password.length > 0) {
+        return {
+            allowed: false,
+            diagnostic: { code: 'unsafe-url', severity: 'error', message: 'credential-bearing URLs are rejected', details: { url } },
+        };
+    }
+    if (!isLoopbackHost(parsed.hostname)) {
+        return {
+            allowed: false,
+            diagnostic: { code: 'unsafe-url', severity: 'error', message: `host "${parsed.hostname}" is not a loopback host`, details: { url } },
+        };
+    }
+    return { allowed: true };
+}
+export function classifyRedirect(fromUrl, toUrl) {
+    const decision = classifyUrl(toUrl);
+    if (decision.allowed)
+        return decision;
+    return {
+        allowed: false,
+        diagnostic: {
+            code: 'prohibited-redirect',
+            severity: 'error',
+            message: 'redirect target failed safety policy',
+            details: { from: fromUrl, to: toUrl },
+        },
+    };
+}
+export function classifySubresource(url) {
+    const decision = classifyUrl(url);
+    if (decision.allowed)
+        return decision;
+    return {
+        allowed: false,
+        diagnostic: {
+            code: 'prohibited-subresource-request',
+            severity: 'error',
+            message: 'subresource target failed safety policy',
+            details: { url },
+        },
+    };
+}
+/** Popups and downloads are never followed/saved in v0.1; both are non-fatal (warning) notices, not errors. */
+export function classifyPopup() {
+    return { code: 'unsupported-configuration', severity: 'warning', message: 'popups are not followed in v0.1' };
+}
+export function classifyDownload() {
+    return { code: 'unsupported-configuration', severity: 'warning', message: 'downloads are not followed in v0.1' };
+}
+//# sourceMappingURL=policy.js.map

package/dist/safety/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/safety/policy.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Architecture
+
+## Current scaffold architecture
+
+The current repository is one private TypeScript ESM package:
+
+- `src/cli.ts` is the real, thin `observe` command entry point (argument
+  parsing/output only).
+- `src/index.ts` is the library entry point re-exporting the observer-owned
+  contracts/functions from every layer below.
+- `scripts/clean.mjs` safely removes only the project `dist/` directory.
+- `scripts/check-docs.mjs` validates the canonical documentation foundation,
+  roadmap version presence, and the no-batches rule.
+- TypeScript, ESLint, Vitest, and package configuration provide foundation
+  validation, now exercised by real product tests (`tests/unit/`,
+  `tests/browser/`).
+
+Batch 1 added the observation domain/schema and safety-policy layer
+(`src/domain/`, `src/request/`, `src/safety/`). Batch 2 added a real
+Playwright Chromium browser adapter (`src/browser/`), a minimal application
+seam invoking it (`src/application/`), and a deterministic browser
+fixture/test boundary (`tests/fixtures/`, `tests/browser/`, run via
+`npm run test:browser`). Batch 3 extended that single browser adapter with an
+internal page/target measurement module (`src/browser/evidenceCapture.ts`)
+that reads page and explicit-CSS-target evidence from the same live,
+already-ready page used for the screenshot - no second browser/page is ever
+opened, and Playwright objects still never leave `src/browser/`. Batch 4
+added the artifact ownership boundary itself: `src/artifacts/artifactWriter.ts`
+is the one canonical place that writes an observation to disk (temp
+directory, then one atomic rename into `<outputLocation>/<observationId>/`),
+and `src/application/observationPersistence.ts` assembles the frozen
+`ObservationArtifact` from a browser-capture result before handing it to the
+writer. The artifact layer has no Playwright dependency and is testable
+without launching Chromium. Batch 5 completed the boundary chain: `src/cli.ts`
+parses `observe` arguments (CLI-syntax errors only - e.g. malformed
+`WIDTHxHEIGHT`), constructs a raw request, and hands it to the existing
+Batch 1 `normalizeRequest`; on success it calls one new application-level use
+case, `observe()` in `src/application/observationPersistence.ts`, which runs
+the existing `runBrowserCapture` exactly once and, only on success, the
+existing artifact writer exactly once, then returns a small observer-owned
+`ApplicationObservationResult` (observation id, completion state, artifact
+path, target/diagnostic counts) for the CLI to print. The CLI never imports
+Playwright or the filesystem-write path directly. Batch 6 closed the
+remaining real-Chromium coverage gap (a genuine navigation failure, distinct
+from a readiness timeout or a pre-launch safety rejection) and validated the
+packed npm tarball end to end in a clean consumer environment, independent
+of the source checkout. There is still no controlled-scroll/comparison
+behavior.
+
+## Planned v0.1 architecture constraints
+
+v0.1 planning must preserve these approved boundaries without treating module
+names from the historical run as mandatory:
+
+```text
+thin command-line boundary
+        ↓
+reusable observation engine/application layer
+        ↓
+browser automation boundary
+        ↓
+observer-owned runtime evidence
+
+observer-owned domain/schema
+        ↓
+artifact ownership boundary
+
+deterministic fixture/test boundary
+        ↓
+browser-level validation
+```
+
+Use one browser engine implementation, keep browser logic out of presentation,
+avoid speculative plugin/multi-browser abstractions, and keep observed
+applications external. Before v0.6, versions must not add runtime coupling to
+sibling ecosystem projects. v0.6 may add only explicit bounded context,
+correlation/export, orchestrator-consumption, and lab-compatibility contracts
+while preserving independent ownership.
+
+The text/config-driven coding-agent workflow must be operational before the
+viewer and annotation layers are added. Those interfaces consume the same
+canonical observation, relationship, comparison, contract, change-scope,
+correlation, and context boundaries rather than creating parallel engines.
+The concrete implementation plan and module layout must be designed only after
+the relevant version planning workflow inspects the current repositories.

package/docs/CI_CD.md

@@ -0,0 +1,28 @@
+# CI/CD
+
+A GitHub Actions pre-release readiness workflow exists at
+`.github/workflows/pre-release-readiness.yml` (triggered manually via
+`workflow_dispatch` or by pushing a `validation/**` branch). It has two
+phases:
+
+1. **candidate** (Linux, Node 24): `npm ci`, install Chromium, typecheck,
+   lint, `npm test`, `npm run test:browser`, `npm run test:security`,
+   build, `npm run check:docs`, then `npm pack` to produce exactly one
+   candidate tarball and its SHA-256, uploaded as build artifacts.
+2. **matrix-smoke** (`windows-latest`, `ubuntu-latest`, `macos-latest`, all
+   Node 24): each job downloads the *same* candidate tarball produced by the
+   candidate job, independently recomputes and verifies its SHA-256 against
+   the candidate job's hash (failing immediately on any mismatch - no job
+   ever builds its own tarball), installs Chromium via the installed
+   package's own Playwright dependency, and runs
+   `scripts/ci/runPackedObservationSmoke.mjs` against the installed
+   tarball: a real Chromium observation against a disposable local HTTP
+   target, with artifact/schema/screenshot/target-immutability assertions.
+
+This proves the same packaged candidate installs and performs a real
+observation on Windows, Linux, and macOS, not just in the source checkout.
+
+There is no automated npm publication and no automated GitHub Release
+creation - this workflow is readiness validation only, run from a
+`validation/**` branch, never from a release branch or tag. Package
+publication remains a separate, later, explicit release decision.

package/docs/COMMANDS.md

@@ -0,0 +1,82 @@
+# Commands
+
+## Product command surface
+
+`node dist/cli.js observe` (or `my-frontend-observer observe` once installed
+as a bin) captures one bounded, loopback-only browser observation and
+persists it as a portable artifact.
+
+```text
+my-frontend-observer observe --url <loopback-url> [options]
+```
+
+Required:
+
+- `--url <url>` — loopback target URL (`http`/`https`; `localhost`,
+  `127.x.x.x`, or `::1` only - enforced by the existing request/safety
+  contracts, not by CLI-local logic).
+
+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"]`.
+- `--output <directory>` — portable, relative output location for the
+  observation artifact (same contract as the request's `outputLocation`; no
+  drive letter, no leading `/`, no `..` segments).
+- `--timeout <ms>` — overall request timeout in milliseconds.
+- `--help` — show `observe` usage.
+
+Also available: `--help` / `-h` (top-level usage) and `--version` (prints the
+actual package version).
+
+On success the command prints exactly:
+
+```text
+Observation: <observation-id>
+State: <complete|partial|warning|fatal|invalid-request>
+Artifact: <artifact-root-path>
+Targets: <configured-target-count>
+Diagnostics: <diagnostic-count>
+```
+
+and exits `0` for a validly persisted observation - including one whose
+`State` truthfully reports `partial` (e.g. a missing or ambiguous target)
+- or exits nonzero for invalid CLI syntax, a request the existing validator
+rejects, an unsafe/failed navigation with no persistable artifact, or a
+failed artifact write. No progress output is printed during a normal
+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`.
+
+## Foundation commands
+
+- `npm install` — install dependencies (includes the `playwright` runtime
+  dependency since Batch 2).
+- `npx playwright install chromium` — install the Chromium binary once per
+  machine (see `docs/DEVELOPMENT.md`).
+- `npm run typecheck` — run TypeScript no-emit checking.
+- `npm run lint` — lint the repository and scripts.
+- `npm test` — run the fast unit suite (`tests/unit/`).
+- `npm run test:browser` — run the real-Chromium integration suite
+  (`tests/browser/`), including a real `observe` end-to-end test against the
+  deterministic local fixture.
+- `npm run test:security` — run only the safety-relevant subset of the suite
+  (`tests/unit/policy.test.ts` plus the real-Chromium enforcement cases in
+  `tests/browser/chromiumAdapter.test.ts`: unsafe initial target, prohibited
+  redirect, prohibited subresource request, and browser cleanup around
+  safety/navigation failure) — a discoverable entry point for security
+  review tooling; it is a subset of, not a replacement for, `npm test` and
+  `npm run test:browser`.
+- `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.

package/docs/CONTRACTS.md

@@ -0,0 +1,54 @@
+# Contracts
+
+## 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:
+
+- artifact kind `my-frontend-observer/observation`, schema version `1.0.0`
+  (independent of the package version, currently `0.1.0`);
+- 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
+  separate `evidence.json`;
+- `manifest.json` is written last, after `screenshot.png`, via one atomic
+  directory rename, so a consumer never observes a partially-written
+  artifact; a filesystem failure anywhere in that sequence reports the
+  `artifact-write-failure` diagnostic and leaves no completed artifact;
+- internal artifact references (e.g. `screenshot.png`) are relative to the
+  artifact root, never an absolute machine path; the observation's logical
+  identity is its `observationId`, not its filesystem location;
+- evidence states `available`, `unavailable`, `not-applicable`, `partial`;
+  evidence sources `browser`, `computed-browser`, `derived`;
+- a stable diagnostic vocabulary (`src/domain/diagnostics.ts`) and completion
+  states `complete`, `partial`, `warning`, `invalid-request`, `fatal`
+  (`src/domain/completion.ts`);
+- 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.
+
+## Approved v0.1 design inputs
+
+The historical greenfield scaffold plan recorded these v0.1 design decisions:
+
+- artifact kind `my-frontend-observer/observation`;
+- schema version `1.0.0`, independent of package version;
+- one portable directory containing `manifest.json`, `evidence.json`, and
+  `screenshot.png`;
+- evidence states `available`, `unavailable`, `not-applicable`, and `partial`;
+- evidence sources `browser`, `computed-browser`, and `derived`;
+- bounded explicitly requested targets, provenance, diagnostics, completion
+  state, limits, and relative artifact references.
+
+These were planning inputs only at the time they were recorded. As shown in
+"Current contracts" above, the implemented contract matches them except for
+the file layout: there is no separate `evidence.json` - page/target evidence
+is embedded directly inside `manifest.json`.
+
+Comparison and relationship contracts belong to v0.4, and canonical
+change-scope contracts belong to v0.5. Bounded agent-context plus ecosystem
+integration contracts move to v0.6, followed by the text/config-driven
+coding-agent review contract in v0.7. Viewer and annotation contracts follow in
+v0.8 and v0.9 and converge with the existing workflow in v0.10.

package/docs/CURRENT_STATE.md

@@ -0,0 +1,113 @@
+# Current State
+
+The project is published at package version `0.1.0` (roadmap v0.1, Runtime
+Observation Foundation).
+
+## Greenfield foundation established
+
+The retained repository contains:
+
+- Node.js 24+ and TypeScript ESM package configuration;
+- TypeScript build and typecheck configuration;
+- ESLint configuration;
+- a Vitest runner configured to report honestly when no tests exist;
+- a safe `dist/` clean script;
+- documentation validation;
+- package allowlisting;
+- minimal `src/cli.ts` and `src/index.ts` placeholders required by the selected
+  TypeScript CLI starter profile;
+- complete repository-local Project Description, Project Milestones, ROADMAP,
+  and standardized documentation.
+
+The package bin (`src/cli.ts`) now implements the real `observe` command
+described below; it is no longer the not-implemented placeholder.
+
+## v0.1 progress (Batch 1–6; implemented and released as 0.1.0)
+
+- Batch 1 froze and implemented the observation request contract, evidence
+  states/sources, schema 1.0.0, observation/request identity, bounded
+  readiness semantics, diagnostic/completion semantics, browser/network
+  safety policy, and portable path normalization, with 40 passing unit tests.
+- Batch 2 added a Playwright Chromium browser boundary (`src/browser/`) and a
+  minimal application seam (`src/application/`) that launches a real
+  Chromium browser, enforces the Batch 1 loopback/redirect/subresource
+  safety policy at runtime, applies the requested viewport, waits for the
+  approved bounded readiness condition, captures a real viewport PNG
+  screenshot, returns observer-owned browser provenance, and reliably closes
+  the browser on every exit path. Deterministic local HTTP fixtures live
+  under `tests/fixtures/`; the real-Chromium integration tests live under
+  `tests/browser/` and run via `npm run test:browser` (kept separate from
+  `npm test`, which continues to run only the fast unit suite).
+- Batch 3 extended the same single browser observation (no second Chromium
+  lifecycle) to also capture the v0.1 minimum page evidence (requested/final
+  URL, title, viewport, device pixel ratio, document scroll/client
+  dimensions plus a derived overall document width/height, window scroll
+  position) and explicit-target evidence (tag, geometry, computed
+  display/position/overflow, scroll/client metrics, initial visibility, and
+  role/name where the browser reliably exposes them) for every configured
+  CSS target, honoring missing/ambiguous-target semantics honestly. This
+  additively extended `src/domain/schema.ts`'s `TargetEvidenceRecord` (new
+  `tag`/`layout`/`visibility`/`semantics` categories, and concrete shapes for
+  `geometry`/`style`) and `BrowserCaptureResult`; schema version stays
+  `1.0.0`.
+- Batch 4 added a portable, atomic observation-artifact writer
+  (`src/artifacts/artifactWriter.ts`) and a minimal application persistence
+  seam (`src/application/observationPersistence.ts`) that assembles the
+  frozen `ObservationArtifact` shape from a Batch 2/3 browser capture (using
+  the existing Batch 1 identity/completion functions verbatim, no new logic
+  invented) and writes it to `<outputLocation>/<observationId>/manifest.json`
+  plus `screenshot.png`. Writing happens in a sibling temporary directory
+  first (screenshot before manifest), finalized only via one atomic
+  directory rename, so a consumer can never observe a partially-written
+  artifact under its real name; a filesystem failure anywhere in that
+  sequence reports the existing `artifact-write-failure` diagnostic and
+  leaves no completed artifact behind. Internal artifact references
+  (`screenshot.png`) are relative/portable; the observation's logical
+  identity is the existing Batch 1 `observationId`, not its filesystem
+  location. The writer has no Playwright dependency and does not modify the
+  observed target. Schema stays `1.0.0`.
+- Batch 5 wired the existing owners into the real user-facing workflow:
+  `src/cli.ts` implements a real `observe` command (thin argument
+  parsing/output only - no Chromium, safety, evidence, or filesystem logic
+  of its own), and `src/application/observationPersistence.ts` gained one
+  `observe()` use case that runs the existing browser capture exactly once
+  and, only on success, persists it exactly once through the existing
+  artifact writer. CLI syntax errors (malformed `WIDTHxHEIGHT`, malformed
+  `id=selector`) are rejected before any browser launches; all domain bounds
+  and safety decisions still come from the existing Batch 1 request
+  validator and safety policy, not CLI-local logic. A successfully
+  persisted observation - including one whose completion state honestly
+  reports `partial` - exits `0`; invalid syntax/request, an unpersistable
+  browser failure, or a failed artifact write exits nonzero. Package version
+  is `0.1.0`; schema stays `1.0.0`.
+
+So: `my-frontend-observer observe --url ... --viewport ... --target ...
+--output ...` is a real, working, source-checkout command that launches
+Chromium, produces bounded runtime evidence, and writes a portable local
+artifact - proven both via `runCli()`-level tests and a built
+`node dist/cli.js observe ...` smoke run against the deterministic fixture.
+
+Batch 6 closed the remaining v0.1 coverage gap (a genuine real-Chromium
+navigation failure - connection reset mid-navigation - distinct from a
+readiness timeout or a pre-launch safety rejection) and proved the packaged
+form of the implementation works independent of the source checkout: the
+real `npm pack` tarball, installed fresh in a clean temporary consumer
+directory outside the repository, exposes its `my-frontend-observer` bin,
+reports the correct version/help text, installs its own Chromium binary via
+the consumer-local Playwright toolchain, and performs a real observation
+against a disposable local HTTP target - producing a `manifest.json` +
+`screenshot.png` artifact identical in shape to the source-checkout result,
+without modifying the observed target, and with the temporary consumer/
+tarball/output fully cleaned up afterward. Documentation across the
+repository was reconciled to this implemented state as part of the same
+batch.
+
+## 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.
+
+## Next target
+
+v0.1.0 is released. The next allowed workflow is v0.2 planning.