my-frontend-observer 0.1.0 → 0.3.0

package/dist/domain/scrollEvidence.d.ts

@@ -0,0 +1,51 @@
+import type { EvidenceField } from './evidence.js';
+import type { Viewport } from '../request/request.js';
+import type { ScrollableMetrics, OverflowEvidence, ViewportRelationEvidence, TargetGeometry, ScrollRuntimeSnapshot, TargetScrollRuntimeState, TargetScrollTransition, ScrollScenarioTransition, ScrollOwnerInterpretation } from './schema.js';
+/**
+ * Derived only from a bounding rectangle (viewport-relative, as produced by
+ * `getBoundingClientRect()`) plus viewport width/height - never from source
+ * styles or locator kind (Batch 1 frozen contract). `above`/`below` require
+ * the rectangle to be *entirely* outside the viewport on that axis; any
+ * vertical overlap with `[0, viewport.height)` is `intersecting`.
+ */
+export declare function deriveViewportRelation(rect: TargetGeometry, viewport: Viewport): ViewportRelationEvidence;
+/**
+ * Distinguishes a computed `overflow-x`/`overflow-y` CSS declaration from
+ * actual dimensional overflow. `overflow-x: auto`/`overflow-y: scroll` alone
+ * never implies actual overflow - only `scrollWidth > clientWidth` /
+ * `scrollHeight > clientHeight` do.
+ */
+export declare function deriveOverflowEvidence(metrics: ScrollableMetrics, overflowX: string, overflowY: string): OverflowEvidence;
+/**
+ * Bounded before/after change evidence for one configured target across the
+ * one scroll action - not a generic recursive diff. Returns `undefined`
+ * (rather than fabricating zeroed/default values) when either snapshot's
+ * metrics/boundingRect/viewportRelation evidence for this target is not
+ * itself usable (e.g. the target never resolved), consistent with
+ * `enteredViewport`/`leftViewport` only being evaluated when both
+ * viewport-relation states are valid.
+ */
+export declare function deriveTargetScrollTransition(initial: TargetScrollRuntimeState, final: TargetScrollRuntimeState): TargetScrollTransition | undefined;
+/** Derives the bounded scenario transition evidence purely from the two already-captured runtime snapshots - no re-measurement, no generic JSON diffing. A target absent from either snapshot's `targets` map, or whose per-target transition cannot be derived (see `deriveTargetScrollTransition`), is simply omitted from `targets` here. */
+export declare function deriveScrollScenarioTransition(initial: ScrollRuntimeSnapshot, final: ScrollRuntimeSnapshot): ScrollScenarioTransition;
+/**
+ * Conservative scroll-owner derivation, shared by both `window-scroll-by`
+ * and `target-scroll-by` scenarios: relies solely on observed scroll
+ * *position* changes (`scrollTop`/`scrollLeft`/`window.scrollX`/
+ * `window.scrollY`), never on a target's bounding-rectangle movement (which
+ * moves for every configured target whenever the document scrolls,
+ * regardless of who "owns" scrolling - using it here would falsely
+ * attribute document scrolling to every visible target) and never on
+ * computed overflow, `position: fixed`/`sticky`, target name, locator kind,
+ * or DOM hierarchy.
+ *
+ * Rules (frozen Batch 1 vocabulary):
+ * - no window movement, no target movement -> `none`;
+ * - window movement, no competing target movement -> `document`;
+ * - no window movement, exactly one target's own scroll position moved
+ *   (on either or both axes - two axes of the *same* target is still one
+ *   owner) -> `target:<name>`;
+ * - anything else (window plus a target, or more than one target) ->
+ *   `indeterminate` - multiple plausible owners, never forced to pick one.
+ */
+export declare function deriveScrollOwner(transition: ScrollScenarioTransition): EvidenceField<ScrollOwnerInterpretation>;

package/dist/domain/scrollEvidence.js

@@ -0,0 +1,134 @@
+/**
+ * Derived only from a bounding rectangle (viewport-relative, as produced by
+ * `getBoundingClientRect()`) plus viewport width/height - never from source
+ * styles or locator kind (Batch 1 frozen contract). `above`/`below` require
+ * the rectangle to be *entirely* outside the viewport on that axis; any
+ * vertical overlap with `[0, viewport.height)` is `intersecting`.
+ */
+export function deriveViewportRelation(rect, viewport) {
+    const vertical = rect.bottom <= 0 ? 'above' : rect.y >= viewport.height ? 'below' : 'intersecting';
+    const intersectsViewport = rect.right > 0 && rect.x < viewport.width && rect.bottom > 0 && rect.y < viewport.height;
+    const fullyWithinViewport = rect.x >= 0 && rect.y >= 0 && rect.right <= viewport.width && rect.bottom <= viewport.height;
+    return { vertical, intersectsViewport, fullyWithinViewport };
+}
+/**
+ * Distinguishes a computed `overflow-x`/`overflow-y` CSS declaration from
+ * actual dimensional overflow. `overflow-x: auto`/`overflow-y: scroll` alone
+ * never implies actual overflow - only `scrollWidth > clientWidth` /
+ * `scrollHeight > clientHeight` do.
+ */
+export function deriveOverflowEvidence(metrics, overflowX, overflowY) {
+    return {
+        horizontalOverflow: metrics.scrollWidth > metrics.clientWidth,
+        verticalOverflow: metrics.scrollHeight > metrics.clientHeight,
+        overflowX,
+        overflowY,
+    };
+}
+function numberChange(before, after) {
+    return { before, after, changed: before !== after };
+}
+function extractAvailable(field) {
+    return field.state === 'available' || field.state === 'partial' ? field.value : undefined;
+}
+/**
+ * Bounded before/after change evidence for one configured target across the
+ * one scroll action - not a generic recursive diff. Returns `undefined`
+ * (rather than fabricating zeroed/default values) when either snapshot's
+ * metrics/boundingRect/viewportRelation evidence for this target is not
+ * itself usable (e.g. the target never resolved), consistent with
+ * `enteredViewport`/`leftViewport` only being evaluated when both
+ * viewport-relation states are valid.
+ */
+export function deriveTargetScrollTransition(initial, final) {
+    const initialMetrics = extractAvailable(initial.metrics);
+    const finalMetrics = extractAvailable(final.metrics);
+    const initialRect = extractAvailable(initial.boundingRect);
+    const finalRect = extractAvailable(final.boundingRect);
+    const initialRelation = extractAvailable(initial.viewportRelation);
+    const finalRelation = extractAvailable(final.viewportRelation);
+    if (!initialMetrics || !finalMetrics || !initialRect || !finalRect || !initialRelation || !finalRelation) {
+        return undefined;
+    }
+    const enteredViewport = !initialRelation.intersectsViewport && finalRelation.intersectsViewport;
+    const leftViewport = initialRelation.intersectsViewport && !finalRelation.intersectsViewport;
+    return {
+        scrollTop: numberChange(initialMetrics.scrollTop, finalMetrics.scrollTop),
+        scrollLeft: numberChange(initialMetrics.scrollLeft, finalMetrics.scrollLeft),
+        boundingRectPosition: {
+            before: { x: initialRect.x, y: initialRect.y },
+            after: { x: finalRect.x, y: finalRect.y },
+            changed: initialRect.x !== finalRect.x || initialRect.y !== finalRect.y,
+        },
+        viewportRelation: { before: initialRelation.vertical, after: finalRelation.vertical, changed: initialRelation.vertical !== finalRelation.vertical },
+        enteredViewport,
+        leftViewport,
+    };
+}
+/** Derives the bounded scenario transition evidence purely from the two already-captured runtime snapshots - no re-measurement, no generic JSON diffing. A target absent from either snapshot's `targets` map, or whose per-target transition cannot be derived (see `deriveTargetScrollTransition`), is simply omitted from `targets` here. */
+export function deriveScrollScenarioTransition(initial, final) {
+    const targets = {};
+    for (const [name, initialState] of Object.entries(initial.targets)) {
+        const finalState = final.targets[name];
+        if (!finalState)
+            continue;
+        const transition = deriveTargetScrollTransition(initialState, finalState);
+        if (transition)
+            targets[name] = transition;
+    }
+    return {
+        windowScrollX: numberChange(initial.window.scrollX, final.window.scrollX),
+        windowScrollY: numberChange(initial.window.scrollY, final.window.scrollY),
+        targets,
+    };
+}
+/**
+ * Conservative scroll-owner derivation, shared by both `window-scroll-by`
+ * and `target-scroll-by` scenarios: relies solely on observed scroll
+ * *position* changes (`scrollTop`/`scrollLeft`/`window.scrollX`/
+ * `window.scrollY`), never on a target's bounding-rectangle movement (which
+ * moves for every configured target whenever the document scrolls,
+ * regardless of who "owns" scrolling - using it here would falsely
+ * attribute document scrolling to every visible target) and never on
+ * computed overflow, `position: fixed`/`sticky`, target name, locator kind,
+ * or DOM hierarchy.
+ *
+ * Rules (frozen Batch 1 vocabulary):
+ * - no window movement, no target movement -> `none`;
+ * - window movement, no competing target movement -> `document`;
+ * - no window movement, exactly one target's own scroll position moved
+ *   (on either or both axes - two axes of the *same* target is still one
+ *   owner) -> `target:<name>`;
+ * - anything else (window plus a target, or more than one target) ->
+ *   `indeterminate` - multiple plausible owners, never forced to pick one.
+ */
+export function deriveScrollOwner(transition) {
+    const windowMoved = transition.windowScrollX.changed || transition.windowScrollY.changed;
+    const changedTargetNames = Object.entries(transition.targets)
+        .filter(([, t]) => t.scrollTop.changed || t.scrollLeft.changed)
+        .map(([name]) => name);
+    let value;
+    let derivedFrom;
+    if (!windowMoved && changedTargetNames.length === 0) {
+        value = { kind: 'none' };
+        derivedFrom = ['window.scrollX', 'window.scrollY', ...Object.keys(transition.targets).flatMap((name) => [`${name}.scrollTop`, `${name}.scrollLeft`])];
+    }
+    else if (windowMoved && changedTargetNames.length === 0) {
+        value = { kind: 'document' };
+        derivedFrom = ['window.scrollX', 'window.scrollY'];
+    }
+    else if (!windowMoved && changedTargetNames.length === 1) {
+        const target = changedTargetNames[0];
+        value = { kind: 'target', target };
+        derivedFrom = [`${target}.scrollTop`, `${target}.scrollLeft`];
+    }
+    else {
+        value = { kind: 'indeterminate' };
+        derivedFrom = [
+            ...(windowMoved ? ['window.scrollX', 'window.scrollY'] : []),
+            ...changedTargetNames.flatMap((name) => [`${name}.scrollTop`, `${name}.scrollLeft`]),
+        ];
+    }
+    return { state: 'available', source: 'derived', value, derivedFrom };
+}
+//# sourceMappingURL=scrollEvidence.js.map

package/dist/domain/scrollEvidence.js.map

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

package/dist/index.d.ts

@@ -4,11 +4,11 @@ export type { DiagnosticCode, DiagnosticSeverity, Diagnostic } from './domain/di
 export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
 export type { CompletionState, RequestPhase } from './domain/completion.js';
 export { deriveCompletion } from './domain/completion.js';
-export type { ObservationArtifact, ArtifactReference, TargetEvidenceRecord, TargetGeometry, TargetComputedStyle, TargetLayoutMetrics, TargetVisibility, TargetSemantics, SchemaValidationResult, } from './domain/schema.js';
-export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, getProducerInfo, isValidObservationArtifact } from './domain/schema.js';
+export type { ObservationArtifact, ArtifactReference, TargetEvidenceRecord, TargetGeometry, TargetComputedStyle, TargetLayoutMetrics, TargetVisibility, TargetSemantics, TargetLocatorKind, TargetSelectionStatus, TargetSelectionConfidence, TargetLocatorAttemptStatus, TargetLocatorAttempt, TargetResolution, TargetSemanticState, TargetLandmarkRole, TargetContainment, SchemaValidationResult, ScrollableMetrics, OverflowEvidence, WindowScrollSnapshot, DocumentScrollSnapshot, VerticalViewportRelation, ViewportRelationEvidence, TargetScrollRuntimeState, ScrollRuntimeSnapshot, ScrollValueChange, TargetScrollTransition, ScrollScenarioTransition, ScrollOwnerInterpretation, ScrollScenarioEvidence, } from './domain/schema.js';
+export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, TARGET_LANDMARK_ROLES, getProducerInfo, isValidObservationArtifact, } from './domain/schema.js';
 export { buildRequestIdentity, buildObservationIdentity } from './domain/identity.js';
-export type { NamedTarget, Viewport, ReadinessCondition, ReadinessConfig, NormalizedObservationRequest, RawObservationRequest, NormalizeRequestResult, } from './request/request.js';
-export { normalizeRequest } from './request/request.js';
+export type { NamedTarget, RawNamedTarget, TargetLocator, Viewport, ReadinessCondition, ReadinessConfig, NormalizedObservationRequest, RawObservationRequest, NormalizeRequestResult, ScrollAction, ScrollScenario, } from './request/request.js';
+export { normalizeRequest, SCROLL_DELTA_MAX_ABS } from './request/request.js';
 export type { NormalizeOutputLocationResult } from './request/paths.js';
 export { normalizeOutputLocation } from './request/paths.js';
 export type { SafetyDecision } from './safety/policy.js';

package/dist/index.js

@@ -1,9 +1,9 @@
 export { isValidEvidenceField } from './domain/evidence.js';
 export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
 export { deriveCompletion } from './domain/completion.js';
-export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, getProducerInfo, isValidObservationArtifact } from './domain/schema.js';
+export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, TARGET_LANDMARK_ROLES, getProducerInfo, isValidObservationArtifact, } from './domain/schema.js';
 export { buildRequestIdentity, buildObservationIdentity } from './domain/identity.js';
-export { normalizeRequest } from './request/request.js';
+export { normalizeRequest, SCROLL_DELTA_MAX_ABS } from './request/request.js';
 export { normalizeOutputLocation } from './request/paths.js';
 export { classifyUrl, classifyRedirect, classifySubresource, classifyPopup, classifyDownload } from './safety/policy.js';
 export { runBrowserCapture } from './application/browserCaptureService.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAa1D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAE/H,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAWtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGzH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEvF,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAmC1D,OAAO,EACL,aAAa,EACb,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAetF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGzH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEvF,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC"}

package/dist/request/request.d.ts

@@ -1,7 +1,34 @@
 import type { Diagnostic } from '../domain/diagnostics.js';
+export type TargetLocator = {
+    kind: 'role';
+    role: string;
+    name?: string;
+} | {
+    kind: 'id';
+    value: string;
+} | {
+    kind: 'data-attribute';
+    attribute: string;
+    value: string;
+} | {
+    kind: 'semantic-element';
+    tag: string;
+} | {
+    kind: 'css';
+    selector: string;
+} | {
+    kind: 'text';
+    text: string;
+};
 export interface NamedTarget {
     name: string;
-    selector: string;
+    locators: TargetLocator[];
+}
+/** Raw, not-yet-validated target shape as it may appear in a RawObservationRequest. Exactly one of `selector` (legacy) or `locators` (canonical) may be present, never both. */
+export interface RawNamedTarget {
+    name?: unknown;
+    selector?: unknown;
+    locators?: unknown;
 }
 export interface Viewport {
     width: number;
@@ -12,6 +39,25 @@ export interface ReadinessConfig {
     condition: ReadinessCondition;
     timeoutMs: number;
 }
+/**
+ * v0.3 Batch 1 canonical scroll-action shape. Exactly the two bounded action
+ * kinds below are supported; `target` on `target-scroll-by` refers to the
+ * existing stable observer-owned target `name` (see `NamedTarget`), never a
+ * CSS selector, Playwright locator, or DOM id evaluated directly.
+ */
+export type ScrollAction = {
+    kind: 'window-scroll-by';
+    deltaX: number;
+    deltaY: number;
+} | {
+    kind: 'target-scroll-by';
+    target: string;
+    deltaX: number;
+    deltaY: number;
+};
+export interface ScrollScenario {
+    action: ScrollAction;
+}
 export interface NormalizedObservationRequest {
     targetUrl: string;
     viewport: Viewport;
@@ -19,6 +65,7 @@ export interface NormalizedObservationRequest {
     outputLocation: string;
     timeoutMs: number;
     readiness: ReadinessConfig;
+    scrollScenario?: ScrollScenario;
 }
 export interface RawObservationRequest {
     targetUrl?: unknown;
@@ -27,6 +74,7 @@ export interface RawObservationRequest {
     outputLocation?: unknown;
     timeoutMs?: unknown;
     readiness?: unknown;
+    scrollScenario?: unknown;
 }
 export type NormalizeRequestResult = {
     ok: true;
@@ -35,6 +83,14 @@ export type NormalizeRequestResult = {
     ok: false;
     diagnostics: Diagnostic[];
 };
+/**
+ * Conservative bound for a single controlled-observation scroll action. No
+ * existing repository precedent for a scroll-delta magnitude; chosen large
+ * enough to reach realistic overflow content (documents/containers well
+ * beyond one viewport) while staying far short of a pathological/runaway
+ * request - see docs/CONTRACTS.md and tests/unit/request.test.ts.
+ */
+export declare const SCROLL_DELTA_MAX_ABS = 20000;
 /**
  * Total, never throws. Collects every applicable diagnostic before returning
  * (does not short-circuit on the first violation) so callers see every