Skip to content
FKNdocs
GitHubnpm

Drive a real site and play its video

You can put another website inside your own layout, act on it through locators, and play its video after asking the user once. This page takes that from an empty <iframe> to a currentTime that advances, on either backend, and names the three choices that only show up once the calls are composed.

The end state is a real site rendered inside your app’s layout, playing, with one consent prompt behind it. What the recipe costs:

A backend is where a call runs: the FKN cloud, or the user’s own browser through the extension, the FKN browser extension. Every step carries the [Page] badge, defined on recipes, because attachFrame() needs a window realm, a JavaScript execution context with a window. The two live demos under frames and locators and actions run this shape end to end, so you can watch it before you write it.

[Page] Choose the layout before mounting

Section titled “[Page] Choose the layout before mounting”

An attached frame, the Frame that attachFrame() returns, is bound to one <iframe> element in one place in your document. Moving that element to another parent removes it from the document and inserts it again, and the browser reloads it on the way. On the cloud backend the attachment ends the moment the iframe leaves the document, and every later call throws cloud.attachFrame: the attached iframe left the document or was reloaded; attach a fresh iframe.

So the layout is decided first. Choose where the site sits, a modal or a panel beside your own controls, from what the app knows before the attach, mount the iframe there, and attach it in that place. Read isExtensionExposed() after the attach to decide what the layout shows around it, since the video surface below is an extension backend feature.

[Page] Attach and declare the domains

Section titled “[Page] Attach and declare the domains”

attachFrame() takes the iframe once it is in the document, and domains names the hosts the frame will hold:

app.ts
const 
const iframe: HTMLIFrameElement
iframe = 
var document: Document
window.document returns a reference to the document contained in the window.


MDN Reference
document.
Document.createElement<"iframe">(tagName: "iframe", options?: ElementCreationOptions): HTMLIFrameElement (+2 overloads)
In an HTML document, the document.createElement() method creates the HTML element specified by localName, or an HTMLUnknownElement if localName isn't recognized.


MDN Reference
createElement('iframe')
var document: Document
window.document returns a reference to the document contained in the window.


MDN Reference
document.
ParentNode.querySelector<Element>(selectors: string): Element | null (+4 overloads)
Returns the first element that is a descendant of node that matches selectors.


MDN Reference
querySelector('#player-slot')!.
ParentNode.append(...nodes: (Node | string)[]): void
Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.


Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.


MDN Reference
append(
const iframe: HTMLIFrameElement
iframe) // in the document, in its final place, before the attach


const 
const frame: Frame
frame = await 
function attachFrame(options: AttachFrameOptions): Promise<Frame>
attachFrame({ 
iframe: HTMLIFrameElement
iframe, 
domains?: string[] | undefined
domains: ['example.org'] }) // a Frame, on the extension when it is exposed and on the cloud otherwise
const 
const onExtension: boolean
onExtension = 
function isExtensionExposed(): boolean
Unchanged on purpose, and still exported: a page half built before versioning calls exactly this,
and an extension that announces an ABI must keep answering it the same way. Backwards
compatibility here runs in BOTH directions, which is the only property that matters when neither
end updates on demand.
isExtensionExposed() // true when the attach landed on the extension

The call resolves once a backend has taken the iframe, and the Frame is the same object on either one. The root call takes the extension when it is exposed on the page, and the render proxy, the cloud frame backend, after a short wait otherwise, with no install card on the way, see two backends.

domains does two different jobs. On the extension it lifts the framing headers for those hosts and copies the user’s cookies for them into the frame. On the cloud it is the list of hosts a frame.fetch() may reach, see options.

On the cloud backend the frame holds none of the user’s cookies. It reads the render proxy’s own cookie jar, so a sign-in, when a site wants one, runs inside the frame.

[Page] Ask for the area once

Section titled “[Page] Ask for the area once”

The consent sheet is the prompt the extension shows before an action above severity 0, and click() sits at severity 3. ensure() runs that consent check without touching an element, and subtree: true widens it to an area grant, one answer that covers everything under the chain:

app.ts
try {
  await 
const frame: Frame
frame.
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('.controls').
ensure: (operation: "click" | "fill" | "hover" | "textContent" | "getAttribute" | "isVisible" | "count" | "exists" | "videoElement", options?: EnsureOptions) => Promise<void>
ensure('click', { 
subtree: boolean
subtree: true, 
reason: string
reason: 'Control the player from this app' }) // one sheet, marked Whole area, for act.click on '.controls *'
} catch (
var error: unknown
error) {
  if ((
var error: unknown
error as 
interface Error
Error).
Error.name: string
name !== 'PermissionDeniedError') throw 
var error: unknown
error
  // the user said no, so leave the site's own controls in view
}


await 
const frame: Frame
frame.
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('.controls').
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('#play').
click: (options?: PositionOptions | undefined) => Promise<void>
click() // covered by the area grant, no sheet
await 
const frame: Frame
frame.
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('.controls').
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('#mute').
click: (options?: PositionOptions | undefined) => Promise<void>
click() // covered too, one 'covered' row in the activity log

The two clicks raise no sheet. Each writes one row to the activity log, the on-device record of what an app did, see ensure() and subtree. The refusal arrives under the name PermissionDeniedError, which neither exported guard matches, so test error.name, see a refusal neither guard matches.

Run the ensure() from the click that turns the feature on, with a reason that names what the user gets, see asking well. On the cloud backend the same call resolves at once, because no locator action is gated there, see consent on the cloud backend.

[Page] Navigate with the right wait

Section titled “[Page] Navigate with the right wait”

goto() navigates the frame, and waitUntil decides when it resolves. The two backends want different answers:

app.ts
if (
const onExtension: boolean
onExtension) {
  await 
const frame: Frame
frame.
function goto(url: string, options?: GotoOptions): Promise<void>
goto('https://example.org/player', { 
waitUntil?: "documentstart" | "load" | undefined
waitUntil: 'documentstart' }) // resolves when the new document's content script announces itself
} else {
  await 
const frame: Frame
frame.
function goto(url: string, options?: GotoOptions): Promise<void>
goto('https://example.org/player', { 
waitUntil?: "documentstart" | "load" | undefined
waitUntil: 'load' }) // resolves on the load event, once the render proxy holds the committed document
}
const frame: Frame
frame.
function url(): string
url() // 'https://example.org/player', the url you asked for

On the extension 'documentstart' resolves as soon as the new document exists, before the site has finished loading, and a locator call from then on is retried until its element appears. On the cloud backend the render proxy runs locator calls against the committed document. A 'documentstart' navigation resolves there at once, so every locator call until the commit fails and is retried inside its own 30,000 ms deadline. Ask for 'load' there, so the wait belongs to goto().

Both waits are bounded: 30,000 ms on the extension, and 30,000 ms in the render proxy plus 5,000 ms in the library on the cloud. A relative URL resolves against your page rather than the frame, so pass absolute ones, see goto() and url().

[Page] Read and act

Section titled “[Page] Read and act”

A locator chain is a Locator built by chaining selectors, and nothing touches the page until you call an action on it. Probe first, then read: exists() answers at severity 0 with no sheet, and textContent() reads at severity 1, after one sheet on the extension and none on the cloud:

app.ts
const 
const title: Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
title = 
const frame: Frame
frame.
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('h1') // nothing has happened yet
if (await 
const title: Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
title.
exists: (_options?: LocatorOptions | undefined) => Promise<boolean>
exists()) { // true, a probe at severity 0, no sheet
  
var document: Document
window.document returns a reference to the document contained in the window.


MDN Reference
document.
ParentNode.querySelector<Element>(selectors: string): Element | null (+4 overloads)
Returns the first element that is a descendant of node that matches selectors.


MDN Reference
querySelector('#heading')!.
Element.textContent: string | null
MDN Reference
textContent = await 
const title: Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
title.
textContent: (_options?: LocatorOptions | undefined) => Promise<string>
textContent({ 
reason?: string | undefined
reason: 'Show the title in this app' }) // the heading text, after one sheet for read.text on the extension
}


await 
const frame: Frame
frame.
addStyleTag: (options: AddStyleTagOptions) => Promise<void>
addStyleTag({ 
content: string
content: '#sidebar { display: none }' }) // media.appear, severity 0, with url() stripped from the css first

The heading now sits in your own page, which is the first half of the check below. exists() and count() accept any number of matches and never prompt, where a read or an action needs exactly one match, see reading versus acting. addStyleTag() filters the CSS before it lands, see styling the page.

[Page] Take the video surface

Section titled “[Page] Take the video surface”

videoElement() hands you a RemoteVideoElement, a handle backed by the real <video> inside the frame. It runs at severity 0, so no sheet:

app.ts
const 
const video: RemoteVideoElement
video: 
type RemoteVideoElement = EventTarget & {
    currentTime: number;
    volume: number;
    muted: boolean;
    playbackRate: number;
    src: string;
    loop: boolean;
    autoplay: boolean;
    preload: string;
    poster: string;
    disableRemotePlayback: boolean;
    readonly duration: number;
    readonly paused: boolean;
    readonly ended: boolean;
    readonly seeking: boolean;
    readonly readyState: number;
    readonly currentSrc: string;
    readonly error: MediaError | null;
    readonly buffered: TimeRanges;
    readonly seekable: TimeRanges;
    play(): Promise<void>;
    pause(): void;
    load(): void;
    requestPictureInPicture(): Promise<void>;
    exitPictureInPicture(): Promise<void>;
    readonly HAVE_FUTURE_DATA: 3;
    readonly HAVE_ENOUGH_DATA: 4;
}
RemoteVideoElement = await 
const frame: Frame
frame.
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('video').
videoElement: (_options?: LocatorOptions | undefined) => Promise<RemoteVideoElement>
videoElement() // media.video, severity 0, no sheet


const video: RemoteVideoElement
video.
EventTarget.addEventListener(type: string, callback: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions | boolean): void
The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.


MDN Reference
addEventListener('timeupdate', () => {
  
const video: RemoteVideoElement
video.
currentTime: number
currentTime // advancing, refreshed by the event that just arrived
})
const video: RemoteVideoElement
video.
muted: boolean
muted = true // written locally at once, then reconciled from the frame
await 
const video: RemoteVideoElement
video.
function play(): Promise<void>
play() // the frame's own play() promise, so its rejection reaches you

play() returns the frame’s own promise, and the timeupdate listener keeps currentTime and duration current. Without a listener the read-only fields stay at the snapshot taken when the handle was made, see video. requestPictureInPicture() rejects with requestPictureInPicture is not supported in this environment where the frame’s browser lacks it, so watch the handle’s enterpictureinpicture event instead.

The extension backend serves the handle. On the cloud backend it is not measured, so gate your own control strip on onExtension and leave the site’s player in view otherwise, see limitations.

[Page] Tell terminal from retryable

Section titled “[Page] Tell terminal from retryable”

Every locator action retries a failed attempt every 50 ms until its deadline, then throws the last attempt’s error. Three names stop the loop early, and isLocatorUnsupported() picks out the one no retry can fix:

app.ts
const 
const readTitle: () => Promise<string | null>
readTitle = async (): 
interface Promise<T>
Represents the completion of an asynchronous operation
Promise<string | null> => {
  try {
    return await 
const frame: Frame
frame.
locator: (selector: string) => Locator$1<Extended<{
    readonly element: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly getByRole: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, role: string) => Element[];
                readonly render: (role: unknown) => {
                    fragment: string;
                };
            };
            readonly getByText: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, text: string) => Element[];
                readonly render: (text: unknown) => {
                    fragment: string;
                };
            };
            readonly getByTestId: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, testId: string) => Element[];
                readonly render: (testId: unknown) => {
                    fragment: string;
                };
            };
            readonly first: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                };
            };
            readonly nth: {
                readonly to: "element";
                readonly resolve: (context: LocatorContext, index: number) => Element[];
                readonly render: (index: unknown) => {
                    fragment: string;
                };
            };
        };
        readonly operations: {
            readonly click: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly fill: {
                readonly resolve: (context: LocatorContext, value: string, _options?: OperationOptions) => void;
            };
            readonly hover: {
                readonly resolve: (context: LocatorContext, options?: PositionOptions$1) => void;
            };
            readonly textContent: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => string;
            };
            readonly getAttribute: {
                readonly resolve: (context: LocatorContext, name: string, _options?: OperationOptions) => string | null;
            };
            readonly isVisible: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
            readonly count: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => number;
            };
            readonly exists: {
                readonly resolve: (context: LocatorContext, _options?: OperationOptions) => boolean;
            };
        };
    };
    readonly frame: {
        readonly selectors: {
            readonly locator: {
                readonly to: "element";
                readonly css: true;
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "descend";
                };
            };
            readonly frameLocator: {
                readonly to: "frame";
                readonly css: true;
                readonly barrier: "down";
                readonly resolve: (context: LocatorContext, selector: string) => Element[];
                readonly render: (selector: unknown) => {
                    fragment: string;
                    separator: "down";
                };
            };
            readonly owner: {
                readonly to: "frame";
                readonly barrier: "up";
                readonly resolve: (_context: LocatorContext) => Element[];
                readonly render: () => {
                    fragment: string;
                    separator: "up";
                };
            };
        };
        readonly operations: {
            readonly addStyleTag: {
                readonly resolve: (context: LocatorContext, options: AddStyleTagOptions$1) => void;
            };
            readonly fetch: {
                readonly kind: ChainKind;
                readonly ...
locator('h1').
textContent: (_options?: LocatorOptions | undefined) => Promise<string>
textContent({ 
timeout?: number | undefined
timeout: 5_000 })
  } catch (
function (local var) error: unknown
error) {
    if (
function isLocatorUnsupported(error: unknown): boolean
isLocatorUnsupported(
function (local var) error: unknown
error)) throw 
function (local var) error: unknown
error // this backend cannot run it, and asking again changes nothing
    if (
function isTerminalError(error: unknown): boolean
isTerminalError(
function (local var) error: unknown
error)) throw 
function (local var) error: unknown
error // a gate said no, or the argument was malformed, never retried
    return null // 'No elements found' after 5 s, so try once more when the page settles
  }
}

The first branch is LocatorUnsupportedError: Locator operation not supported on the <backend> backend: <operation> when a backend does not serve the operation. On the cloud path the detached-iframe error from the first step carries the same name, so that the loop stops instead of retrying a dead channel. The second branch covers LocatorDeniedError and the invalid-argument name, both thrown once, see errors.

Everything else is a LocatorError, one failed attempt that the loop already retried. A missing element ends as No elements found once the 5 seconds passed to timeout are spent, and Locator timeout (5000ms): textContent appears only when no attempt failed before the deadline, see what a timeout says. A retry of the whole call is yours to schedule, once the page had time to settle.

Check it worked

Section titled “Check it worked”

The heading from the site is in your own page, and video.currentTime reads higher on each timeupdate than on the one before. When it does not, take these in order:

  1. No elements found after 30 seconds is a timeout wearing another name: the chain matched nothing on its last attempt. Check the selector against the site’s markup, and on the cloud path check that the goto() asked for 'load'.
  2. A frame that went stale means the iframe moved or reloaded. On the cloud the message is cloud.attachFrame: the attached iframe left the document or was reloaded; attach a fresh iframe, and the fix is a fresh iframe in its final place. On the extension a document that navigated off the declared origins refuses with frame: this frame no longer holds the document the app attached it to, and a goto() to a declared target brings it back.
  3. Locator operation not supported on the <backend> backend: <operation> means the frame landed on a backend without that operation. Read isExtensionExposed() and hide the feature rather than retrying.
  4. Locator timeout (30000ms): videoElement means no attempt failed and a single attempt hung. Raise timeout, or find out what the attempt is waiting on.

Optional: Ask for everything at once

Section titled “Optional: Ask for everything at once”

permissions.request() puts read.text and act.click on one sheet with scope * before the first call, the shape the guided demo uses, so the heading read above costs no sheet of its own, see several at once.

Optional: Pin a backend

Section titled “Optional: Pin a backend”

extension.attachFrame() and cloud.attachFrame() skip the choice, and the extension one opens the install card when nothing answers, see pinning a backend.

See also

Section titled “See also”