@e2e-dev/web 0.15.5-nightly-20261104030231 → 0.15.5

package/dist/evaluation.d.ts

@@ -1,18 +1,25 @@
-type EvaluationResult = {
-    ok: true;
-    value: unknown;
-} | {
-    ok: false;
-    message: string;
-};
-/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page. */
-export declare const KEEP_NAMES_HELPER = "const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });";
+/** Separates exceptions thrown by trusted page code from failures of the evaluation transport. */
+import type { JsonValue } from 'e2e';
+/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page; it takes `defineProperty` before that code runs. */
+export declare const KEEP_NAMES_HELPER = "const __name = ((define) => (target, value) => define(target, 'name', { value, configurable: true }))(({}).constructor.defineProperty);";
 /** A function expression for page code, including ordinary and async method shorthand. Never runs it here. */
 export declare function pageFunctionSource(fn: (...args: never[]) => unknown): string;
+/**
+ * Builds, in the page, the encoder of an evaluation result into JSON text.
+ * Called before the caller's code runs, it takes the intrinsics it needs from
+ * literals, so code that deletes or replaces `Array`, `Object`, or `JSON`
+ * cannot reach it. Only JSON passes: `null`, booleans, finite numbers,
+ * strings, arrays, and plain objects. Anything else throws `{ invalid }` with
+ * the reason `validateJsonValue` gives. Embedded into the page as source, so
+ * it captures nothing from this module.
+ */
+export declare function pageValueEncoder(): (root: unknown) => string | undefined;
 /**
  * Compiles the page-side error boundary without evaluating the caller's source in this process.
  * The source is one expression: a function it evaluates to is called with the argument, any
- * other value is the result.
+ * other value is the result. The boundary resolves to JSON text, a primitive the caller takes
+ * back without Playwright serializing it in the page, so a page that deleted or replaced a
+ * global the serializer needs still returns its result; `decodeEvaluation` reads it.
  *
  * A function serialized with `toString()` carries whatever the loader compiled
  * it to. e2e before 0.17 loaded tests through tsx, whose esbuild `keepNames`
@@ -20,5 +27,6 @@ export declare function pageFunctionSource(fn: (...args: never[]) => unknown): s
  * helper; the page has no such helper, so the same one is declared next to
  * the inlined source for as long as this engine supports those runners.
  */
-export declare function compileEvaluation(source: string, hasArgument: boolean): (arg: unknown) => Promise<EvaluationResult>;
-export {};
+export declare function compileEvaluation(source: string, hasArgument: boolean): (arg: unknown) => Promise<string>;
+/** The result of the boundary `compileEvaluation` compiled, from the JSON text it resolved to; throws what the page threw. */
+export declare function decodeEvaluation(text: string): JsonValue | undefined;

package/dist/evaluation.js

@@ -1,8 +1,7 @@
-/** Separates exceptions thrown by trusted page code from failures of the evaluation transport. */
 import { TestError } from 'e2e/engine';
 import { message } from './support.js';
-/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page. */
-export const KEEP_NAMES_HELPER = "const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });";
+/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page; it takes `defineProperty` before that code runs. */
+export const KEEP_NAMES_HELPER = "const __name = ((define) => (target, value) => define(target, 'name', { value, configurable: true }))(({}).constructor.defineProperty);";
 /** A function expression for page code, including ordinary and async method shorthand. Never runs it here. */
 export function pageFunctionSource(fn) {
     const source = fn.toString().trim();
@@ -34,10 +33,82 @@ export function pageFunctionSource(fn) {
         }
     }
 }
+/**
+ * Builds, in the page, the encoder of an evaluation result into JSON text.
+ * Called before the caller's code runs, it takes the intrinsics it needs from
+ * literals, so code that deletes or replaces `Array`, `Object`, or `JSON`
+ * cannot reach it. Only JSON passes: `null`, booleans, finite numbers,
+ * strings, arrays, and plain objects. Anything else throws `{ invalid }` with
+ * the reason `validateJsonValue` gives. Embedded into the page as source, so
+ * it captures nothing from this module.
+ */
+export function pageValueEncoder() {
+    const { getPrototypeOf, keys } = ({}).constructor;
+    const objectPrototype = getPrototypeOf({});
+    const { isArray } = [].constructor;
+    const charCodeAt = ''.charCodeAt;
+    const hex = '0123456789abcdef';
+    const invalid = (reason) => ({ invalid: reason });
+    const quote = (text) => {
+        let out = '"';
+        for (let i = 0; i < text.length; i++) {
+            const code = charCodeAt.call(text, i);
+            const escape = code === 34 || code === 92 || code < 32 || code === 0x2028 || code === 0x2029 || (code >= 0xd800 && code <= 0xdfff);
+            out += escape ? `\\u${hex[code >> 12]}${hex[(code >> 8) & 15]}${hex[(code >> 4) & 15]}${hex[code & 15]}` : text[i];
+        }
+        return `${out}"`;
+    };
+    const ancestors = [];
+    const encode = (value) => {
+        if (value === null)
+            return 'null';
+        switch (typeof value) {
+            case 'string':
+                return quote(value);
+            case 'boolean':
+                return value ? 'true' : 'false';
+            case 'number':
+                if (value !== value || value === Infinity || value === -Infinity)
+                    throw invalid('contains a non-finite number');
+                return `${value}`;
+            case 'object':
+                break;
+            default:
+                throw invalid(`must be JSON-safe, found ${typeof value}`);
+        }
+        const array = isArray(value);
+        const prototype = getPrototypeOf(value);
+        if (!array && prototype !== objectPrototype && prototype !== null)
+            throw invalid('must be JSON-safe');
+        for (let i = 0; i < ancestors.length; i++) {
+            if (ancestors[i] === value)
+                throw invalid('contains a cycle');
+        }
+        ancestors[ancestors.length] = value;
+        let text = '';
+        if (array) {
+            for (let i = 0; i < value.length; i++)
+                text += `${i === 0 ? '' : ','}${encode(value[i])}`;
+            text = `[${text}]`;
+        }
+        else {
+            const record = value;
+            const names = keys(record);
+            for (let i = 0; i < names.length; i++)
+                text += `${i === 0 ? '' : ','}${quote(names[i])}:${encode(record[names[i]])}`;
+            text = `{${text}}`;
+        }
+        ancestors.length -= 1;
+        return text;
+    };
+    return (root) => (root === undefined ? undefined : encode(root));
+}
 /**
  * Compiles the page-side error boundary without evaluating the caller's source in this process.
  * The source is one expression: a function it evaluates to is called with the argument, any
- * other value is the result.
+ * other value is the result. The boundary resolves to JSON text, a primitive the caller takes
+ * back without Playwright serializing it in the page, so a page that deleted or replaced a
+ * global the serializer needs still returns its result; `decodeEvaluation` reads it.
  *
  * A function serialized with `toString()` carries whatever the loader compiled
  * it to. e2e before 0.17 loaded tests through tsx, whose esbuild `keepNames`
@@ -48,23 +119,49 @@ export function pageFunctionSource(fn) {
 export function compileEvaluation(source, hasArgument) {
     try {
         return new Function('arg', `
-      return (async () => {
-        ${KEEP_NAMES_HELPER}
+      ${KEEP_NAMES_HELPER}
+      return (async (encode, run) => {
+        const report = (ok, key, text) => \`{"ok":\${ok}\${text === undefined ? '' : \`,"\${key}":\${text}\`}}\`;
+        let value;
         try {
-          return { ok: true, value: await ((result) => typeof result === 'function' ? result(${hasArgument ? 'arg' : ''}) : result)((${source}\n)) };
+          value = await run();
         } catch (cause) {
           let message;
           try {
-            message = typeof cause?.message === 'string' ? cause.message : String(cause);
+            message = typeof cause?.message === 'string' ? cause.message : \`\${cause}\`;
           } catch {
             message = 'Page evaluation threw an unprintable value';
           }
-          return { ok: false, message };
+          return report(false, 'message', encode(message));
         }
-      })();
+        try {
+          return report(true, 'value', encode(value));
+        } catch (cause) {
+          if (cause !== null && typeof cause === 'object' && typeof cause.invalid === 'string') {
+            return report(false, 'invalid', encode(cause.invalid));
+          }
+          return '{"ok":false,"message":"evaluate result cannot be read"}';
+        }
+      })((${pageValueEncoder.toString()})(), async () => ((result) => typeof result === 'function' ? result(${hasArgument ? 'arg' : ''}) : result)((${source}\n)));
     `);
     }
     catch (cause) {
         throw new TestError('EVALUATE_FAILED', message(cause), { cause });
     }
 }
+/** The result of the boundary `compileEvaluation` compiled, from the JSON text it resolved to; throws what the page threw. */
+export function decodeEvaluation(text) {
+    let report;
+    try {
+        // oxlint-disable-next-line e2e/no-unchecked-json -- the text is what compileEvaluation's own boundary wrote
+        report = JSON.parse(text);
+    }
+    catch (cause) {
+        throw new TestError('EVALUATE_FAILED', 'page evaluation returned an unreadable result', { cause });
+    }
+    if (report.ok)
+        return report.value;
+    if ('invalid' in report)
+        throw new TestError('INVALID_ARGUMENT', `evaluate result ${report.invalid}`);
+    throw new TestError('EVALUATE_FAILED', report.message);
+}

package/dist/frame-document.d.ts

@@ -0,0 +1,20 @@
+/** Which frames hold a document script can read. */
+import type { ElementHandle, Frame } from 'playwright-core';
+/**
+ * True when Playwright can evaluate in the frame without waiting on a
+ * navigation.
+ *
+ * A child frame that has not committed a navigation (its URL is empty, as
+ * while its first request is held) shows its initial empty document.
+ * Chromium creates no script context for that document until script in its
+ * parent touches it, and Playwright waits for the navigation to commit
+ * instead. Reading `contentDocument` from the parent is that touch, so the
+ * frame is readable from then on. A parent that cannot read it (a sandboxed
+ * frame) means no script could have written into it either: it shows
+ * nothing. When the check itself fails, the frame counts as readable, so the
+ * caller's own read of it decides. `owner` is the frame's element when the
+ * caller already holds it.
+ */
+export declare function hasReadableDocument(frame: Frame, owner?: ElementHandle): Promise<boolean>;
+/** The page's frames whose documents script can read; see `hasReadableDocument`. */
+export declare function readableFrames(frames: readonly Frame[]): Promise<Frame[]>;

package/dist/frame-document.js

@@ -0,0 +1,40 @@
+/** Which frames hold a document script can read. */
+/**
+ * True when Playwright can evaluate in the frame without waiting on a
+ * navigation.
+ *
+ * A child frame that has not committed a navigation (its URL is empty, as
+ * while its first request is held) shows its initial empty document.
+ * Chromium creates no script context for that document until script in its
+ * parent touches it, and Playwright waits for the navigation to commit
+ * instead. Reading `contentDocument` from the parent is that touch, so the
+ * frame is readable from then on. A parent that cannot read it (a sandboxed
+ * frame) means no script could have written into it either: it shows
+ * nothing. When the check itself fails, the frame counts as readable, so the
+ * caller's own read of it decides. `owner` is the frame's element when the
+ * caller already holds it.
+ */
+export async function hasReadableDocument(frame, owner) {
+    if (frame.url() !== '' || frame.parentFrame() === null)
+        return true;
+    if (owner !== undefined)
+        return parentReadsDocument(owner);
+    const fetched = await frame.frameElement().catch(() => null);
+    if (fetched === null)
+        return true;
+    try {
+        return await parentReadsDocument(fetched);
+    }
+    finally {
+        await fetched.dispose().catch(() => undefined);
+    }
+}
+/** The page's frames whose documents script can read; see `hasReadableDocument`. */
+export async function readableFrames(frames) {
+    const readable = await Promise.all(frames.map((frame) => hasReadableDocument(frame)));
+    return frames.filter((_, index) => readable[index]);
+}
+/** Reads the frame's document from its parent, which gives it a script context; true when that read fails. */
+function parentReadsDocument(owner) {
+    return owner.evaluate((element) => 'contentDocument' in element && element.contentDocument !== null).catch(() => true);
+}

package/dist/in-page/read-semantics.js

@@ -1460,6 +1460,8 @@ export const readSemanticsFunction = (element, options) => {
         // no rect, as Playwright's `boundingBox()` answers null; a box with no
         // size, or one `visibility: hidden` keeps, is still a rect.
         const rect = el.getClientRects().length === 0 ? null : el.getBoundingClientRect();
+        const borderLeft = Number.parseFloat(style?.borderLeftWidth ?? '') || 0;
+        const borderTop = Number.parseFloat(style?.borderTopWidth ?? '') || 0;
         const role = isDocumentRoot ? 'document' : roleOf(el, tag);
         let level = null;
         if (role === 'heading') {
@@ -1494,6 +1496,7 @@ export const readSemanticsFunction = (element, options) => {
             attributes,
             testId: el.getAttribute(options.testIdAttribute),
             rect: rect === null ? null : { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+            origin: rect === null || (borderLeft === 0 && borderTop === 0) ? null : { x: rect.x + borderLeft, y: rect.y + borderTop },
         };
     };
     // The conditional return type resolves per call site; inside the body the

package/dist/install.d.ts

@@ -13,7 +13,7 @@ export declare function runPlaywrightCli(args: readonly string[]): Promise<numbe
  * disk, a `warn` when the first run will download it, or none when `env`
  * points at another browser cache than this process loaded.
  */
-export declare function browserCheck(name: BrowserName, env: NodeJS.ProcessEnv, headed: boolean, isInstalled?: (name: BrowserName) => boolean | undefined): EngineDoctorCheck[];
+export declare function browserCheck(name: BrowserName, env: NodeJS.ProcessEnv, headed: boolean, isInstalled?: (name: BrowserName) => boolean | undefined | Promise<boolean | undefined>): Promise<EngineDoctorCheck[]>;
 /** What an installer receives besides the browser names. */
 export interface InstallContext {
     /** Receives every line the installer prints: the download URL, progress, warnings. */
@@ -36,7 +36,7 @@ export interface EnsureBrowsersOptions {
      * Injected detection for tests; defaults to an executable existence check.
      * Undefined means "cannot tell here": the installer runs and decides.
      */
-    readonly isInstalled?: (name: BrowserName) => boolean | undefined;
+    readonly isInstalled?: (name: BrowserName) => boolean | undefined | Promise<boolean | undefined>;
     /** Injected installer for tests; defaults to spawning the Playwright CLI. */
     readonly install?: (names: readonly BrowserName[], context: InstallContext) => Promise<void>;
     /** Aborts a download in progress; the run's interrupt owns it. */

package/dist/install.js

@@ -18,11 +18,11 @@ function headlessShellInstalled(browsersPath, revision) {
  * Whether the build the run launches (headless shell for headless chromium, else the full build)
  * is on disk, or undefined when `env` points at another cache than this process loaded.
  */
-function isBrowserInstalled(name, env, headed) {
+async function isBrowserInstalled(name, env, headed) {
     if (env['PLAYWRIGHT_BROWSERS_PATH'] !== process.env['PLAYWRIGHT_BROWSERS_PATH'])
         return undefined;
     try {
-        const executable = browserType(name).executablePath();
+        const executable = (await browserType(name)).executablePath();
         if (headed || name !== 'chromium')
             return existsSync(executable);
         return headlessShellAt(executable);
@@ -79,8 +79,8 @@ export function runPlaywrightCli(args) {
  * disk, a `warn` when the first run will download it, or none when `env`
  * points at another browser cache than this process loaded.
  */
-export function browserCheck(name, env, headed, isInstalled = (browser) => isBrowserInstalled(browser, env, headed)) {
-    const installed = isInstalled(name);
+export async function browserCheck(name, env, headed, isInstalled = (browser) => isBrowserInstalled(browser, env, headed)) {
+    const installed = await isInstalled(name);
     if (installed === undefined)
         return [];
     if (installed)
@@ -115,7 +115,7 @@ export async function ensureBrowsersInstalled(names, options = {}) {
     const env = options.env ?? process.env;
     const headed = options.headed ?? false;
     const isInstalled = options.isInstalled ?? ((name) => isBrowserInstalled(name, env, headed));
-    const verdicts = new Map([...new Set(names)].map((name) => [name, isInstalled(name)]));
+    const verdicts = new Map(await Promise.all([...new Set(names)].map(async (name) => [name, await isInstalled(name)])));
     const missing = [...verdicts.keys()].filter((name) => verdicts.get(name) !== true);
     if (missing.length === 0)
         return;

package/dist/locators.d.ts

@@ -17,6 +17,13 @@ export type PostStep = {
     readonly kind: 'filter';
     readonly options: PwFilterOptions;
 };
+/** What a projection reads besides the expression. */
+export interface ProjectionOptions {
+    /** The attribute a `testId` query reads. */
+    readonly testIdAttribute: string;
+    /** True when a frame along the expression's frame chain is hidden, so every node in it is. */
+    readonly frameHidden: boolean;
+}
 export interface ProjectedLocator {
     /**
      * The Playwright locator to resolve. For a display-value query this is the
@@ -61,8 +68,8 @@ export interface ProjectedLocator {
      */
     readonly visible: boolean;
 }
-/** Projects an expression onto the page; `testIdAttribute` is what a `testId` query reads. */
-export declare function projectExpression(page: Page, expression: LocatorExpression, testIdAttribute: string): ProjectedLocator;
+/** Projects an expression onto the page. */
+export declare function projectExpression(page: Page, expression: LocatorExpression, options: ProjectionOptions): ProjectedLocator;
 /**
  * Applies post steps, innermost first, to an ordered list of matches. `nth`
  * past the end selects nothing, matching Playwright's `nth` on a locator with

package/dist/locators.js

@@ -152,11 +152,19 @@ function queryToPw(scope, query, testIdAttribute) {
  * never selects or retains a node that state calls hidden, and the surface's
  * hold of a terminal query to the batch-read state agrees with it.
  */
-function visibleQueryToPw(scope, query, testIdAttribute) {
-    return narrowedToVisible(queryToPw(scope, query, testIdAttribute), query);
+function visibleQueryToPw(scope, query, options) {
+    return narrowedToVisible(queryToPw(scope, query, options.testIdAttribute), query, options.frameHidden);
 }
-/** The visibility narrowing above, on a locator already built for `query`; identity unless the query is `visible`. */
-function narrowedToVisible(located, query) {
+/**
+ * Matches no element. Inside a hidden frame every node reads as hidden, which
+ * the frame's own document cannot see, so a query that never matches a
+ * hidden node, a `visible` or a role query, narrows to it there.
+ */
+const NOTHING_SELECTOR = 'css=:not(*)';
+/** The visibility narrowing above, on a locator already built for `query`; identity unless the query keeps shown nodes alone. */
+function narrowedToVisible(located, query, frameHidden) {
+    if (frameHidden && (query.visible === true || query.kind === 'role'))
+        return located.locator(NOTHING_SELECTOR);
     if (query.visible !== true)
         return located;
     return located.locator(SHOWN_SELECTOR);
@@ -192,20 +200,20 @@ const DISPLAY_VALUE_COMPOSITION_MESSAGE = 'displayValue queries cannot scope chi
  * unsupported: a display-value query as the scope of a child query, and as a
  * `has` filter.
  */
-function project(scope, expression, testIdAttribute) {
+function project(scope, expression, options) {
     switch (expression.kind) {
         case 'union': {
-            const left = requireComposable(project(scope, expression.left, testIdAttribute));
-            const right = requireComposable(project(scope, expression.right, testIdAttribute));
+            const left = requireComposable(project(scope, expression.left, options));
+            const right = requireComposable(project(scope, expression.right, options));
             return plain(left.or(right));
         }
         case 'query': {
             const inner = expression.scope === undefined
                 ? scope
-                : requireComposable(project(scope, expression.scope, testIdAttribute));
+                : requireComposable(project(scope, expression.scope, options));
             const { query } = expression;
             const exactLabel = query.kind === 'label' && query.value.kind === 'string' && query.value.exact ? query.value : null;
-            const locator = visibleQueryToPw(inner, query, testIdAttribute);
+            const locator = visibleQueryToPw(inner, query, options);
             return {
                 locator,
                 displayValue: query.kind === 'displayValue' ? query.value : null,
@@ -216,30 +224,30 @@ function project(scope, expression, testIdAttribute) {
             };
         }
         case 'filter': {
-            const source = project(scope, expression.source, testIdAttribute);
-            const options = {};
+            const source = project(scope, expression.source, options);
+            const filter = {};
             if (expression.hasText !== undefined)
-                options.hasText = patternToPw(expression.hasText);
+                filter.hasText = patternToPw(expression.hasText);
             if (expression.hasNotText !== undefined)
-                options.hasNotText = patternToPw(expression.hasNotText);
+                filter.hasNotText = patternToPw(expression.hasNotText);
             if (expression.has !== undefined) {
-                options.has = requireComposable(project(scope, expression.has, testIdAttribute));
+                filter.has = requireComposable(project(scope, expression.has, options));
             }
             if (expression.hasNot !== undefined) {
-                options.hasNot = requireComposable(project(scope, expression.hasNot, testIdAttribute));
+                filter.hasNot = requireComposable(project(scope, expression.hasNot, options));
             }
             if (source.steps.length > 0) {
-                return { ...source, steps: [...source.steps, { kind: 'filter', options }] };
+                return { ...source, steps: [...source.steps, { kind: 'filter', options: filter }] };
             }
             return {
                 ...source,
-                locator: source.locator.filter(options),
-                composable: source.composable === null ? null : source.composable.filter(options),
+                locator: source.locator.filter(filter),
+                composable: source.composable === null ? null : source.composable.filter(filter),
                 steps: [],
             };
         }
         case 'index': {
-            const source = project(scope, expression.source, testIdAttribute);
+            const source = project(scope, expression.source, options);
             if (source.displayValue !== null || source.name !== null) {
                 return {
                     ...source,
@@ -252,12 +260,12 @@ function project(scope, expression, testIdAttribute) {
         case 'selector':
             return plain(scope.locator(expression.selector));
         case 'frame':
-            return project(scope.frameLocator(expression.selector), expression.source, testIdAttribute);
+            return project(scope.frameLocator(expression.selector), expression.source, options);
     }
 }
-/** Projects an expression onto the page; `testIdAttribute` is what a `testId` query reads. */
-export function projectExpression(page, expression, testIdAttribute) {
-    return project(page, expression, testIdAttribute);
+/** Projects an expression onto the page. */
+export function projectExpression(page, expression, options) {
+    return project(page, expression, options);
 }
 /**
  * Returns the locator of a projection that must participate in Playwright's

package/dist/observation-capture.js

@@ -37,11 +37,11 @@ export async function captureObservation(page, refs, settings, operation, option
                 captureDocument({
                     ...settings,
                     reserveIds: (count) => refs.reserveIds(count),
-                    commit: (id, element) => {
+                    commit: (id, target) => {
                         if (accepting && !operation.signal.aborted)
-                            generation.set(id, { kind: 'element', element });
+                            generation.set(id, target);
                         else
-                            void element.dispose().catch(() => undefined);
+                            target.list.dispose();
                     },
                 }, page, {
                     framePath: [], budget: MAX_OBSERVED_NODES,

package/dist/observation.d.ts

@@ -2,9 +2,10 @@
  * 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-core';
-import { type NodeRef, type SemanticNode } from 'e2e/engine';
+import type { Frame } from 'playwright-core';
+import { type NodeRef, type SemanticNode, type ViewportPoint } from 'e2e/engine';
 import { type RawNodeData } from './read-node.ts';
+import type { ListedTarget } from './refs.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
@@ -21,8 +22,8 @@ export interface CaptureDeps {
     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;
+    /** Publishes one observed node under its id in the generation being built. */
+    commit(id: string, target: ListedTarget): void;
 }
 export interface CaptureOptions {
     /** Enclosing frame selectors, outermost first; empty for the main document. */
@@ -69,10 +70,13 @@ export declare function frameContentInset(element: Element): Rect;
 /** A frame element's content box, from its border box and `frameContentInset`. */
 export declare function contentBox(border: Rect, inset: Rect): Rect;
 /**
- * A box a child document measured against its own viewport, in the top-level
- * viewport's space: shifted by the frame's box and clipped to it; undefined
- * when nothing of it is inside the frame.
+ * A node box a child document measured against its own viewport, in the
+ * top-level viewport's space: `rect` shifted by the frame's box and clipped
+ * to it, empty when nothing of it is inside the frame. `origin` is shifted
+ * but never clipped, and a clip that moves the box's corner keeps the
+ * unclipped corner as `origin`, so an offset into the node lands where it
+ * would at the top level.
  */
-export declare function placeRectInFrame(rect: Rect, frame: Rect): Rect | undefined;
+export declare function placeBoxInFrame(rect: Rect, origin: ViewportPoint | undefined, frame: Rect): Pick<SemanticNode, 'rect' | 'origin'>;
 export declare function toSemanticNode(ref: NodeRef, raw: RawNodeData, children?: readonly SemanticNode[], framePath?: readonly string[]): SemanticNode;
 export {};