Types Reference — Interfaces, Enums, and Event Payloads

import {
  Application,
  type Dimensions,
  type Monitor,
  type WebviewCookie,
  Theme,
  CursorType,
  ProgressBarState,
} from '@webviewjs/webview';

/** Width and height in pixels. */
interface Dimensions {
  width:  number;
  height: number;
}

/** A two-dimensional point. */
interface Position {
  x: number;
  y: number;
}

/**
 * Logical-pixel rectangle used by child-webview positioning.
 * Coordinates are relative to the parent window's top-left corner.
 */
interface WebviewBounds {
  x:      number;
  y:      number;
  width:  number;
  height: number;
}

interface WebviewCookie {
  name:      string;
  value:     string;
  domain?:   string;
  path?:     string;
  httpOnly?: boolean;
  secure?:   boolean;
  /** `"strict"`, `"lax"`, or `"none"`. */
  sameSite?: 'strict' | 'lax' | 'none';
}

interface HeaderData {
  key:    string;
  value?: string;
}

interface CustomProtocolResponse {
  /** Response body bytes. Required. */
  body:        Buffer;
  /** MIME type, e.g. `"text/html"`. Defaults to `"application/octet-stream"`. */
  mimeType?:   string;
  /** HTTP status code. Defaults to `200`. */
  statusCode?: number;
  /** Extra response headers. */
  headers?:    HeaderData[];
}

interface Monitor {
  /** Display name, if the OS provides one. */
  name?:        string;
  /** DPI scale factor (e.g. `2` for a Retina / HiDPI display). */
  scaleFactor:  number;
  /** Physical resolution in pixels. */
  size:         Dimensions;
  /** Position of the monitor's top-left corner in the virtual desktop space. */
  position:     Position;
  /** All video modes supported by this monitor. */
  videoModes:   VideoMode[];
}

interface VideoMode {
  /** Resolution in pixels. */
  size:        Dimensions;
  /** Colour bit depth (e.g. `32`). */
  bitDepth:    number;
  /** Refresh rate in millihertz (e.g. `60000` for 60 Hz). */
  refreshRate: number;
}

interface IpcMessage {
  /** Raw bytes of the message body. */
  body:    Buffer;
  /** HTTP-style method string (typically `"POST"`). */
  method:  string;
  /** Request headers forwarded by the IPC bridge. */
  headers: HeaderData[];
  /** The IPC endpoint URI. */
  uri:     string;
}

interface ApplicationEvent {
  event:            WebviewApplicationEvent;
  customMenuEvent?: CustomMenuEvent;
}

interface CustomMenuEvent {
  /** The `id` of the `MenuItemOptions` that was clicked. */
  id:       string;
  /** Numeric ID of the window the click originated from. */
  windowId: number;
}

enum WebviewApplicationEvent {
  WindowCloseRequested      = 0,
  ApplicationCloseRequested = 1,
  CustomMenuClick           = 2,
  Ready                     = 3,
}

enum Theme {
  Light  = 0,
  Dark   = 1,
  System = 2,
}

enum FullscreenType {
  /** Full exclusive fullscreen — takes over the display entirely. */
  Exclusive = 0,
  /** Borderless window fullscreen — maximises without a true mode change. */
  Borderless = 1,
}

enum ProgressBarState {
  None          = 0,
  Normal        = 1,
  Indeterminate = 2,
  Paused        = 3,
  Error         = 4,
}

class SerializationError extends Error {
  name: 'SerializationError';
}

import { SerializationError } from '@webviewjs/webview';

webview.expose('api', {
  getData: () => ({
    items: [1, 2, 3],           // ✓ serializable
    map: new Map([['a', 1]]),   // ✗ throws SerializationError
  }),
});

// In an async context you can catch it:
try {
  await page.api.getData();
} catch (err) {
  if (err.name === 'SerializationError') {
    console.error('Return value could not be serialized');
  }
}

interface WebContextOptions {
  /**
   * Custom directory for storing WebView data (cookies, cache, IndexedDB, etc.).
   * Useful on Windows where a bundled application cannot write to Program Files.
   */
  dataDirectory?: string;

  /**
   * Allow browser-automation tools (e.g. WebDriver) to control webviews
   * created in this context.
   * Currently enforced on Linux only; at most one context may allow automation
   * at a time.
   */
  allowsAutomation?: boolean;
}

const ctx = app.createWebContext({
  dataDirectory:    '/home/user/.config/myapp/webdata',
  allowsAutomation: false,
});

const win = app.createBrowserWindow();
const webview = win.createWebview({ url: 'app://localhost/' }, ctx);