Frames

epos.frames lets you manage hidden background frames.

This is useful when you need to interact with a real web page in the background, not just fetch data from it.

Creating a Frame

To create a frame, call create() with the target URL:

const frameId = await epos.frames.create('https://example.com')

This creates a hidden <iframe> with that URL and returns a frame id you can use later.

You can create as many frames as you need.

Inspecting Frames

Each frame is an ordinary <iframe> element created inside the offscreen document.

To inspect created frames:

1. Open chrome://extensions.
2. Click Details on the Epos extension card.
3. Click offscreen.html. DevTools will open.
4. Go to Console tab.
5. Select the frame from the DevTools context dropdown, which shows top by default.

INFO

Technically, <background> is also a frame. But it is not managed by epos.frames. Epos manages this frame internally, you cannot create or remove it yourself.

Running Code in Frames

Usually, you also want some code to run inside the frame, not just open it. The setup is the same as with other Epos targets: you tell Epos which files to load and where.

Just prefix the URL pattern with frame::

epos.json

{
  "name": "My Extension",
  "matches": "frame:*://*.example.com/*",
  "load": ["dist/frame.js"]
}

In this setup, Epos injects dist/frame.js into any matching example.com page running inside an <iframe>.

This applies to all matching iframes, not just ones created by epos.frames. If a page contains an iframe with a matching URL, Epos injects the script there as well.

INFO

You can use all Epos features inside iframes, including messaging, state, and storage. No special setup is required.

Removing Frames

When you no longer need a frame, remove it using remove():

await epos.frames.remove(frameId)

Frames are never removed automatically. You have to remove them manually. The only exception is a full extension refresh.

Checking Frame Existence

To check if a frame still exists, use has():

const exists = await epos.frames.has(frameId)
console.log(exists) // true or false

Listing Frames

To get a list of all frames created by the current project, use list():

const frames = await epos.frames.list() // Array<{ id, name, url }>

• id is the unique frame id.
• name is a human-readable name for the frame, generated by Epos.
• url is the initial URL used to create the frame.

Passing Custom Attributes

You can pass any <iframe> attributes as the second argument to create():

const frameId = await epos.frames.create('https://example.com', {
  width: 1200,
  height: 800,
})

The only exceptions are name and src. Epos will ignore them if provided.

What Epos Manages For You

<iframe> elements are more restricted than normal web pages, and many websites block themselves from being embedded.

Epos takes that into account and configures frames for maximum compatibility with no extra setup from your side:

• Epos sets broad allow and sandbox attributes so frames can use as much functionality as possible.
• It also adds a temporary network rule that removes X-Frame-Options for the target frame, which makes embedding possible. When the frame is removed, Epos removes that rule too.
• The engine sets the frame width and height to match your screen by default, so content inside is rendered the same way it would be in a normal tab.