@nativewindow/webview 0.1.1

package/dist/index.js

@@ -0,0 +1,406 @@
+import { NativeWindow as NativeWindow$1, init, pumpEvents } from "../native-window.js";
+import { checkRuntime, ensureRuntime, loadHtmlOrigin } from "../native-window.js";
+let _pump = null;
+let _windowCount = 0;
+function ensureInit() {
+  if (_pump) return;
+  init();
+  _pump = setInterval(() => {
+    try {
+      pumpEvents();
+    } catch (e) {
+      console.error("[native-window] pumpEvents() error:", e);
+    }
+  }, 16);
+}
+function stopPump() {
+  if (_pump) {
+    clearInterval(_pump);
+    _pump = null;
+  }
+}
+class NativeWindow {
+  /** @internal */
+  _native;
+  /** @internal */
+  _closed = false;
+  /** @internal */
+  _unsafe;
+  /** @internal */
+  _devtools;
+  constructor(options) {
+    ensureInit();
+    _windowCount++;
+    this._native = new NativeWindow$1(options);
+    this._native.onClose(() => this._handleClose());
+  }
+  /** @internal */
+  _handleClose() {
+    if (this._closed) return;
+    this._closed = true;
+    _windowCount--;
+    this._userCloseCallback?.();
+    if (_windowCount <= 0) {
+      _windowCount = 0;
+      setTimeout(() => stopPump(), 200);
+    }
+  }
+  /**
+   * Throws if the window has been closed.
+   * @internal
+   */
+  _ensureOpen() {
+    if (this._closed) {
+      throw new Error("Window is closed");
+    }
+  }
+  // ---- onClose with user callback support ----
+  _userCloseCallback;
+  /**
+   * Register a handler for the window close event.
+   * The pump is automatically stopped when all windows are closed.
+   *
+   * Calling this multiple times replaces the previous handler.
+   */
+  onClose(callback) {
+    if (this._userCloseCallback) {
+      console.warn(
+        "NativeWindow: onClose() called multiple times. The previous handler will be replaced."
+      );
+    }
+    this._userCloseCallback = callback;
+  }
+  // ---- Getters ----
+  /** Unique window ID */
+  get id() {
+    return this._native.id;
+  }
+  // ---- Content loading ----
+  loadUrl(url) {
+    this._ensureOpen();
+    this._native.loadUrl(url);
+  }
+  /**
+   * Load raw HTML content into the webview.
+   *
+   * @security **Injection risk.** Never interpolate unsanitized user input
+   * into HTML strings. Use a dedicated sanitization library such as
+   * [DOMPurify](https://github.com/cure53/DOMPurify) or
+   * [sanitize-html](https://github.com/apostrophecms/sanitize-html) to
+   * sanitize untrusted content before embedding it.
+   */
+  loadHtml(html) {
+    this._ensureOpen();
+    this._native.loadHtml(html);
+  }
+  postMessage(message) {
+    this._ensureOpen();
+    this._native.postMessage(message);
+  }
+  // ---- Unsafe operations ----
+  /**
+   * Namespace for operations that require extra care to avoid injection risks.
+   * Methods under `unsafe` execute arbitrary code in the webview context.
+   *
+   * @security Never pass unsanitized user input to these methods.
+   * Use {@link sanitizeForJs} to escape strings before embedding them in
+   * script code.
+   */
+  get unsafe() {
+    this._ensureOpen();
+    if (!this._unsafe) {
+      this._unsafe = {
+        evaluateJs: (script) => {
+          this._ensureOpen();
+          this._native.evaluateJs(script);
+        }
+      };
+    }
+    return this._unsafe;
+  }
+  // ---- Devtools ----
+  /**
+   * Namespace for controlling the browser devtools panel.
+   * Requires `devtools: true` in {@link WindowOptions} at window creation.
+   *
+   * @example
+   * ```ts
+   * const win = new NativeWindow({ devtools: true });
+   * win.devtools.open();
+   * console.log(win.devtools.isOpen()); // true
+   * win.devtools.close();
+   * ```
+   */
+  get devtools() {
+    this._ensureOpen();
+    if (!this._devtools) {
+      this._devtools = {
+        open: () => {
+          this._ensureOpen();
+          this._native.openDevtools();
+        },
+        close: () => {
+          this._ensureOpen();
+          this._native.closeDevtools();
+        },
+        isOpen: () => {
+          this._ensureOpen();
+          return this._native.isDevtoolsOpen();
+        }
+      };
+    }
+    return this._devtools;
+  }
+  // ---- Window control ----
+  setTitle(title) {
+    this._ensureOpen();
+    this._native.setTitle(title);
+  }
+  setSize(width, height) {
+    this._ensureOpen();
+    this._native.setSize(width, height);
+  }
+  setMinSize(width, height) {
+    this._ensureOpen();
+    this._native.setMinSize(width, height);
+  }
+  setMaxSize(width, height) {
+    this._ensureOpen();
+    this._native.setMaxSize(width, height);
+  }
+  setPosition(x, y) {
+    this._ensureOpen();
+    this._native.setPosition(x, y);
+  }
+  setResizable(resizable) {
+    this._ensureOpen();
+    this._native.setResizable(resizable);
+  }
+  setDecorations(decorations) {
+    this._ensureOpen();
+    this._native.setDecorations(decorations);
+  }
+  setAlwaysOnTop(alwaysOnTop) {
+    this._ensureOpen();
+    this._native.setAlwaysOnTop(alwaysOnTop);
+  }
+  /**
+   * Set the window icon from a PNG or ICO file path.
+   * On macOS this is silently ignored (macOS doesn't support per-window icons).
+   * Relative paths resolve from the working directory.
+   */
+  setIcon(path) {
+    this._ensureOpen();
+    this._native.setIcon(path);
+  }
+  // ---- Window state ----
+  show() {
+    this._ensureOpen();
+    this._native.show();
+  }
+  hide() {
+    this._ensureOpen();
+    this._native.hide();
+  }
+  close() {
+    this._ensureOpen();
+    this._native.close();
+  }
+  focus() {
+    this._ensureOpen();
+    this._native.focus();
+  }
+  maximize() {
+    this._ensureOpen();
+    this._native.maximize();
+  }
+  minimize() {
+    this._ensureOpen();
+    this._native.minimize();
+  }
+  unmaximize() {
+    this._ensureOpen();
+    this._native.unmaximize();
+  }
+  reload() {
+    this._ensureOpen();
+    this._native.reload();
+  }
+  // ---- Event handlers ----
+  /**
+   * Register a handler for messages from the webview.
+   *
+   * @security **No origin filtering.** The raw `onMessage` API does not
+   * enforce origin restrictions. If your webview navigates to untrusted
+   * URLs, validate the `sourceUrl` parameter before processing messages.
+   * For automatic origin filtering, use `createChannel()` with the
+   * `trustedOrigins` option from `native-window-ipc`.
+   *
+   * @security **No rate limiting.** Messages from the webview are delivered
+   * without throttling. A malicious page can flood the host with messages.
+   * Consider implementing application-level rate limiting if loading
+   * untrusted content.
+   */
+  onMessage(callback) {
+    this._ensureOpen();
+    this._native.onMessage(callback);
+  }
+  onResize(callback) {
+    this._ensureOpen();
+    this._native.onResize(callback);
+  }
+  onMove(callback) {
+    this._ensureOpen();
+    this._native.onMove(callback);
+  }
+  onFocus(callback) {
+    this._ensureOpen();
+    this._native.onFocus(callback);
+  }
+  onBlur(callback) {
+    this._ensureOpen();
+    this._native.onBlur(callback);
+  }
+  onPageLoad(callback) {
+    this._ensureOpen();
+    this._native.onPageLoad(callback);
+  }
+  onTitleChanged(callback) {
+    this._ensureOpen();
+    this._native.onTitleChanged(callback);
+  }
+  onReload(callback) {
+    this._ensureOpen();
+    this._native.onReload(callback);
+  }
+  /**
+   * Register a handler for blocked navigation events.
+   * Fired when a navigation is blocked by the {@link WindowOptions.allowedHosts}
+   * restriction. Receives the URL that was blocked.
+   *
+   * @example
+   * ```ts
+   * win.onNavigationBlocked((url) => {
+   *   console.log("Blocked navigation to:", url);
+   * });
+   * ```
+   */
+  onNavigationBlocked(callback) {
+    this._ensureOpen();
+    this._native.onNavigationBlocked(callback);
+  }
+  // ---- Cookie access ----
+  /**
+   * Validate and parse a raw cookies JSON array from the native layer.
+   * Returns a cleaned {@link CookieInfo} array or `null` if the payload
+   * is malformed.
+   *
+   * @internal
+   */
+  _validateCookies(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(parsed)) return null;
+    const cookies = [];
+    for (const item of parsed) {
+      if (typeof item !== "object" || item === null) continue;
+      const obj = item;
+      if (typeof obj.name !== "string" || typeof obj.value !== "string") {
+        continue;
+      }
+      if (typeof obj.domain !== "string" || typeof obj.path !== "string") {
+        continue;
+      }
+      if (typeof obj.httpOnly !== "boolean" || typeof obj.secure !== "boolean") {
+        continue;
+      }
+      if (typeof obj.sameSite !== "string" || typeof obj.expires !== "number") {
+        continue;
+      }
+      cookies.push({
+        name: obj.name,
+        value: obj.value,
+        domain: obj.domain,
+        path: obj.path,
+        httpOnly: obj.httpOnly,
+        secure: obj.secure,
+        sameSite: obj.sameSite,
+        expires: obj.expires
+      });
+    }
+    return cookies;
+  }
+  /**
+   * Query cookies from the native cookie store.
+   *
+   * Returns a Promise that resolves with validated {@link CookieInfo} objects,
+   * including `HttpOnly` cookies that are invisible to `document.cookie`.
+   *
+   * - **macOS**: Uses `WKHTTPCookieStore.getAllCookies` with client-side
+   *   URL filtering (domain + path match).
+   * - **Windows**: Uses `ICoreWebView2CookieManager.GetCookies` which
+   *   filters by URI natively.
+   *
+   * @param url  If provided, only cookies matching this URL are returned.
+   *             If omitted, all cookies in the webview's cookie store are returned.
+   *
+   * @example
+   * ```ts
+   * const cookies = await win.getCookies("https://example.com");
+   * const session = cookies.find((c) => c.name === "session_id");
+   * if (session) console.log("Session:", session.value, "HttpOnly:", session.httpOnly);
+   * ```
+   */
+  getCookies(url) {
+    this._ensureOpen();
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("getCookies() timed out after 10 seconds"));
+      }, 1e4);
+      this._native.onCookies((raw) => {
+        clearTimeout(timeout);
+        const validated = this._validateCookies(raw);
+        if (validated) {
+          resolve(validated);
+        } else {
+          reject(new Error("Failed to parse cookie response"));
+        }
+      });
+      this._native.getCookies(url);
+    });
+  }
+  /**
+   * Clear cookies from the native cookie store.
+   *
+   * - If `host` is provided, only cookies whose domain matches that host
+   *   are deleted (e.g. `"example.com"` deletes `.example.com` cookies).
+   * - If omitted, all cookies in the webview's cookie store are cleared.
+   *
+   * @example
+   * ```ts
+   * // Clear all cookies
+   * win.clearCookies();
+   *
+   * // Clear cookies for a specific host
+   * win.clearCookies("example.com");
+   * ```
+   */
+  clearCookies(host) {
+    this._ensureOpen();
+    this._native.clearCookies(host);
+  }
+}
+function sanitizeForJs(input) {
+  return JSON.stringify(input).slice(1, -1).replace(/<\/script>/gi, "<\\/script>").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+export {
+  NativeWindow,
+  checkRuntime,
+  ensureRuntime,
+  loadHtmlOrigin,
+  sanitizeForJs
+};

package/native-window.d.ts

@@ -0,0 +1,264 @@
+/* eslint-disable */
+// Auto-generated type declarations for the native addon.
+// These will be overwritten by `napi build` but serve as
+// a reference during development.
+
+export interface WindowOptions {
+  /** Window title. Default: "" */
+  title?: string;
+  /** Inner width in logical pixels. Default: 800 */
+  width?: number;
+  /** Inner height in logical pixels. Default: 600 */
+  height?: number;
+  /** X position in screen coordinates */
+  x?: number;
+  /** Y position in screen coordinates */
+  y?: number;
+  /** Minimum inner width */
+  minWidth?: number;
+  /** Minimum inner height */
+  minHeight?: number;
+  /** Maximum inner width */
+  maxWidth?: number;
+  /** Maximum inner height */
+  maxHeight?: number;
+  /** Allow resizing. Default: true */
+  resizable?: boolean;
+  /** Show window decorations (title bar, borders). Default: true */
+  decorations?: boolean;
+  /** Transparent window background. Default: false */
+  transparent?: boolean;
+  /** Always on top of other windows. Default: false */
+  alwaysOnTop?: boolean;
+  /** Initially visible. Default: true */
+  visible?: boolean;
+  /** Enable devtools. Default: false */
+  devtools?: boolean;
+  /**
+   * Content Security Policy to inject at document start.
+   * When set, a `<meta http-equiv="Content-Security-Policy">` tag is injected
+   * before any page scripts run.
+   *
+   * **Limitation:** The CSP is applied via a `<meta>` tag at `DOMContentLoaded`,
+   * so scripts executing before that event are not restricted. Meta-tag CSP also
+   * cannot enforce `frame-ancestors` or `report-uri` directives. For stronger
+   * enforcement, serve pages via the custom protocol handler with a real HTTP
+   * `Content-Security-Policy` header.
+   *
+   * @example `"default-src 'self'; script-src 'self' 'unsafe-inline'"`
+   */
+  csp?: string;
+  /**
+   * Trusted origins for IPC messages at the native layer.
+   * When set, only messages whose source URL origin matches one of these
+   * entries are forwarded to the host. Messages from other origins are
+   * silently dropped.
+   *
+   * Each entry should be a full origin string (scheme + host + optional port),
+   * e.g. `"https://example.com"`. No trailing slash.
+   *
+   * @security Defense-in-depth. For application-level origin filtering,
+   * use `trustedOrigins` in `createChannel()` from `native-window-ipc`.
+   *
+   * @example `["https://myapp.com", "https://cdn.myapp.com"]`
+   */
+  trustedOrigins?: string[];
+  /**
+   * Allowed hosts for navigation restriction.
+   * When set and non-empty, ALL navigations (including `loadUrl()`, link
+   * clicks, form submissions, and redirects) are restricted to URLs whose
+   * host matches one of these patterns.
+   *
+   * Supports wildcard prefixes: `"*.example.com"` matches any subdomain
+   * of `example.com` and `example.com` itself.
+   *
+   * Internal navigations (`about:blank`, `loadHtml()` content) are always
+   * permitted. When unset or empty, all hosts are allowed.
+   *
+   * @example `["myapp.com", "*.cdn.myapp.com"]`
+   */
+  allowedHosts?: string[];
+  /**
+   * Allow the webview to access the camera when requested.
+   * Default: false (all camera requests are denied).
+   * @note Not yet enforced in the wry backend. The OS default (prompt user) applies.
+   */
+  allowCamera?: boolean;
+  /**
+   * Allow the webview to access the microphone when requested.
+   * Default: false (all microphone requests are denied).
+   * @note Not yet enforced in the wry backend. The OS default (prompt user) applies.
+   */
+  allowMicrophone?: boolean;
+  /**
+   * Allow the webview to use the File System Access API
+   * (`showOpenFilePicker`, `showSaveFilePicker`, `showDirectoryPicker`).
+   * Default: false (all file system access requests are denied).
+   * @note Not yet enforced in the wry backend. The OS default applies.
+   */
+  allowFileSystem?: boolean;
+
+  /**
+   * Path to a PNG or ICO file for the window icon (title bar).
+   * On macOS this option is silently ignored (macOS doesn't support
+   * per-window icons). Relative paths resolve from the working directory.
+   */
+  icon?: string;
+  /**
+   * Run the webview in incognito (private) mode.
+   * When `true`, no cookies, cache, or other browsing data are persisted to disk.
+   * Each window starts with a clean, isolated session and all data is discarded
+   * when the window closes.
+   *
+   * Platform notes:
+   * - **macOS**: Uses `WKWebsiteDataStore.nonPersistentDataStore()` (WKWebView).
+   * - **Windows**: Enables `IsInPrivateModeEnabled` on the WebView2 controller.
+   * - **Linux**: Uses a temporary in-memory WebContext (no persistent storage).
+   *
+   * Default: `false`
+   */
+  incognito?: boolean;
+}
+
+export class NativeWindow {
+  constructor(options?: WindowOptions);
+
+  /** Unique window ID */
+  readonly id: number;
+
+  // Content loading
+  loadUrl(url: string): void;
+  loadHtml(html: string): void;
+  evaluateJs(script: string): void;
+  postMessage(message: string): void;
+
+  // Window control
+  setTitle(title: string): void;
+  setSize(width: number, height: number): void;
+  setMinSize(width: number, height: number): void;
+  setMaxSize(width: number, height: number): void;
+  setPosition(x: number, y: number): void;
+  setResizable(resizable: boolean): void;
+  setDecorations(decorations: boolean): void;
+  setAlwaysOnTop(alwaysOnTop: boolean): void;
+  /** Set the window icon from a PNG or ICO file path. Ignored on macOS. */
+  setIcon(path: string): void;
+
+  // Window state
+  show(): void;
+  hide(): void;
+  close(): void;
+  focus(): void;
+  maximize(): void;
+  minimize(): void;
+  unmaximize(): void;
+  reload(): void;
+
+  // Event handlers
+  onMessage(callback: (message: string, sourceUrl: string) => void): void;
+  onClose(callback: () => void): void;
+  onResize(callback: (width: number, height: number) => void): void;
+  onMove(callback: (x: number, y: number) => void): void;
+  onFocus(callback: () => void): void;
+  onBlur(callback: () => void): void;
+  onPageLoad(callback: (event: "started" | "finished", url: string) => void): void;
+  onTitleChanged(callback: (title: string) => void): void;
+  onReload(callback: () => void): void;
+  onNavigationBlocked(callback: (url: string) => void): void;
+
+  // Cookie access
+  getCookies(url?: string): void;
+  onCookies(callback: (cookies: string) => void): void;
+  clearCookies(host?: string): void;
+
+  // Devtools
+  /** Open the browser devtools panel. Requires `devtools: true` in options. */
+  openDevtools(): void;
+  /** Close the browser devtools panel. */
+  closeDevtools(): void;
+  /** Check whether the devtools panel is currently open. */
+  isDevtoolsOpen(): boolean;
+}
+
+/** Initialize the native window system. Must be called once before creating any windows. */
+export function init(): void;
+
+/** Process pending native UI events. Call periodically (~16ms) to keep windows responsive. */
+export function pumpEvents(): void;
+
+/** Information about the native webview runtime. */
+export interface RuntimeInfo {
+  /** Whether the webview runtime is available. */
+  available: boolean;
+  /** The version string of the runtime, if detected. */
+  version?: string;
+  /** The current platform: "macos", "windows", "linux", or "unsupported". */
+  platform: "macos" | "windows" | "linux" | "unsupported";
+}
+
+/**
+ * Check if the native webview runtime is available.
+ *
+ * - **macOS**: Always returns available (WKWebView is a system framework).
+ * - **Windows**: Detects WebView2 via `GetAvailableCoreWebView2BrowserVersionString`.
+ * - **Linux**: Always returns available (WebKitGTK is required at build time).
+ * - **Other**: Returns `{ available: false, platform: "unsupported" }`.
+ */
+export function checkRuntime(): RuntimeInfo;
+
+/**
+ * Ensure the native webview runtime is available, installing it if necessary.
+ *
+ * - **macOS**: Returns immediately (WKWebView is always available).
+ * - **Windows**: If WebView2 is missing, downloads the Evergreen Bootstrapper
+ *   (~2MB) from Microsoft and runs it silently. Throws on failure.
+ * - **Linux**: Returns immediately (WebKitGTK is required at build time).
+ * - **Other**: Throws an error.
+ *
+ * @security This function downloads and executes a Microsoft-signed binary
+ * from the internet (Windows only). Authenticode signature verification is
+ * performed before execution; unverified binaries are never run.
+ *
+ * **Do not call in an elevated (Administrator) context without explicit user
+ * consent.** The silent installer applies system-wide. Prefer calling
+ * {@link checkRuntime} first to avoid unnecessary network requests when the
+ * runtime is already present.
+ */
+export function ensureRuntime(): RuntimeInfo;
+
+/**
+ * Escape a string for safe embedding inside a JavaScript string literal.
+ * Handles backslashes, quotes, newlines, null bytes, closing `</script>` tags,
+ * and Unicode line/paragraph separators (U+2028, U+2029).
+ *
+ * @security Use this when interpolating untrusted input into `win.unsafe.evaluateJs()` calls.
+ *
+ * @example
+ * ```ts
+ * import { sanitizeForJs } from "native-window";
+ *
+ * const userInput = 'He said "hello"\n<script>alert(1)</script>';
+ * win.unsafe.evaluateJs(`display("${sanitizeForJs(userInput)}")`);
+ * ```
+ */
+export function sanitizeForJs(input: string): string;
+
+/**
+ * Returns the origin of pages loaded via `loadHtml()`.
+ *
+ * Use this in `trustedOrigins` to restrict IPC messages to only accept
+ * messages from `loadHtml()` content.
+ *
+ * - macOS/Linux: `"nativewindow://localhost"`
+ * - Windows: `"https://nativewindow.localhost"`
+ *
+ * @example
+ * ```ts
+ * import { NativeWindow, loadHtmlOrigin } from "@nativewindow/webview";
+ *
+ * const win = new NativeWindow({
+ *   trustedOrigins: [loadHtmlOrigin()],
+ * });
+ * ```
+ */
+export function loadHtmlOrigin(): string;