attachFrame()

The attachFrame() function of @fkn/lib attaches an <iframe> element your page embeds and returns a Frame handle: the root locator for finding elements and performing actions inside it, plus navigation helpers.

It requires the FKN extension. The attachment itself is a low-severity capability; the actions you perform through the returned frame are gated individually by the consent system.

Syntax

const 
const frame: Frame
frame = await 
function attachFrame({ iframe, domains }: AttachFrameOptions): Promise<Frame>
attachFrame({
  
iframe: HTMLIFrameElement
iframe: 
var document: Document
window.document returns a reference to the document contained in the window.
MDN Reference
document.
ParentNode.querySelector<"iframe">(selectors: "iframe"): HTMLIFrameElement | null (+4 overloads)
Returns the first element that is a descendant of node that matches selectors.
MDN Reference
querySelector('iframe')!,
})

Parameters

iframe: the HTMLIFrameElement to attach. It must be connected to the document. Its src may be empty or about:blank and filled in later via goto().
domains (optional): a list of additional domains the frame is expected to navigate across, requested as part of the same consent.

Return value

A Promise resolving to a Frame: a FrameLocator extended with:

goto(url, options?): navigate the frame. options.waitUntil is 'documentstart' or 'load'.
url(): the frame’s current src.

Examples

Drive a player embedded from another site

import { 
const attachFrame: ({ iframe, domains }: AttachFrameOptions) => Promise<Frame>
attachFrame, 
const waitForExtensionExposure: (timeout?: number) => Promise<void>
waitForExtensionExposure } from '@fkn/lib'

await 
function waitForExtensionExposure(timeout?: number): Promise<void>
waitForExtensionExposure()

const 
const iframe: HTMLIFrameElement
iframe = 
var document: Document
window.document returns a reference to the document contained in the window.
MDN Reference
document.
ParentNode.querySelector<HTMLIFrameElement>(selectors: string): HTMLIFrameElement | null (+4 overloads)
Returns the first element that is a descendant of node that matches selectors.
MDN Reference
querySelector<
interface HTMLIFrameElement
The HTMLIFrameElement interface provides special properties and methods (beyond those of the HTMLElement interface it also has available to it by inheritance) for manipulating the layout and presentation of inline frame elements.
MDN Reference
HTMLIFrameElement>('#player')!
const 
const frame: Frame
frame = await 
function attachFrame({ iframe, domains }: AttachFrameOptions): Promise<Frame>
attachFrame({ 
iframe: HTMLIFrameElement
iframe })

await 
const frame: Frame
frame.
function goto(url: string, options?: GotoOptions): Promise<void>
goto('https://example.com/watch/123', { 
waitUntil?: "documentstart" | "load" | undefined
waitUntil: 'load' })
await 
const frame: Frame
frame.
locator: (selector: string) => Locator
locator('.controls').
getByText: (text: string) => Locator
getByText('Play').
click: (options?: (OperationTimeoutOptions & {
    position?: {
        x?: number | undefined;
        y?: number | undefined;
    } | undefined;
}) | undefined) => Promise<void>
click()

Ask for an area grant up front

One prompt covering a whole region of the page, instead of one per control. See Permissions and consent for how covered actions are logged.

await 
const frame: Frame
frame.
locator: (selector: string) => Locator
locator('.controls').
ensure: (operation: "click" | "fill" | "hover" | "textContent" | "isVisible" | "count" | "exists" | "getAttribute" | "videoElement", options?: {
    reason?: string;
    timeout?: number;
    subtree?: boolean;
} & Record<string, unknown>) => Promise<void>
ensure('click', { 
subtree?: boolean | undefined
subtree: true })

// These run without further prompts, and are audit-logged as covered
await 
const frame: Frame
frame.
locator: (selector: string) => Locator
locator('.controls').
locator: (selector: string) => Locator
locator('#play').
click: (options?: (OperationTimeoutOptions & {
    position?: {
        x?: number | undefined;
        y?: number | undefined;
    } | undefined;
}) | undefined) => Promise<void>
click()
await 
const frame: Frame
frame.
locator: (selector: string) => Locator
locator('.controls').
locator: (selector: string) => Locator
locator('#volume-up').
click: (options?: (OperationTimeoutOptions & {
    position?: {
        x?: number | undefined;
        y?: number | undefined;
    } | undefined;
}) | undefined) => Promise<void>
click()

Security

attachFrame() and goto() refuse to target the extension’s own pages (chrome-extension:, moz-extension:) and the FKN platform origin (fkn.app and subdomains). Either would let an embedded app escalate out of its sandbox. The check is enforced in the extension’s content script; the page-side API mirrors it for a fast, clear error.