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

# ScramjetController

> Main controller class for managing Scramjet instances

The `ScramjetController` class manages Scramjet instances, handles configuration, and provides frame creation. It extends `EventTarget` to support listening for global Scramjet events.

## Constructor

Creates a new `ScramjetController` instance.

```typescript theme={null}
new ScramjetController(config: Partial<ScramjetInitConfig>)
```

<ParamField path="config" type="Partial<ScramjetInitConfig>" required>
  Configuration options for Scramjet. See [config types](/api/config-types) for details.

  <Expandable title="Common properties">
    <ParamField path="prefix" type="string">
      The URL prefix for proxied content. Default: `/scramjet/`
    </ParamField>

    <ParamField path="flags" type="Partial<ScramjetFlags>">
      Feature flags to enable or disable Scramjet features
    </ParamField>

    <ParamField path="codec" type="{ encode: Function, decode: Function }">
      Custom URL encoding/decoding functions
    </ParamField>
  </Expandable>
</ParamField>

### Example

```typescript theme={null}
const { ScramjetController } = $scramjetLoadController();

const scramjet = new ScramjetController({
  prefix: "/scramjet/",
  flags: {
    serviceworkers: false,
    syncxhr: false,
    strictRewrites: true,
    captureErrors: true
  }
});
```

## Methods

### init()

Initializes the controller by loading codecs, opening IndexedDB, and setting up message listeners.

```typescript theme={null}
async init(): Promise<void>
```

<Warning>
  You must call `init()` before using other methods on the controller.
</Warning>

#### Example

```typescript theme={null}
await scramjet.init();
```

### createFrame()

Creates a new `ScramjetFrame` instance for managing an iframe.

```typescript theme={null}
createFrame(frame?: HTMLIFrameElement): ScramjetFrame
```

<ParamField path="frame" type="HTMLIFrameElement">
  Optional existing iframe element. If not provided, a new iframe is created.
</ParamField>

#### Returns

A `ScramjetFrame` instance for managing the iframe.

#### Example

```typescript theme={null}
const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);
frame.go("https://example.com");
```

### encodeUrl()

Encodes a real URL into a Scramjet-proxied URL.

```typescript theme={null}
encodeUrl(url: string | URL): string
```

<ParamField path="url" type="string | URL" required>
  The real URL to encode
</ParamField>

#### Returns

The encoded URL with the Scramjet prefix.

#### Example

```typescript theme={null}
const proxiedUrl = scramjet.encodeUrl("https://example.com");
// Returns: "/scramjet/https%3A%2F%2Fexample.com"
```

<Note>
  Only HTTP and HTTPS URLs are encoded. Other protocols are returned unchanged.
</Note>

### decodeUrl()

Decodes a Scramjet-proxied URL back to the real URL.

```typescript theme={null}
decodeUrl(url: string | URL): string
```

<ParamField path="url" type="string | URL" required>
  The proxied URL to decode
</ParamField>

#### Returns

The decoded real URL.

#### Example

```typescript theme={null}
const realUrl = scramjet.decodeUrl("/scramjet/https%3A%2F%2Fexample.com");
// Returns: "https://example.com"
```

### modifyConfig()

Dynamically updates the Scramjet configuration.

```typescript theme={null}
async modifyConfig(newconfig: Partial<ScramjetInitConfig>): Promise<void>
```

<ParamField path="newconfig" type="Partial<ScramjetInitConfig>" required>
  The configuration properties to update
</ParamField>

#### Example

```typescript theme={null}
await scramjet.modifyConfig({
  flags: {
    captureErrors: false,
    strictRewrites: false
  }
});
```

<Info>
  Configuration changes are persisted to IndexedDB and synchronized with the service worker.
</Info>

### addEventListener()

Adds an event listener for Scramjet global events.

```typescript theme={null}
addEventListener<K extends keyof ScramjetGlobalEvents>(
  type: K,
  listener: (event: ScramjetGlobalEvents[K]) => void,
  options?: boolean | AddEventListenerOptions
): void
```

<ParamField path="type" type="'download'" required>
  The event type to listen for
</ParamField>

<ParamField path="listener" type="Function" required>
  The callback function to execute when the event fires
</ParamField>

<ParamField path="options" type="boolean | AddEventListenerOptions">
  Event listener options
</ParamField>

#### Example

```typescript theme={null}
scramjet.addEventListener("download", (event) => {
  console.log("Download intercepted:", event.download.filename);
  console.log("URL:", event.download.url);
});
```

## Events

### download

Fired when a download is intercepted by Scramjet.

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

See [event types](/api/event-types) for the full `ScramjetDownload` interface.