> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mercuryworkshop/scramjet/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```typescript theme={null}
type ScramjetGlobalEvents = {
  download: ScramjetGlobalDownloadEvent;
};
```

### ScramjetGlobalEvent

Union type for all global Scramjet events.

```typescript theme={null}
type ScramjetGlobalEvent = ScramjetGlobalDownloadEvent;
```

### ScramjetGlobalDownloadEvent

Event class for proxified download interception.

```typescript theme={null}
class ScramjetGlobalDownloadEvent extends Event {
  type: "download";
  download: ScramjetDownload;
}
```

<ParamField path="download" type="ScramjetDownload" required>
  The download object containing file information
</ParamField>

#### Example

```typescript theme={null}
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.

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

<ParamField path="filename" type="string">
  The suggested filename for the download (may be undefined)
</ParamField>

<ParamField path="url" type="string" required>
  The URL of the resource being downloaded
</ParamField>

<ParamField path="type" type="string" required>
  The MIME type of the download
</ParamField>

<ParamField path="body" type="ReadableStream<Uint8Array>" required>
  The readable stream containing the download data
</ParamField>

<ParamField path="length" type="number" required>
  The content length in bytes
</ParamField>

## Frame events

Events dispatched on `ScramjetFrame` instances.

### ScramjetEvents

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

```typescript theme={null}
type ScramjetEvents = {
  navigate: NavigateEvent;
  urlchange: UrlChangeEvent;
  contextInit: ScramjetContextEvent;
};
```

### ScramjetEvent

Union type for all Scramjet proxified navigation events.

```typescript theme={null}
type ScramjetEvent =
  | NavigateEvent
  | UrlChangeEvent
  | ScramjetContextEvent;
```

### NavigateEvent

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

```typescript theme={null}
class NavigateEvent extends Event {
  type: "navigate";
  url: string;
}
```

<ParamField path="url" type="string" required>
  The real URL being navigated to
</ParamField>

#### Example

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

<Info>
  Call `event.preventDefault()` to prevent the navigation from occurring.
</Info>

### UrlChangeEvent

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

```typescript theme={null}
class UrlChangeEvent extends Event {
  type: "urlchange";
  url: string;
}
```

<ParamField path="url" type="string" required>
  The new URL after the change
</ParamField>

#### Example

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

<Note>
  This event fires after navigation completes, including history API usage.
</Note>

### ScramjetContextEvent

Event class fired when Scramjet initializes in a frame.

```typescript theme={null}
class ScramjetContextEvent extends Event {
  type: "contextInit";
  window: Self;
  client: ScramjetClient;
}
```

<ParamField path="window" type="Self" required>
  The global object (window or worker) where Scramjet was initialized
</ParamField>

<ParamField path="client" type="ScramjetClient" required>
  The ScramjetClient instance for this context
</ParamField>

#### Example

```typescript theme={null}
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

```typescript theme={null}
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");
```