ScramjetClient

Core client for controlling sandboxing and proxying

The ScramjetClient class is the core client that runs inside proxified contexts. It handles DOM API interception, URL rewriting, and provides the sandboxing infrastructure.

Most users won’t need to interact with ScramjetClient directly. It’s automatically created and managed by ScramjetController and ScramjetFrame.

Constructor

Creates a new ScramjetClient instance.

new ScramjetClient(global: typeof globalThis)

global · typeof globalThis · required

The global object to apply Scramjet sandboxing to (typically window or self)

Only one ScramjetClient instance can exist per global context. Attempting to create multiple instances will throw an error.

Properties

global

The global object this client is sandboxing.

global: typeof globalThis

url

Gets or sets the current proxified URL.

get url(): URL
set url(url: URL | string)

Example

console.log("Current URL:", client.url.href);

// Navigate to a new URL
client.url = "https://example.com";

locationProxy

The proxified location object.

locationProxy: Location

bare

The BareClient instance for making bare requests.

bare: BareClient

cookieStore

The cookie store for cookie emulation.

cookieStore: CookieStore

natives

Store for accessing native (unproxied) browser APIs.

natives: {
  store: Record<string, any>;
  call(target: string, that: any, ...args): any;
  construct(target: string, ...args): any;
}

Example

// Call native fetch without proxy interception
const response = client.natives.call(
  "fetch",
  window,
  "https://example.com"
);

descriptors

Store for accessing native property descriptors.

descriptors: {
  store: Record<string, PropertyDescriptor>;
  get(target: string, that: any): any;
  set(target: string, that: any, value: any): void;
}

frame

Returns the ScramjetFrame instance if this client is inside a frame, or null if top-level.

get frame(): ScramjetFrame | null

isSubframe

Returns true if this client is running in a subframe (not created by ScramjetFrame).

get isSubframe(): boolean

Methods

hook()

Applies all Scramjet hooks to the global context. This method is called automatically during initialization.

hook(): void

This method loads and applies all DOM and worker hooks based on the current context.

loadcookies()

Loads cookies from a cookie string.

loadcookies(cookiestr: string): void

cookiestr · string · required

The cookie string to load

Proxy()

Proxies a function or constructor to intercept calls.

Proxy(name: string | string[], handler: Proxy): void

name · string | string[] · required

The name(s) of the API to proxy (e.g., "fetch" or "XMLHttpRequest.prototype.open")

handler · Proxy · required

Handler object with apply and/or construct methods

Example

client.Proxy("fetch", {
  apply(ctx) {
    console.log("Fetch called with:", ctx.args);
    // Modify args before calling
    ctx.args[0] = rewriteUrl(ctx.args[0]);
    return ctx.call();
  }
});

Trap()

Traps a property to intercept get/set operations.

Trap<T>(name: string | string[], descriptor: Trap<T>): PropertyDescriptor

name · string | string[] · required

The name(s) of the property to trap (e.g., "window.location.href")

descriptor · Trap<T> · required

Descriptor object with get and/or set methods

Example

client.Trap("document.cookie", {
  get(ctx) {
    // Return proxified cookies
    return client.cookieStore.getCookies();
  },
  set(ctx, value) {
    // Handle cookie setting
    client.cookieStore.setCookie(value);
  }
});

RawProxy()

Lower-level proxy method that operates directly on objects.

RawProxy(target: any, prop: string, handler: Proxy): void

target · any · required

The target object

prop · string · required

The property name

handler · Proxy · required

Handler object

RawTrap()

Lower-level trap method that operates directly on objects.

RawTrap<T>(target: any, prop: string, descriptor: Trap<T>): PropertyDescriptor

target · any · required

The target object

prop · string · required

The property name

descriptor · Trap<T> · required

Descriptor object

Type definitions

Proxy

Handler for proxying functions and constructors.

type Proxy = {
  construct?(ctx: ProxyCtx): any;
  apply?(ctx: ProxyCtx): any;
};

type ProxyCtx = {
  fn: Function;
  this: any;
  args: any[];
  newTarget: Function;
  return: (r: any) => void;
  call: () => any;
};

Trap

Handler for trapping properties.

type Trap<T> = {
  writable?: boolean;
  value?: any;
  enumerable?: boolean;
  configurable?: boolean;
  get?: (ctx: TrapCtx<T>) => T;
  set?: (ctx: TrapCtx<T>, v: T) => void;
};

type TrapCtx<T> = {
  this: any;
  get: () => T;
  set: (v: T) => void;
};

See module types for complete type definitions.