my-frontend-observer 0.2.0 → 0.3.0

package/dist/browser/scrollCapture.js

@@ -0,0 +1,163 @@
+import { deriveOverflowEvidence, deriveViewportRelation } from '../domain/scrollEvidence.js';
+function browserField(value) {
+    return { state: 'available', source: 'browser', value };
+}
+function computedField(value) {
+    return { state: 'available', source: 'computed-browser', value };
+}
+function derivedField(value, derivedFrom) {
+    return { state: 'available', source: 'derived', value, derivedFrom };
+}
+function unavailableField(reason) {
+    return { state: 'unavailable', reason };
+}
+function notApplicableField(reason) {
+    return { state: 'not-applicable', reason };
+}
+/**
+ * `document.scrollingElement` (falling back to `documentElement`, which is
+ * what `scrollingElement` resolves to for any standards-mode document) is
+ * the browser's own answer to "which element actually scrolls the page" -
+ * that becomes `document.root`. `documentElement` is included as its own
+ * field only when it is a *different* element from the scrolling root
+ * (legacy quirks-mode pages, not exercised by this repository's fixtures);
+ * otherwise it would just duplicate `root`'s own metrics. `body` is always
+ * a distinct DOM element from `documentElement` when present, so its own
+ * metrics are genuine measurement, not fabrication, even when numerically
+ * equal to `root`.
+ */
+async function captureWindowAndDocument(page) {
+    return page.evaluate(() => {
+        const metricsOf = (el) => ({
+            scrollTop: el.scrollTop,
+            scrollLeft: el.scrollLeft,
+            scrollWidth: el.scrollWidth,
+            scrollHeight: el.scrollHeight,
+            clientWidth: el.clientWidth,
+            clientHeight: el.clientHeight,
+        });
+        const scrollingElement = document.scrollingElement ?? document.documentElement;
+        const rootStyle = getComputedStyle(scrollingElement);
+        const body = document.body;
+        return {
+            scrollX: window.scrollX,
+            scrollY: window.scrollY,
+            root: metricsOf(scrollingElement),
+            rootOverflowX: rootStyle.overflowX,
+            rootOverflowY: rootStyle.overflowY,
+            documentElement: scrollingElement !== document.documentElement ? metricsOf(document.documentElement) : undefined,
+            body: body ? metricsOf(body) : undefined,
+        };
+    });
+}
+/** Same hidden-element convention as `evidenceCapture.ts#captureResolvedTargetRecord`: `display:none`/`visibility:hidden`/zero-size all mean "not visibly rendered". */
+async function captureTargetScrollMeasurement(handle) {
+    return handle.evaluate((el) => {
+        const rect = el.getBoundingClientRect();
+        const computed = getComputedStyle(el);
+        return {
+            metrics: {
+                scrollTop: el.scrollTop,
+                scrollLeft: el.scrollLeft,
+                scrollWidth: el.scrollWidth,
+                scrollHeight: el.scrollHeight,
+                clientWidth: el.clientWidth,
+                clientHeight: el.clientHeight,
+            },
+            overflowX: computed.overflowX,
+            overflowY: computed.overflowY,
+            rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height, right: rect.right, bottom: rect.bottom },
+            visible: computed.display !== 'none' && computed.visibility !== 'hidden' && rect.width > 0 && rect.height > 0,
+        };
+    });
+}
+/**
+ * Builds one bounded `TargetScrollRuntimeState` for a single already-resolved
+ * configured target. Metrics/overflow/boundingRect are reported as real
+ * browser measurement (even when zero, for a hidden element) - consistent
+ * with how `evidenceCapture.ts` already reports geometry for hidden v0.2
+ * targets - but `viewportRelation` is `not-applicable` for a hidden target
+ * (Batch 1 Section 20/24: hidden is not the same claim as offscreen, so a
+ * hidden target must never receive ordinary above/below/intersecting
+ * geometry).
+ */
+async function captureTargetScrollRuntimeState(info, viewport) {
+    if (info.status !== 'matched' || !info.handle) {
+        const reason = info.unavailableReason ?? `target itself did not resolve (status: ${info.status})`;
+        return {
+            metrics: unavailableField(reason),
+            overflow: unavailableField(reason),
+            boundingRect: unavailableField(reason),
+            viewportRelation: unavailableField(reason),
+        };
+    }
+    const raw = await captureTargetScrollMeasurement(info.handle);
+    const overflow = deriveOverflowEvidence(raw.metrics, raw.overflowX, raw.overflowY);
+    const viewportRelation = raw.visible
+        ? derivedField(deriveViewportRelation(raw.rect, viewport), ['boundingRect', 'viewport'])
+        : notApplicableField('target is hidden or non-rendered; viewport relation is not meaningful');
+    return {
+        metrics: browserField(raw.metrics),
+        overflow: computedField(overflow),
+        boundingRect: browserField(raw.rect),
+        viewportRelation,
+    };
+}
+/**
+ * Captures one point-in-time bounded `ScrollRuntimeSnapshot` (Batch 1 frozen
+ * contract) from the live page, using already-resolved target handles -
+ * never re-resolving targets itself. Called twice by the scenario lifecycle
+ * (once before the scroll action, once after stabilization) against the
+ * exact same `resolved` set, so "which browser element is target X" is
+ * answered exactly once per observation's scenario capture.
+ */
+export async function captureScrollRuntimeSnapshot(page, resolved, viewport) {
+    const raw = await captureWindowAndDocument(page);
+    const rootOverflow = deriveOverflowEvidence(raw.root, raw.rootOverflowX, raw.rootOverflowY);
+    const targets = {};
+    for (const info of resolved) {
+        targets[info.name] = await captureTargetScrollRuntimeState(info, viewport);
+    }
+    return {
+        window: { scrollX: raw.scrollX, scrollY: raw.scrollY },
+        document: {
+            root: raw.root,
+            rootOverflow,
+            ...(raw.documentElement ? { documentElement: raw.documentElement } : {}),
+            ...(raw.body ? { body: raw.body } : {}),
+        },
+        targets,
+    };
+}
+/**
+ * Immediate, non-smooth window scroll using the Batch 1 normalized delta.
+ * `behavior: 'instant'` guarantees no smooth-scroll animation regardless of
+ * any `scroll-behavior: smooth` the observed page's own CSS declares - the
+ * position change is synchronous within this one `evaluate()` call.
+ */
+export async function performWindowScrollBy(page, deltaX, deltaY) {
+    await page.evaluate(({ deltaX, deltaY }) => {
+        window.scrollBy({ left: deltaX, top: deltaY, behavior: 'instant' });
+    }, { deltaX, deltaY });
+}
+/**
+ * Immediate, non-smooth scroll of one uniquely-resolved configured target
+ * element, using the same `behavior: 'instant'` primitive as
+ * {@link performWindowScrollBy} - one stabilization/execution contract for
+ * both action kinds, never a forked one. `element.scrollBy` is a real,
+ * browser-native immediate-scroll method on every `Element` (no dependency
+ * on the target actually being scrollable - a non-overflowing target simply
+ * produces no position change, which is a valid, honestly-reported outcome).
+ */
+export async function performTargetScrollBy(handle, deltaX, deltaY) {
+    await handle.evaluate((el, { deltaX, deltaY }) => {
+        el.scrollBy({ left: deltaX, top: deltaY, behavior: 'instant' });
+    }, { deltaX, deltaY });
+}
+/** The Batch 1 frozen stabilization contract: exactly two `requestAnimationFrame` cycles on the live page, no timers/sleeps/network-idle substitutes. */
+export async function waitTwoAnimationFrames(page) {
+    await page.evaluate(() => new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    }));
+}
+//# sourceMappingURL=scrollCapture.js.map

package/dist/browser/scrollCapture.js.map

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

package/dist/browser/types.d.ts

@@ -1,6 +1,6 @@
 import type { Diagnostic } from '../domain/diagnostics.js';
 import type { EvidenceField } from '../domain/evidence.js';
-import type { TargetEvidenceRecord } from '../domain/schema.js';
+import type { TargetEvidenceRecord, ScrollScenarioEvidence } from '../domain/schema.js';
 export interface BrowserProvenance {
     engine: string;
     version: string;
@@ -16,6 +16,8 @@ export type BrowserCaptureResult = {
     pageEvidence: Record<string, EvidenceField<unknown>>;
     targetEvidence: Record<string, TargetEvidenceRecord>;
     diagnostics: Diagnostic[];
+    /** v0.3 Batch 2: present only when the request configured a scrollScenario. */
+    scrollScenarioEvidence?: ScrollScenarioEvidence;
 } | {
     ok: false;
     diagnostics: Diagnostic[];

package/dist/cli.js

@@ -50,6 +50,19 @@ Options:
                             itself is never persisted into the artifact or
                             included in the observation's request identity.
                             Cannot be combined with --target.
+  --scroll-scenario-file <json-file>
+                            Loads one bounded runtime scroll scenario from a
+                            local JSON file: { "action": { "kind":
+                            "window-scroll-by"|"target-scroll-by", ...,
+                            "deltaX": <int>, "deltaY": <int> } }.
+                            "target-scroll-by" additionally requires a
+                            "target" naming a configured stable target.
+                            Exactly zero or one scenario per observation.
+                            Relative paths resolve from the current working
+                            directory; the file path itself is never
+                            persisted into the artifact or included in the
+                            observation's request identity. May be combined
+                            with either --target or --targets-file.
   --output <directory>      Portable, relative output location for the
                             observation artifact.
   --timeout <ms>            Overall request timeout in milliseconds.
@@ -84,6 +97,8 @@ function parseObserveArgs(argv) {
     let timeoutMs;
     let targetsFilePath;
     let targetsFileFlagCount = 0;
+    let scrollScenarioFilePath;
+    let scrollScenarioFileFlagCount = 0;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         switch (arg) {
@@ -126,6 +141,20 @@ function parseObserveArgs(argv) {
                 }
                 break;
             }
+            case '--scroll-scenario-file': {
+                const value = argv[(i += 1)];
+                scrollScenarioFileFlagCount += 1;
+                if (value === undefined) {
+                    errors.push('--scroll-scenario-file requires a file path argument');
+                }
+                else if (scrollScenarioFileFlagCount > 1) {
+                    errors.push('--scroll-scenario-file may only be specified once');
+                }
+                else {
+                    scrollScenarioFilePath = value;
+                }
+                break;
+            }
             case '--output':
                 outputLocation = argv[(i += 1)];
                 break;
@@ -158,7 +187,12 @@ function parseObserveArgs(argv) {
         ...(outputLocation === undefined ? {} : { outputLocation }),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
     };
-    return { ok: true, raw, ...(targetsFilePath === undefined ? {} : { targetsFilePath }) };
+    return {
+        ok: true,
+        raw,
+        ...(targetsFilePath === undefined ? {} : { targetsFilePath }),
+        ...(scrollScenarioFilePath === undefined ? {} : { scrollScenarioFilePath }),
+    };
 }
 const TARGETS_FILE_ALLOWED_ROOT_FIELDS = new Set(['targets']);
 /**
@@ -200,6 +234,41 @@ function loadTargetsFile(filePath) {
     }
     return { ok: true, targets: record.targets };
 }
+/**
+ * CLI/input-boundary-only responsibility, mirroring `loadTargetsFile`: read
+ * one local JSON file and validate only the root shape this file format
+ * owns (plain, non-array object) - the file supplies the value of
+ * `RawObservationRequest.scrollScenario` directly (no wrapper field), so
+ * there is no root-field allowlist to enforce here the way
+ * `loadTargetsFile` enforces `{ "targets": [...] }`. Every scenario/action
+ * rule (supported kind, required action, delta types/bounds, the both-zero
+ * rule, stable target reference, unknown fields) stays owned by
+ * `normalizeRequest()`, not duplicated here. The file path itself is never
+ * returned to the caller beyond this function, so it can never reach the
+ * persisted request/artifact.
+ */
+function loadScrollScenarioFile(filePath) {
+    let rawText;
+    try {
+        rawText = readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--scroll-scenario-file could not be read: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `--scroll-scenario-file is not valid JSON: ${message}` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, error: '--scroll-scenario-file root must be a JSON object' };
+    }
+    return { ok: true, scenario: parsed };
+}
 function formatDiagnostic(diagnostic) {
     const target = diagnostic.targetName === undefined ? '' : ` (target: ${diagnostic.targetName})`;
     return `[${diagnostic.code}] ${diagnostic.message}${target}`;
@@ -228,6 +297,15 @@ async function runObserveCommand(argv, io) {
         }
         raw = { ...raw, targets: loaded.targets };
     }
+    if (parsedArgs.scrollScenarioFilePath !== undefined) {
+        const loaded = loadScrollScenarioFile(parsedArgs.scrollScenarioFilePath);
+        if (!loaded.ok) {
+            io.stderr(`error: ${loaded.error}\n`);
+            io.stderr(OBSERVE_HELP);
+            return 1;
+        }
+        raw = { ...raw, scrollScenario: loaded.scenario };
+    }
     const normalized = normalizeRequest(raw);
     if (!normalized.ok) {
         for (const diagnostic of normalized.diagnostics)

package/dist/cli.js.map

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

package/dist/domain/identity.d.ts

@@ -1,9 +1,14 @@
 import type { NormalizedObservationRequest } from '../request/request.js';
 /**
  * Pure function of {targetUrl, viewport, targets (order preserved -
- * semantic), readiness.condition} only. timeoutMs, readiness.timeoutMs, and
- * outputLocation never affect the result - this is the frozen definition of
- * "same configuration" for this batch.
+ * semantic), readiness.condition, scrollScenario} only. timeoutMs,
+ * readiness.timeoutMs, and outputLocation never affect the result - this is
+ * the frozen definition of "same configuration" for this batch. A request
+ * with no `scrollScenario` omits the key entirely (rather than setting it to
+ * `undefined`) so the v0.2 identity for scenario-less requests is unchanged
+ * by this v0.3 extension. Only the requested action configuration
+ * participates - never runtime scroll results, movement success/failure, or
+ * scroll-owner interpretation, which are runtime evidence, not identity.
  */
 export declare function buildRequestIdentity(request: NormalizedObservationRequest): string;
 /**

package/dist/domain/identity.js

@@ -12,9 +12,14 @@ function canonicalize(value) {
 }
 /**
  * Pure function of {targetUrl, viewport, targets (order preserved -
- * semantic), readiness.condition} only. timeoutMs, readiness.timeoutMs, and
- * outputLocation never affect the result - this is the frozen definition of
- * "same configuration" for this batch.
+ * semantic), readiness.condition, scrollScenario} only. timeoutMs,
+ * readiness.timeoutMs, and outputLocation never affect the result - this is
+ * the frozen definition of "same configuration" for this batch. A request
+ * with no `scrollScenario` omits the key entirely (rather than setting it to
+ * `undefined`) so the v0.2 identity for scenario-less requests is unchanged
+ * by this v0.3 extension. Only the requested action configuration
+ * participates - never runtime scroll results, movement success/failure, or
+ * scroll-owner interpretation, which are runtime evidence, not identity.
  */
 export function buildRequestIdentity(request) {
     const semanticView = {
@@ -22,6 +27,7 @@ export function buildRequestIdentity(request) {
         viewport: { width: request.viewport.width, height: request.viewport.height },
         targets: request.targets.map((target) => ({ name: target.name.toLowerCase(), locators: target.locators })),
         readinessCondition: request.readiness.condition,
+        ...(request.scrollScenario ? { scrollScenario: request.scrollScenario } : {}),
     };
     const serialized = JSON.stringify(canonicalize(semanticView));
     return createHash('sha256').update(serialized).digest('hex');

package/dist/domain/identity.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/domain/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC,CAAU,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqC;IACxE,MAAM,YAAY,GAAG;QACnB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE;QAC5E,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1G,kBAAkB,EAAE,OAAO,CAAC,SAAS,CAAC,SAAS;KAChD,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,GAAG,eAAe,IAAI,KAAK,EAAE,CAAC;AACvC,CAAC"}
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/domain/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC,CAAU,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqC;IACxE,MAAM,YAAY,GAAG;QACnB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE;QAC5E,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1G,kBAAkB,EAAE,OAAO,CAAC,SAAS,CAAC,SAAS;QAC/C,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9E,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,GAAG,eAAe,IAAI,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/dist/domain/schema.d.ts

@@ -3,7 +3,7 @@ import type { Diagnostic } from './diagnostics.js';
 import type { CompletionState } from './completion.js';
 import type { NormalizedObservationRequest } from '../request/request.js';
 export declare const ARTIFACT_KIND: "my-frontend-observer/observation";
-export declare const SCHEMA_VERSION: "1.1.0";
+export declare const SCHEMA_VERSION: "1.2.0";
 export declare const PRODUCER_NAME: "my-frontend-observer";
 export type TargetLocatorKind = 'role' | 'id' | 'data-attribute' | 'semantic-element' | 'css' | 'text';
 export type TargetSelectionStatus = 'matched' | 'not-found' | 'ambiguous' | 'unavailable';
@@ -104,6 +104,119 @@ export interface TargetEvidenceRecord {
     landmark: EvidenceField<TargetLandmarkRole>;
     containment: EvidenceField<TargetContainment>;
 }
+/**
+ * v0.3 Batch 1 bounded runtime scroll/overflow evidence model. Frozen here
+ * as a contract; no browser capture populates it yet (Batch 2/3), so
+ * `scrollScenarioEvidence` on `ObservationArtifact` stays absent for every
+ * Batch-1-era observation, including one whose `requestConfig.scrollScenario`
+ * is present (see `src/browser/chromiumAdapter.ts`, which fails such a
+ * request honestly rather than pretending to execute it).
+ */
+export interface ScrollableMetrics {
+    scrollTop: number;
+    scrollLeft: number;
+    scrollWidth: number;
+    scrollHeight: number;
+    clientWidth: number;
+    clientHeight: number;
+}
+/** Distinguishes an `overflow-x`/`overflow-y` CSS declaration from actual browser-observed dimensional overflow - the two are not interchangeable (see docs/CONTRACTS.md). */
+export interface OverflowEvidence {
+    horizontalOverflow: boolean;
+    verticalOverflow: boolean;
+    overflowX: string;
+    overflowY: string;
+}
+export interface WindowScrollSnapshot {
+    scrollX: number;
+    scrollY: number;
+}
+/** `documentElement`/`body` are omitted (not fabricated) when the browser's own scrolling/root-element representation makes them not meaningfully distinct or not observable. */
+export interface DocumentScrollSnapshot {
+    root: ScrollableMetrics;
+    rootOverflow: OverflowEvidence;
+    documentElement?: ScrollableMetrics;
+    body?: ScrollableMetrics;
+}
+export type VerticalViewportRelation = 'above' | 'intersecting' | 'below';
+/**
+ * Derived only from a target's bounding rectangle plus viewport width/height
+ * - never from source styles or locator kind. A hidden/non-rendered target
+ * (see `TargetVisibility`/`target-hidden`) must not receive normal
+ * above/below/intersecting geometry; its `viewportRelation` field on
+ * `TargetScrollRuntimeState` is `not-applicable` instead (hidden is not the
+ * same claim as offscreen).
+ */
+export interface ViewportRelationEvidence {
+    vertical: VerticalViewportRelation;
+    intersectsViewport: boolean;
+    fullyWithinViewport: boolean;
+}
+/** Bounded per-configured-target runtime scroll/overflow/viewport evidence for one snapshot (initial or final). References targets by the existing stable target `name` - never a second region identity - and never copies the full `TargetEvidenceRecord`. */
+export interface TargetScrollRuntimeState {
+    metrics: EvidenceField<ScrollableMetrics>;
+    overflow: EvidenceField<OverflowEvidence>;
+    boundingRect: EvidenceField<TargetGeometry>;
+    viewportRelation: EvidenceField<ViewportRelationEvidence>;
+}
+/** One point-in-time bounded runtime snapshot (captured either before or after the one scroll action). */
+export interface ScrollRuntimeSnapshot {
+    window: WindowScrollSnapshot;
+    document: DocumentScrollSnapshot;
+    targets: Record<string, TargetScrollRuntimeState>;
+}
+export interface ScrollValueChange<T> {
+    before: T;
+    after: T;
+    changed: boolean;
+}
+/**
+ * `enteredViewport`/`leftViewport` are only evaluated when both the initial
+ * and final `viewportRelation` evidence are valid (never derived from a
+ * hidden-to-visible transition, which is a separate evidence concept - see
+ * docs/CONTRACTS.md).
+ */
+export interface TargetScrollTransition {
+    scrollTop: ScrollValueChange<number>;
+    scrollLeft: ScrollValueChange<number>;
+    boundingRectPosition: ScrollValueChange<{
+        x: number;
+        y: number;
+    }>;
+    viewportRelation: ScrollValueChange<VerticalViewportRelation>;
+    enteredViewport: boolean;
+    leftViewport: boolean;
+}
+/** Bounded explicit before/after change evidence for the one scroll action in this scenario - not a generic recursive diff engine. */
+export interface ScrollScenarioTransition {
+    windowScrollX: ScrollValueChange<number>;
+    windowScrollY: ScrollValueChange<number>;
+    targets: Record<string, TargetScrollTransition>;
+}
+/**
+ * Conservative derived interpretation of which scrolling container actually
+ * moved. Never forces a winner: `none` when nothing relevant changed,
+ * `indeterminate` when more than one plausible owner changed or evidence is
+ * insufficient. `target` references the existing stable target `name`.
+ */
+export type ScrollOwnerInterpretation = {
+    kind: 'document';
+} | {
+    kind: 'target';
+    target: string;
+} | {
+    kind: 'none';
+} | {
+    kind: 'indeterminate';
+};
+/** Top-level optional v0.3 evidence family. Present only when the request configured a `scrollScenario`; absent otherwise (never fabricated as empty/zeroed evidence). */
+export interface ScrollScenarioEvidence {
+    initial: ScrollRuntimeSnapshot;
+    final: ScrollRuntimeSnapshot;
+    transition: ScrollScenarioTransition;
+    /** Always `source: 'derived'` with a non-empty `derivedFrom` (enforced by `isValidEvidenceField`/`isValidObservationArtifact`) - scroll ownership is an interpretation over browser-observed facts, never itself a direct browser observation. */
+    scrollOwner: EvidenceField<ScrollOwnerInterpretation>;
+}
 export interface ObservationArtifact {
     artifactKind: typeof ARTIFACT_KIND;
     schemaVersion: typeof SCHEMA_VERSION;
@@ -124,6 +237,7 @@ export interface ObservationArtifact {
     };
     pageEvidence: Record<string, EvidenceField<unknown>>;
     targetEvidence: Record<string, TargetEvidenceRecord>;
+    scrollScenarioEvidence?: ScrollScenarioEvidence;
     screenshot: EvidenceField<{
         path: string;
     }>;
@@ -151,5 +265,5 @@ export declare function getProducerInfo(): {
     name: typeof PRODUCER_NAME;
     version: string;
 };
-/** Structural validator for the frozen schema-1.0.0 ObservationArtifact contract. Treats `value` as arbitrary/unknown input. */
+/** Structural validator for the frozen schema-1.2.0 ObservationArtifact contract. Treats `value` as arbitrary/unknown input. */
 export declare function isValidObservationArtifact(value: unknown): SchemaValidationResult;