@dailephd/my-frontend-observer 0.8.1

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

@@ -0,0 +1,24 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { EvidenceField } from '../domain/evidence.js';
+import type { TargetEvidenceRecord, ScrollScenarioEvidence } from '../domain/schema.js';
+export interface BrowserProvenance {
+    engine: string;
+    version: string;
+}
+/**
+ * Observer-owned result of the browser boundary. Contains no Playwright
+ * object anywhere in its shape - only plain, serializable data.
+ */
+export type BrowserCaptureResult = {
+    ok: true;
+    provenance: BrowserProvenance;
+    screenshot: Uint8Array;
+    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/browser/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/browser/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/browser/types.ts"],"names":[],"mappings":""}

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export interface CliIO {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+export declare function formatCheckHumanResult(result: import('./projectWorkflow/checkResult.js').CheckWorkflowResult): string;
+/** Testable CLI entry point: pure function of argv (+ injectable IO), no direct process.exit. */
+export declare function runCli(argv: readonly string[], io?: CliIO): Promise<number>;