@e2edev/web 0.11.0-canary-20260921180210

package/dist/observation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Semantic tree capture for one observation: the in-page walk, nested-document
+ * stitching, and element-handle bookkeeping the surface keeps per generation.
+ */
+import type { ElementHandle, Frame } from 'playwright';
+import { type NodeRef, type SemanticNode } from 'e2e/engine';
+import { type RawNodeData } from './read-node.ts';
+/**
+ * The id of every observation's root: the main document's element under one
+ * id the engine mints, stable across observations and navigations, so the
+ * harness can address the viewport (`perform(root, swipe)`) from an earlier
+ * observation. Outside the `n<number>` space stamped ids and located ids share.
+ */
+export declare const ROOT_NODE_ID = "root";
+/** A page or frame: anything one document's reader can be evaluated on. */
+export type DocumentHost = Pick<Frame, 'evaluateHandle'>;
+/** What one capture needs from the surface that owns the generation. */
+export interface CaptureDeps {
+    readonly testIdAttribute: string;
+    /** The app's site; a child frame off it stays a boundary node. Undefined admits no child frame. */
+    readonly site: string | undefined;
+    /** Reserves a disjoint range before the reader can stamp any element, including on timeout. */
+    reserveIds(count: number): number;
+    /** Publishes one element handle under its id in the generation being built. */
+    commit(id: string, element: ElementHandle<Element>): void;
+}
+export interface CaptureOptions {
+    /** Enclosing frame selectors, outermost first; empty for the main document. */
+    readonly framePath: readonly string[];
+    /** Remaining node budget shared across every document of the observation. */
+    readonly budget: number;
+    /**
+     * Absolute time (epoch ms) by which the whole observation must be done.
+     * Every document's budget is derived from what remains of it, so the
+     * documents of one observation can never sum past the operation's budget.
+     */
+    readonly deadline: number;
+    readonly signal: AbortSignal;
+}
+/** One document's tree with what the capture knows about its completeness. */
+export interface CapturedDocument {
+    readonly tree: SemanticNode;
+    /** Nodes captured across this document and every child document stitched in. */
+    readonly nodeCount: number;
+    /**
+     * True when nodes on screen are missing from `tree`: the node budget cut
+     * the walk short in this document or a child, or an on-site child frame's
+     * document was not read (no budget or time left, past the depth limit, or
+     * its capture failed). Off-site frames are left out by design and never
+     * count.
+     */
+    readonly truncated: boolean;
+}
+/**
+ * Captures one document's semantic tree, then descends into each observed
+ * iframe boundary node via its content frame and stitches the child
+ * document under it. Frame capture is best-effort: a detached or unloaded
+ * frame leaves its boundary node childless rather than failing the
+ * observation. The node budget is shared across all documents.
+ */
+export declare function captureDocument(deps: CaptureDeps, host: DocumentHost, options: CaptureOptions): Promise<CapturedDocument>;
+export declare function toSemanticNode(ref: NodeRef, raw: RawNodeData, children?: readonly SemanticNode[], framePath?: readonly string[]): SemanticNode;
+//# sourceMappingURL=observation.d.ts.map

package/dist/observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAY,MAAM,YAAY,CAAC;AACjE,OAAO,EAKL,KAAK,OAAO,EACZ,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,gBAAgB,CAAC;AAGxB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAcnC,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;AAEzD,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,mGAAmG;IACnG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,+FAA+F;IAC/F,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAKD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAoB3B;AAkMD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,WAAW,EAChB,QAAQ,GAAE,SAAS,YAAY,EAAO,EACtC,SAAS,GAAE,SAAS,MAAM,EAAO,GAChC,YAAY,CAyBd"}

package/dist/observation.js

@@ -0,0 +1,262 @@
+/**
+ * Semantic tree capture for one observation: the in-page walk, nested-document
+ * stitching, and element-handle bookkeeping the surface keeps per generation.
+ */
+import { EngineError, sameSite, OBSERVED_NAME_LIMIT, OBSERVED_TEXT_LIMIT, } from 'e2e/engine';
+import { readDocumentSemanticsFunction, SECURE_FIELD_SELECTOR, } from './read-node.js';
+import { CaptureScope } from './capture-scope.js';
+/**
+ * The id of every observation's root: the main document's element under one
+ * id the engine mints, stable across observations and navigations, so the
+ * harness can address the viewport (`perform(root, swipe)`) from an earlier
+ * observation. Outside the `n<number>` space stamped ids and located ids share.
+ */
+export const ROOT_NODE_ID = 'root';
+/** Nested iframe capture depth; deeper frames stay boundary nodes. */
+const MAX_FRAME_DEPTH = 4;
+/** Budget for capturing the main document, still capped by the observation deadline. */
+const DOCUMENT_CAPTURE_TIMEOUT_MS = 15_000;
+/**
+ * Budget for capturing one child document. A stalled frame (ads, trackers)
+ * must cost an observation a moment, not the context default timeout.
+ */
+const FRAME_CAPTURE_TIMEOUT_MS = 3_000;
+/**
+ * Captures one document's semantic tree, then descends into each observed
+ * iframe boundary node via its content frame and stitches the child
+ * document under it. Frame capture is best-effort: a detached or unloaded
+ * frame leaves its boundary node childless rather than failing the
+ * observation. The node budget is shared across all documents.
+ */
+export async function captureDocument(deps, host, options) {
+    const { framePath, budget, signal } = options;
+    const cap = framePath.length === 0 ? DOCUMENT_CAPTURE_TIMEOUT_MS : FRAME_CAPTURE_TIMEOUT_MS;
+    const deadline = Math.min(options.deadline, Date.now() + cap);
+    const scope = new CaptureScope(deadline, signal);
+    // A child document's handles are published only once it captured whole; a
+    // frame that fails midway leaves no reachable ids behind.
+    const staged = [];
+    const stage = (id, element) => {
+        if (scope.own(element))
+            staged.push([id, element]);
+    };
+    return scope.run(async () => {
+        const captured = await captureInto(deps, scope, stage, host, framePath, budget, signal);
+        scope.check();
+        for (const [id, element] of staged) {
+            deps.commit(id, element);
+            scope.release(element);
+        }
+        return captured;
+    });
+}
+/** Reads one document and stages its child documents under the same capture owner. */
+async function captureInto(deps, scope, stage, host, framePath, budget, signal) {
+    const captured = await scope.read(() => host.evaluateHandle(readDocumentSemanticsFunction, {
+        testIdAttribute: deps.testIdAttribute,
+        secureFieldSelector: SECURE_FIELD_SELECTOR,
+        mode: {
+            kind: 'tree',
+            maxNodes: budget,
+            idSeed: deps.reserveIds(budget),
+            nameLimit: OBSERVED_NAME_LIMIT,
+            textLimit: OBSERVED_TEXT_LIMIT,
+        },
+    }), (handle) => scope.own(handle));
+    // Property handles would keep earlier captures alive after their parent is disposed.
+    const { nodes, ids, truncated: walkTruncated } = await scope.read(() => captured.evaluate((observation) => ({
+        nodes: observation.nodes,
+        ids: observation.ids,
+        truncated: observation.truncated,
+    })));
+    if (!Array.isArray(ids) || ids.length !== nodes.length) {
+        throw new EngineError('ENGINE_FAILURE', 'observation ids do not align with its nodes', {
+            retryable: false,
+        });
+    }
+    // The main document's element is the observation root, under the minted
+    // id rather than the one stamped on it: a new document stamps a new
+    // number, the root's id must not change with it.
+    if (framePath.length === 0 && ids.length > 0)
+        ids[0] = ROOT_NODE_ID;
+    const elementsHandle = await scope.read(() => captured.getProperty('elements'), (handle) => scope.own(handle));
+    const elements = await collectElementHandles(scope, elementsHandle, nodes.length);
+    elements.forEach((element, index) => stage(ids[index], element));
+    let nodeCount = nodes.length;
+    let truncated = walkTruncated === true;
+    const frameChildren = new Map();
+    for (let index = 0; index < nodes.length; index += 1) {
+        const selector = nodes[index].frameSelector;
+        if (selector === undefined)
+            continue;
+        // A frame with no document (detached, never loaded) shows nothing, so
+        // nothing is missing from the tree.
+        const frame = await scope.read(() => elements[index].contentFrame().catch(() => null));
+        if (frame === null)
+            continue;
+        // Only frames on the app's site enter observations. Third-party
+        // frames (ads, trackers, embeds) are not the agent's to read or act
+        // on - and a stalled ad frame must not tax the capture. They stay
+        // boundary nodes by design, so leaving them out is not truncation.
+        if (!isOnSiteFrame(frame.url(), deps.site))
+            continue;
+        // From here the frame's document is content the model should see: any
+        // reason it is not read (depth, budget, deadline, a failed or timed-out
+        // capture) leaves the tree incomplete, and the snapshot must say so.
+        if (framePath.length >= MAX_FRAME_DEPTH) {
+            truncated = true;
+            continue;
+        }
+        const remaining = budget - nodeCount;
+        if (remaining <= 0 || Date.now() >= scope.deadline) {
+            truncated = true;
+            continue;
+        }
+        const child = await scope.read(() => captureDocument({ ...deps, commit: stage }, frame, {
+            framePath: [...framePath, selector],
+            budget: remaining,
+            deadline: scope.deadline,
+            signal,
+        }).catch(() => undefined));
+        if (child === undefined) {
+            truncated = true;
+            continue;
+        }
+        frameChildren.set(index, child.tree);
+        nodeCount += child.nodeCount;
+        truncated ||= child.truncated;
+    }
+    return { tree: assembleTree(nodes, ids, framePath, frameChildren), nodeCount, truncated };
+}
+/**
+ * True when a frame document is on the app's site.
+ *
+ * `about:blank` and `srcdoc` documents inherit their parent's origin, so they
+ * are the app's own content (consent managers, editors) and always allowed; the
+ * parent frame was already admitted to be captured at all.
+ *
+ * A `data:` document is *not* admitted, even though its bytes are written by the
+ * page that embeds it. It has an opaque origin rather than an inherited one, and
+ * navigation denies the scheme by name alongside `file:` and `javascript:`.
+ */
+function isOnSiteFrame(url, site) {
+    if (url === '' || url === 'about:blank' || url === 'about:srcdoc')
+        return true;
+    if (site === undefined)
+        return false;
+    const protocol = URL.canParse(url) ? new URL(url).protocol : undefined;
+    return protocol !== 'data:' && sameSite(url, site);
+}
+/**
+ * Reads one element handle per observed node from the in-page element array.
+ * `asElement` types handles as `ElementHandle<Node>`, but the observation walk
+ * records `Element` nodes only, so the narrowing is safe by construction.
+ */
+async function collectElementHandles(scope, elementsHandle, count) {
+    const properties = await scope.read(() => elementsHandle.getProperties(), (handles) => {
+        for (const handle of handles.values())
+            scope.own(handle);
+    });
+    const elements = [];
+    for (let index = 0; index < count; index += 1) {
+        const property = properties.get(String(index));
+        const element = (property?.asElement() ?? null);
+        if (element === null) {
+            // The in-page array outlived its document (a navigation committed while
+            // the handles were being read back). The capture is repeatable.
+            throw new EngineError('NODE_STALE', `observation node ${index} lost its element`, {
+                retryable: true,
+            });
+        }
+        elements.push(element);
+    }
+    return elements;
+}
+/**
+ * Rebuilds the observation tree from the depth-first node list. Descendants
+ * always follow their parent, so children are complete before a parent is
+ * built. Captured child documents attach under their iframe boundary nodes.
+ */
+function assembleTree(nodes, ids, framePath, frameChildren) {
+    if (nodes.length === 0 || ids.length === 0) {
+        // An empty document is what a navigation in flight looks like; a real page
+        // always has nodes, so the capture is worth repeating.
+        throw new EngineError('NODE_STALE', 'observation produced no nodes', { retryable: true });
+    }
+    const childLists = nodes.map(() => []);
+    const built = [];
+    for (let index = nodes.length - 1; index >= 0; index -= 1) {
+        const raw = nodes[index];
+        const embedded = frameChildren.get(index);
+        // A child document measured its nodes against its own viewport. Shifted by
+        // the boundary element's box and clipped to it, every box in the tree is
+        // in the top-level viewport's CSS pixels, the space the screenshot and a
+        // point tap share, and a child that overflows its frame cannot claim a
+        // point over the page around it. The shift is the frame's border box; a
+        // bordered iframe is off by its border width, which is within a tap
+        // target. A frame under a CSS transform is not unwound: its boxes are
+        // where the untransformed frame would put them.
+        if (embedded !== undefined)
+            childLists[index].unshift(placeInFrame(embedded, raw.rect));
+        const node = toSemanticNode({ id: ids[index], revision: '' }, raw, childLists[index], framePath);
+        built[index] = node;
+        if (raw.parent >= 0)
+            childLists[raw.parent].unshift(node);
+    }
+    return built[0];
+}
+/** The tree with every box translated into the frame's space and clipped to its box; a box left empty by the clip is dropped. */
+function placeInFrame(node, frame) {
+    const { rect, ...rest } = node;
+    const placed = rect === undefined ? undefined : clipRect(offsetRect(rect, frame), frame);
+    return {
+        ...rest,
+        ...(placed === undefined ? {} : { rect: placed }),
+        ...(node.children === undefined ? {} : { children: node.children.map((child) => placeInFrame(child, frame)) }),
+    };
+}
+function offsetRect(rect, by) {
+    return { x: rect.x + by.x, y: rect.y + by.y, width: rect.width, height: rect.height };
+}
+function clipRect(rect, bounds) {
+    const x = Math.max(rect.x, bounds.x);
+    const y = Math.max(rect.y, bounds.y);
+    const width = Math.min(rect.x + rect.width, bounds.x + bounds.width) - x;
+    const height = Math.min(rect.y + rect.height, bounds.y + bounds.height) - y;
+    return width > 0 && height > 0 ? { x, y, width, height } : undefined;
+}
+export function toSemanticNode(ref, raw, children = [], framePath = []) {
+    const states = {};
+    if (raw.states.checked !== null)
+        states['checked'] = raw.states.checked;
+    if (raw.states.disabled)
+        states['disabled'] = true;
+    if (raw.states.selected !== null)
+        states['selected'] = raw.states.selected;
+    if (raw.states.expanded !== null)
+        states['expanded'] = raw.states.expanded;
+    if (raw.states.pressed !== null)
+        states['pressed'] = raw.states.pressed;
+    if (raw.states.focused)
+        states['focused'] = true;
+    if (raw.states.hidden)
+        states['hidden'] = true;
+    if (raw.states.secure)
+        states['secure'] = true;
+    return {
+        ref,
+        ...(raw.role !== null ? { role: raw.role } : {}),
+        ...(raw.name !== null ? { name: raw.name } : {}),
+        ...(raw.text !== null ? { text: raw.text } : {}),
+        ...(raw.value !== null ? { value: raw.value } : {}),
+        ...(raw.testId !== null ? { testId: raw.testId } : {}),
+        inputPurpose: raw.inputPurpose,
+        states,
+        ...(raw.level !== null ? { level: raw.level } : {}),
+        attributes: raw.attributes,
+        rect: raw.rect,
+        ...(framePath.length > 0 ? { framePath } : {}),
+        ...(children.length > 0 ? { children } : {}),
+    };
+}
+//# sourceMappingURL=observation.js.map

package/dist/observation.js.map

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

package/dist/observe.d.ts

@@ -0,0 +1,51 @@
+/** Masked pixel capture for an observation. */
+import type { Locator, Page } from 'playwright';
+import type { ObservationPixels, OperationContext, ViewportSize } from 'e2e/engine';
+/**
+ * Two mask locators per frame Playwright can reach, covering every secure
+ * field: one through light DOM and open shadow roots, one through the closed
+ * roots the reader also walks. Sweeping every frame rather than only the
+ * frames an observation walked makes the masked set a superset of the observed
+ * secure set - the direction that is safe. Shared by the observation pixels
+ * and the artifact screenshot so both are redacted at the source by the same
+ * rule.
+ */
+export declare function secureFieldMasks(page: Page): Locator[];
+/** Screenshot options that apply the secure-field masks; empty when there is no frame to mask. */
+export declare function maskOptions(masks: readonly Locator[]): Partial<{
+    mask: Locator[];
+    maskColor: string;
+}>;
+export interface PixelCapture {
+    readonly pixels: ObservationPixels;
+    readonly maskedRegionCount: number;
+    /** Every secure-field probe completed, independently of semantic capture. */
+    readonly maskingProven: boolean;
+}
+/**
+ * Captures masked viewport pixels.
+ *
+ * Secure fields are covered before the image leaves the engine and the covered
+ * regions are counted, so the runner can prove the image is at least as redacted
+ * as the tree (the runner's clearance check requires the masked set to be a
+ * superset of the observed secure set, which `secureFieldMasks` guarantees).
+ *
+ * `scale: 'css'` keeps the image in the CSS pixel space every observed node rect
+ * already uses, which is what lets the runner hit-test a point against the same
+ * tree.
+ */
+export declare function capturePixels(page: Page, operation: OperationContext, viewport: ViewportSize): Promise<PixelCapture>;
+/**
+ * Reads pixel dimensions out of PNG bytes.
+ *
+ * The dimensions reported with a screenshot must be the dimensions of the bytes
+ * the model actually receives: every coordinate it returns is relative to them,
+ * so a viewport value that disagrees with the capture displaces every point
+ * silently. PNG puts IHDR first, so width and height are at fixed offsets and no
+ * decoder is needed.
+ */
+export declare function readPngSize(data: Uint8Array): {
+    width: number;
+    height: number;
+} | null;
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAE/C,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAepF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,EAAE,CAOtD;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAEtG;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,YAAY,CAAC,CAkCvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAStF"}

package/dist/observe.js

@@ -0,0 +1,104 @@
+/** Masked pixel capture for an observation. */
+import { CaptureScope } from './capture-scope.js';
+import { CLOSED_SHADOW_SELECTOR_ENGINE, SECURE_FIELD_SELECTOR } from './read-node.js';
+/**
+ * Budget for one masked screenshot, still capped by the operation timeout. A
+ * heavy page that cannot produce a frame promptly must cost the observation a
+ * moment, not the whole step: the caller degrades to tree-only input rather
+ * than failing.
+ */
+const PIXEL_CAPTURE_TIMEOUT_MS = 10_000;
+/** Opaque fill covering every masked region. */
+const MASK_COLOR = '#000000';
+/**
+ * Two mask locators per frame Playwright can reach, covering every secure
+ * field: one through light DOM and open shadow roots, one through the closed
+ * roots the reader also walks. Sweeping every frame rather than only the
+ * frames an observation walked makes the masked set a superset of the observed
+ * secure set - the direction that is safe. Shared by the observation pixels
+ * and the artifact screenshot so both are redacted at the source by the same
+ * rule.
+ */
+export function secureFieldMasks(page) {
+    return page
+        .frames()
+        .flatMap((frame) => [
+        frame.locator(SECURE_FIELD_SELECTOR),
+        frame.locator(`${CLOSED_SHADOW_SELECTOR_ENGINE}=${SECURE_FIELD_SELECTOR}`),
+    ]);
+}
+/** Screenshot options that apply the secure-field masks; empty when there is no frame to mask. */
+export function maskOptions(masks) {
+    return masks.length === 0 ? {} : { mask: [...masks], maskColor: MASK_COLOR };
+}
+/**
+ * Captures masked viewport pixels.
+ *
+ * Secure fields are covered before the image leaves the engine and the covered
+ * regions are counted, so the runner can prove the image is at least as redacted
+ * as the tree (the runner's clearance check requires the masked set to be a
+ * superset of the observed secure set, which `secureFieldMasks` guarantees).
+ *
+ * `scale: 'css'` keeps the image in the CSS pixel space every observed node rect
+ * already uses, which is what lets the runner hit-test a point against the same
+ * tree.
+ */
+export async function capturePixels(page, operation, viewport) {
+    const deadline = Date.now() + operation.timeoutMs;
+    const scope = new CaptureScope(deadline, operation.signal);
+    return scope.run(async () => {
+        const masks = secureFieldMasks(page);
+        // A frame that detaches mid-sweep contributes nothing to the count, which can
+        // only push the observation toward withholding the image.
+        const counts = await scope.read(() => Promise.allSettled(masks.map((mask) => mask.count())));
+        const image = await scope.read(() => page.screenshot({
+            type: 'png',
+            scale: 'css',
+            animations: 'disabled',
+            caret: 'hide',
+            timeout: Math.max(1, Math.min(deadline - Date.now(), PIXEL_CAPTURE_TIMEOUT_MS)),
+            ...maskOptions(masks),
+        }));
+        const data = new Uint8Array(image);
+        // The bytes are the authority on their own size. `scale: 'css'` is asked for
+        // precisely so one image pixel is one CSS pixel, but the ratio is measured
+        // rather than assumed: if a capture ever comes back at device scale, reporting
+        // the viewport instead would displace every coordinate the model reads off it.
+        const size = readPngSize(data) ?? { width: viewport.width, height: viewport.height };
+        return {
+            pixels: {
+                data,
+                mediaType: 'image/png',
+                width: size.width,
+                height: size.height,
+                scale: viewport.width > 0 ? size.width / viewport.width : 1,
+            },
+            maskedRegionCount: counts.reduce((total, count) => total + (count.status === 'fulfilled' ? count.value : 0), 0),
+            maskingProven: masks.length > 0 && counts.every((count) => count.status === 'fulfilled'),
+        };
+    });
+}
+/**
+ * Reads pixel dimensions out of PNG bytes.
+ *
+ * The dimensions reported with a screenshot must be the dimensions of the bytes
+ * the model actually receives: every coordinate it returns is relative to them,
+ * so a viewport value that disagrees with the capture displaces every point
+ * silently. PNG puts IHDR first, so width and height are at fixed offsets and no
+ * decoder is needed.
+ */
+export function readPngSize(data) {
+    if (data.byteLength < 24)
+        return null;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    if (view.getUint32(0) !== 0x89504e47 || view.getUint32(4) !== 0x0d0a1a0a)
+        return null;
+    if (view.getUint32(12) !== 0x49484452)
+        return null;
+    const width = view.getUint32(16);
+    const height = view.getUint32(20);
+    if (width === 0 || height === 0)
+        return null;
+    return { width, height };
+}
+//# sourceMappingURL=observe.js.map

package/dist/observe.js.map

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

package/dist/operation-budget.d.ts

@@ -0,0 +1,11 @@
+/** One deadline for connection recovery and the operation it precedes. */
+import { EngineError } from 'e2e/engine';
+export interface ConnectionBudget {
+    readonly timeoutMs: number;
+    readonly signal: AbortSignal;
+}
+/** Preserves the reason for an engine-owned deadline without relabeling caller cancellation. */
+export declare function connectionAbort(signal: AbortSignal, label: string): EngineError;
+/** Bounds the entire transition, aborts abandoned work, and never grants a fresh dispatch budget. */
+export declare function withConnectionBudget<T>(budget: ConnectionBudget, label: string, work: (remaining: () => ConnectionBudget) => Promise<T>): Promise<T>;
+//# sourceMappingURL=operation-budget.d.ts.map

package/dist/operation-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-budget.d.ts","sourceRoot":"","sources":["../src/operation-budget.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAa,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,gGAAgG;AAChG,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAI/E;AAED,qGAAqG;AACrG,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GACtD,OAAO,CAAC,CAAC,CAAC,CAwBZ"}

package/dist/operation-budget.js

@@ -0,0 +1,40 @@
+/** One deadline for connection recovery and the operation it precedes. */
+import { EngineError, raceAbort } from 'e2e/engine';
+/** Preserves the reason for an engine-owned deadline without relabeling caller cancellation. */
+export function connectionAbort(signal, label) {
+    return signal.reason instanceof EngineError && signal.reason.code === 'OPERATION_TIMEOUT'
+        ? signal.reason
+        : new EngineError('CANCELLED', `${label} cancelled`, { retryable: false });
+}
+/** Bounds the entire transition, aborts abandoned work, and never grants a fresh dispatch budget. */
+export async function withConnectionBudget(budget, label, work) {
+    const controller = new AbortController();
+    const signal = AbortSignal.any([budget.signal, controller.signal]);
+    const endsAt = Date.now() + budget.timeoutMs;
+    const timeout = () => new EngineError('OPERATION_TIMEOUT', `${label} timed out`, { retryable: false });
+    const timer = setTimeout(() => controller.abort(timeout()), Math.max(0, budget.timeoutMs));
+    const remaining = () => {
+        if (signal.aborted)
+            throw connectionAbort(signal, label);
+        const timeoutMs = endsAt - Date.now();
+        if (timeoutMs <= 0) {
+            controller.abort(timeout());
+            throw connectionAbort(signal, label);
+        }
+        return { signal, timeoutMs };
+    };
+    try {
+        return await raceAbort(() => work(remaining), signal, label);
+    }
+    catch (cause) {
+        if (budget.signal.aborted)
+            throw connectionAbort(budget.signal, label);
+        if (signal.aborted)
+            throw connectionAbort(signal, label);
+        throw cause;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=operation-budget.js.map

package/dist/operation-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-budget.js","sourceRoot":"","sources":["../src/operation-budget.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAOpD,gGAAgG;AAChG,MAAM,UAAU,eAAe,CAAC,MAAmB,EAAE,KAAa;IAChE,OAAO,MAAM,CAAC,MAAM,YAAY,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,mBAAmB;QACvF,CAAC,CAAC,MAAM,CAAC,MAAM;QACf,CAAC,CAAC,IAAI,WAAW,CAAC,WAAW,EAAE,GAAG,KAAK,YAAY,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,qGAAqG;AACrG,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAwB,EACxB,KAAa,EACb,IAAuD;IAEvD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC;IAC7C,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,mBAAmB,EAAE,GAAG,KAAK,YAAY,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IACvG,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3F,MAAM,SAAS,GAAG,GAAqB,EAAE;QACvC,IAAI,MAAM,CAAC,OAAO;YAAE,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACzD,MAAM,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACtC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5B,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC,CAAC;IACF,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACvE,IAAI,MAAM,CAAC,OAAO;YAAE,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACzD,MAAM,KAAK,CAAC;IACd,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/protected-app.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Protected-preview access, scoped to the app's site: the configured headers
+ * ride only requests bound for the site, and basic-auth credentials answer
+ * a challenge wherever one is issued. The surface calls these on every
+ * context it creates; nothing here holds state.
+ */
+import type { BrowserContext } from 'playwright';
+import type { WebBasicAuth } from './surface.ts';
+/** The credentials Playwright answers an HTTP authentication challenge with. */
+export interface PlaywrightHttpCredential {
+    readonly username: string;
+    readonly password: string;
+}
+/** Header names lowercased, as Playwright reports a request's own headers. */
+export declare function lowercaseNames(headers: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/**
+ * Adds the configured headers to every request bound for the app's site,
+ * via a context route that falls back to the network. A request for any
+ * other site is not routed at all; without a site there is no policy and
+ * nothing is routed. Nothing awaits a route handler, so a fallback that
+ * fails (the page closed under the request) is dropped rather than left to
+ * surface as an unhandled rejection.
+ */
+export declare function installSiteHeaders(context: BrowserContext, site: string | undefined, headers: Readonly<Record<string, string>> | undefined): Promise<void>;
+/**
+ * The basic-auth credentials a context answers a challenge with, as
+ * Playwright's own `httpCredentials` does: on a 401 from any origin. A site
+ * cannot be enumerated into the exact origins Playwright scopes by, and a
+ * challenge is answered only where one is issued.
+ */
+export declare function httpCredentials(basicAuth: WebBasicAuth | undefined): PlaywrightHttpCredential | undefined;
+//# sourceMappingURL=protected-app.d.ts.map

package/dist/protected-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected-app.d.ts","sourceRoot":"","sources":["../src/protected-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,gFAAgF;AAChF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAE1G;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GACpD,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,GAAG,wBAAwB,GAAG,SAAS,CAIzG"}