Event types

Event type definitions for Scramjet

Scramjet provides typed events for navigation, downloads, and context initialization.

Global events

Events dispatched on the ScramjetController instance.

ScramjetGlobalEvents

Map of all global Scramjet events with their corresponding event types.

type ScramjetGlobalEvents = {
  download: ScramjetGlobalDownloadEvent;
};

ScramjetGlobalEvent

Union type for all global Scramjet events.

type ScramjetGlobalEvent = ScramjetGlobalDownloadEvent;

ScramjetGlobalDownloadEvent

Event class for proxified download interception.

class ScramjetGlobalDownloadEvent extends Event {
  type: "download";
  download: ScramjetDownload;
}

download · ScramjetDownload · required

The download object containing file information

Example

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

scramjet.addEventListener("download", (event) => {
  console.log("Download intercepted:");
  console.log("Filename:", event.download.filename);
  console.log("URL:", event.download.url);
  console.log("Type:", event.download.type);
  console.log("Size:", event.download.length);
});

ScramjetDownload

Object representing a proxified download.

type ScramjetDownload = {
  filename?: string;
  url: string;
  type: string;
  body: ReadableStream<Uint8Array>;
  length: number;
};

filename · string

The suggested filename for the download (may be undefined)

url · string · required

The URL of the resource being downloaded

type · string · required

The MIME type of the download

body · ReadableStream<Uint8Array> · required

The readable stream containing the download data

length · number · required

The content length in bytes

Frame events

Events dispatched on ScramjetFrame instances.

ScramjetEvents

Map of all Scramjet navigation events with their corresponding event types.

type ScramjetEvents = {
  navigate: NavigateEvent;
  urlchange: UrlChangeEvent;
  contextInit: ScramjetContextEvent;
};

ScramjetEvent

Union type for all Scramjet proxified navigation events.

type ScramjetEvent =
  | NavigateEvent
  | UrlChangeEvent
  | ScramjetContextEvent;

NavigateEvent

Navigation event class fired when a Scramjet frame navigates to a new proxified URL.

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

url · string · required

The real URL being navigated to

Example

frame.addEventListener("navigate", (event) => {
  console.log("Navigating to:", event.url);
  
  // Prevent navigation if needed
  if (event.url.includes("blocked.com")) {
    event.preventDefault();
  }
});

Call event.preventDefault() to prevent the navigation from occurring.

UrlChangeEvent

URL change event class fired when the proxified URL changes in a Scramjet frame.

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

url · string · required

The new URL after the change

Example

frame.addEventListener("urlchange", (event) => {
  console.log("URL changed to:", event.url);
  
  // Update the address bar or UI
  document.querySelector("#address-bar").value = event.url;
});

This event fires after navigation completes, including history API usage.

ScramjetContextEvent

Event class fired when Scramjet initializes in a frame.

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

window · Self · required

The global object (window or worker) where Scramjet was initialized

client · ScramjetClient · required

The ScramjetClient instance for this context

Example

frame.addEventListener("contextInit", (event) => {
  console.log("Scramjet initialized");
  console.log("Client:", event.client);
  console.log("Window:", event.window);
  
  // Access the client instance
  console.log("Current URL:", event.client.url);
});

Complete example

const { ScramjetController } = $scramjetLoadController();

const scramjet = new ScramjetController({
  prefix: "/scramjet/",
  flags: {
    interceptDownloads: true
  }
});

await scramjet.init();

// Listen for downloads on the controller
scramjet.addEventListener("download", (event) => {
  console.log("Download:", event.download.filename);
  console.log("Size:", event.download.length, "bytes");
});

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

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

frame.addEventListener("urlchange", (event) => {
  console.log("URL changed to:", event.url);
  document.title = event.url;
});

frame.addEventListener("contextInit", (event) => {
  console.log("Scramjet initialized in frame");
});

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