ScramjetFrame

Abstraction for managing proxy iframes

The ScramjetFrame class provides an abstraction over proxy iframe creation and management. It handles navigation, event dispatching, and provides access to the proxified context.

Constructor

Creates a new ScramjetFrame instance.

new ScramjetFrame(
  controller: ScramjetController,
  frame: HTMLIFrameElement
)

controller · ScramjetController · required

The ScramjetController instance that manages this frame

frame · HTMLIFrameElement · required

The iframe element to be controlled under Scramjet

You typically won’t call this constructor directly. Use ScramjetController.createFrame() instead.

Example

const { ScramjetController } = $scramjetLoadController();
const scramjet = new ScramjetController({ prefix: "/scramjet/" });
await scramjet.init();

const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);
frame.go("https://example.com");

Properties

frame

The underlying HTMLIFrameElement being managed.

frame: HTMLIFrameElement

Example

const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);
frame.frame.style.width = "100%";
frame.frame.style.height = "600px";

client

Returns the ScramjetClient instance running inside the iframe’s contentWindow.

get client(): ScramjetClient

Returns

The ScramjetClient instance for the iframe’s context.

Example

const client = frame.client;
console.log("Current URL:", client.url);

url

Returns the proxified URL as a URL object.

get url(): URL

Returns

The current proxified URL.

Example

console.log("Current URL:", frame.url.href);
console.log("Hostname:", frame.url.hostname);

Methods

go()

Navigates the iframe to a new URL under Scramjet.

go(url: string | URL): void

url · string | URL · required

A real URL to navigate to

Example

frame.go("https://example.net");
frame.go(new URL("https://example.org"));

back()

Goes backwards in the browser history.

back(): void

Example

frame.back();

forward()

Goes forward in the browser history.

forward(): void

Example

frame.forward();

reload()

Reloads the iframe.

reload(): void

Example

frame.reload();

addEventListener()

Binds event listeners to listen for proxified navigation events in Scramjet.

addEventListener<K extends keyof ScramjetEvents>(
  type: K,
  listener: (event: ScramjetEvents[K]) => void,
  options?: boolean | AddEventListenerOptions
): void

type · 'navigate' | 'urlchange' | 'contextInit' · required

Type of event to listen for

listener · Function · required

Event listener callback function

options · boolean | AddEventListenerOptions

Options for the event listener

Example

// Listen for URL changes
frame.addEventListener("urlchange", (event) => {
  console.log("URL changed:", event.url);
  document.title = event.url; // Update page title
});

// Listen for navigation events
frame.addEventListener("navigate", (event) => {
  console.log("Navigating to:", event.url);
});

// Listen for context initialization
frame.addEventListener("contextInit", (event) => {
  console.log("Scramjet initialized in frame");
});

Events

navigate

Fired when the frame navigates to a new proxified URL.

class NavigateEvent extends Event {
  type: "navigate";
  url: string;
}

urlchange

Fired when the proxified URL changes in the frame.

class UrlChangeEvent extends Event {
  type: "urlchange";
  url: string;
}

contextInit

Fired when Scramjet initializes in the frame.

class ScramjetContextEvent extends Event {
  type: "contextInit";
  window: Self;
  client: ScramjetClient;
}

See event types for complete event definitions.

Complete example

const { ScramjetController } = $scramjetLoadController();

const scramjet = new ScramjetController({ prefix: "/scramjet/" });
await scramjet.init();

const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);

// Listen for proxified navigation events
frame.addEventListener("urlchange", (e) => {
  console.log("URL changed to:", e.url);
});

// Navigate to a URL
frame.go("https://example.com");

// Control navigation
frame.back();
frame.forward();
frame.reload();