API Reference

IframeShield

Constructor

new IframeShield(config?: Partial<IframeShieldConfig>)

Creates a new instance. Automatically starts memory monitoring, device detection, and crash recovery.

.register(target, options?)

shield.register(
  target: string | HTMLIFrameElement,
  options?: RegisterOptions
): string

Param	Type	Description
`target`	`string \| HTMLIFrameElement`	CSS selector or element reference
`options.priority`	`number`	Higher = kept alive longer under pressure. Default: `0`
`options.estimatedMemoryMB`	`number`	Estimated memory usage of iframe content
`options.quality`	`QualityLevel`	Override auto quality for this iframe

.setQuality(target, quality)

shield.setQuality(target: string | HTMLIFrameElement, quality: QualityLevel): void

Set quality level. Blocked in yellow+ memory zones for upgrades. Manual changes trigger a 30-second user lock.

.freeze(target, level?)

shield.freeze(target: string | HTMLIFrameElement, level?: FreezeLevel): void

Level	Effect	Resumable?
`1`	Viewport shrink via HTML attributes	Yes, instant
`2`	Detach from DOM, keep reference	Yes, re-attach
`3`	Set src=about:blank, destroy WebGL context	Yes, full reload

.resume(target)

shield.resume(target: string | HTMLIFrameElement): void

Resume from any freeze level. Level 3 requires full iframe reload. Blocked in red+ zones.

.destroy(target)

shield.destroy(target: string | HTMLIFrameElement): void

Permanently remove iframe and free all memory. Cannot be resumed.

.getStats()

shield.getStats(): ShieldStats

Returns current state:

{
  totalRegistered: number,
  activeCount: number,
  frozenCount: number,
  estimatedTotalMemoryMB: number,
  memoryBudgetMB: number,
  memoryZone: MemoryZone,
  wasmProbeAvailable: boolean,
  crashRecoveryActive: boolean,
  iframes: IframeStats[]
}

.getMemoryZone()

shield.getMemoryZone(): 'green' | 'yellow' | 'red' | 'critical' | 'emergency'

.getFreezeLevel(target)

shield.getFreezeLevel(target): FreezeLevel | null

.dispose()

shield.dispose(): void

Cleanup everything. Restore all iframes to original state. Remove all listeners.

GameProxy

Constructor

new GameProxy(config?: Partial<GameProxyConfig>)

.createProxyIframe(gameUrl, container, onReport?)

proxy.createProxyIframe(
  gameUrl: string,
  container: HTMLElement,
  onReport?: (data) => void
): Promise<ProxyResult>

Fetches game HTML, rewrites URLs, injects WebGL interceptor, creates blob: iframe.

.destroy()

proxy.destroy(): void

Revoke blob URLs, remove message listeners.

React Hook

import { useIframeShield } from 'iframe-shield/react';

const {
  iframeRef,       // RefObject<HTMLIFrameElement>
  shieldId,        // string | null
  stats,           // ShieldStats | null (updates every 5s)
  setQuality,      // (quality: QualityLevel) => void
  freeze,          // () => void
  resume,          // () => void
  destroy,         // () => void
  refresh,         // () => void (force stats refresh)
} = useIframeShield(options);

Types

QualityLevel

type QualityLevel = 'high' | 'medium' | 'low' | 'minimal'

FreezeLevel

type FreezeLevel = 0 | 1 | 2 | 3

MemoryZone

type MemoryZone = 'green' | 'yellow' | 'red' | 'critical' | 'emergency'

DeviceTier

type DeviceTier = 'low-end-mobile' | 'mid-mobile' | 'high-mobile'
  | 'tablet' | 'desktop' | 'high-end-desktop'

Standalone Utilities

detectDeviceProfile()

import { detectDeviceProfile } from 'iframe-shield';
const tier = detectDeviceProfile(); // DeviceTier

getConfigForProfile(tier)

import { getConfigForProfile } from 'iframe-shield';
const config = getConfigForProfile('mid-mobile'); // Partial<IframeShieldConfig>

buildInterceptorScript(config)

import { buildInterceptorScript } from 'iframe-shield';
const js = buildInterceptorScript({ maxTextureSize: 512 }); // string

getDeviceInfo()

import { getDeviceInfo } from 'iframe-shield';
const info = getDeviceInfo();
// { isIOS, isSafari, isIOSSafari, isMobile, deviceMemoryGB, estimatedMaxMemoryMB, ... }