Configuration

Core Options

Option	Type	Default	Description
`memoryBudgetMB`	`number`	`600`	Total memory budget in MB. Triggers watermark zones when exceeded.
`quality`	`'auto' \| QualityLevel`	`'auto'`	Initial quality. `auto` selects based on device tier.
`maxConcurrentActive`	`number`	`1`	Max iframes active simultaneously. Others frozen with placeholders.
`lazyLoad`	`boolean`	`true`	Load iframes only when visible (IntersectionObserver).
`rootMargin`	`string`	`'200px'`	Preload distance before viewport entry.
`deviceProfile`	`'auto' \| DeviceTier`	`'auto'`	Device tier detection. `auto` detects from UA and screen.

iOS Configuration

Option	Type	Default	Description
`ios.crashPrevention`	`boolean`	`true`	Enable all iOS Safari protections.
`ios.backgroundFreeze`	`boolean`	`true`	Freeze all iframes when page is backgrounded.
`ios.backgroundDestroyLowPriority`	`boolean`	`true`	Destroy low-priority iframes on background (not just freeze).
`ios.memoryWarningThreshold`	`number`	`0.7`	Start degrading at this fraction of budget (0-1).
`ios.aggressiveCleanup`	`boolean`	`true`	Aggressive GC hints and resource cleanup.
`ios.maxMemoryMB`	`number`	`1200`	Estimated Safari memory limit for device.
`ios.sandboxAttributes`	`string`	`'allow-scripts allow-same-origin allow-popups'`	Sandbox attributes applied to iframes.

Watermark Zones

Thresholds are fractions of memoryBudgetMB.

Option	Default	Zone triggered above
`watermark.greenMax`	`0.6`	Yellow (auto-downgrade quality)
`watermark.yellowMax`	`0.75`	Red (freeze non-visible)
`watermark.redMax`	`0.85`	Critical (single iframe, minimal quality)
`watermark.criticalMax`	`0.95`	Emergency (destroy low-priority)

Crash Recovery

Option	Type	Default	Description
`crashRecovery.enabled`	`boolean`	`true`	Enable crash detection and auto-recovery.
`crashRecovery.storageKey`	`string`	`'iframe-shield-recovery'`	sessionStorage key for crash state.
`crashRecovery.stabilityPeriodMs`	`number`	`30000`	Milliseconds stable before resetting crash counter.
`crashRecovery.maxRecoveryAttempts`	`number`	`3`	After N crashes, load at minimal quality permanently.

Network Budget

Option	Type	Default	Description
`networkBudget.enabled`	`boolean`	`true`	Track bytes transferred per iframe domain.
`networkBudget.maxTransferMB`	`number`	`500`	Freeze iframe after this many MB downloaded.
`networkBudget.trackingIntervalMs`	`number`	`2000`	How often to check transfer budgets.

Debug Overlay

Option	Type	Default	Description
`debugger.enabled`	`boolean`	`false`	Show visual debug overlay.
`debugger.position`	`DebugOverlayPosition`	`'bottom-right'`	Overlay position: `bottom-right`, `bottom-left`, `top-right`, `top-left`.
`debugger.shortcut`	`string`	`'ctrl+shift+q'`	Keyboard shortcut to toggle overlay.

Game Proxy / Interceptor

Option	Type	Default	Description
`interceptor.maxTextureSize`	`number`	`1024`	Max texture dimension in pixels. Larger textures are downscaled.
`interceptor.maxCanvasWidth`	`number`	`1280`	Max WebGL canvas width.
`interceptor.maxCanvasHeight`	`number`	`720`	Max WebGL canvas height.
`interceptor.maxDevicePixelRatio`	`number`	`1`	Override window.devicePixelRatio.
`interceptor.maxFps`	`number`	`30`	Throttle requestAnimationFrame to this FPS.
`interceptor.maxWasmMemoryMB`	`number`	`256`	Cap WebAssembly.Memory maximum pages.
`interceptor.audioSampleRate`	`number`	`22050`	Downsample decoded audio buffers to this rate.

Callbacks

Callback	Arguments	When
`onMemoryWarning`	`(info: MemoryWarningInfo)`	Memory pressure detected
`onQualityChange`	`(id, oldQ, newQ)`	Quality level changed
`onIframeFreeze`	`(id)`	Iframe frozen
`onIframeResume`	`(id)`	Iframe resumed
`onIframeDestroy`	`(id)`	Iframe destroyed
`onCrashPrevented`	`(id, reason)`	Crash was prevented
`onCrashRecovered`	`(info: CrashRecoveryInfo)`	Recovered from previous crash
`onWatermarkZoneChange`	`(oldZone, newZone)`	Memory zone transition
`onError`	`(error: IframeShieldError)`	Internal error

Full Example

new IframeShield({
  memoryBudgetMB: 600,
  quality: 'auto',
  maxConcurrentActive: 1,
  lazyLoad: true,
  rootMargin: '200px',
  deviceProfile: 'auto',

  ios: {
    crashPrevention: true,
    backgroundFreeze: true,
    backgroundDestroyLowPriority: true,
    memoryWarningThreshold: 0.7,
    aggressiveCleanup: true,
    maxMemoryMB: 1200,
  },

  watermark: { greenMax: 0.6, yellowMax: 0.75, redMax: 0.85, criticalMax: 0.95 },
  crashRecovery: { enabled: true, stabilityPeriodMs: 30000, maxRecoveryAttempts: 3 },
  networkBudget: { enabled: true, maxTransferMB: 500 },
  debugger: { enabled: false, position: 'bottom-right', shortcut: 'ctrl+shift+q' },

  onMemoryWarning: (info) => console.log('Memory:', info.estimatedUsageMB, 'MB'),
  onQualityChange: (id, oldQ, newQ) => console.log(id, oldQ, '->', newQ),
  onCrashPrevented: (id, reason) => console.warn('Crash prevented:', reason),
});