Skip to main content
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;
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");